Codebase Scanner

Scans the project and populates CLAUDE.md with structured sections that agents read at runtime. This is how generic agents learn your specific project.

When This Runs

• First install: install.sh --setup triggers a scan automatically
• On demand: User runs /scan to refresh after codebase changes
• Targeted: /scan services to only update the Local Dev Services section

What Gets Scanned

1. Local Dev Services

Detect running services and their configuration:

# Check for frontend frameworks
if [ -f "frontend/package.json" ] || [ -f "package.json" ]; then
    # Read scripts.dev from package.json
    # Detect framework: Next.js (port 3000), Vite (5173), CRA (3000), Vue (5173)
fi

# Check for backend frameworks
if [ -f "backend/requirements.txt" ] || [ -f "requirements.txt" ]; then
    # Detect FastAPI/Django/Flask
    # Default ports: FastAPI 8000, Django 8000, Flask 5000
fi
if [ -f "backend/pyproject.toml" ]; then
    # Read [tool.poetry] or [project] for framework hints
fi

# Check docker-compose.yml for service definitions
if [ -f "docker-compose.yml" ] || [ -f "docker-compose.yaml" ]; then
    # Extract service names, ports, build contexts
fi

# Check for Procfile (Heroku/Railway)
if [ -f "Procfile" ]; then
    # Extract web/worker commands
fi

Output the Local Dev Services table:

## Local Dev Services

| Service  | Port | Directory | Start Command |
|----------|------|-----------|---------------|
| Frontend | 3000 | frontend/ | cd frontend && npm run dev |
| Backend  | 8000 | backend/  | cd backend && source .venv/bin/activate && uvicorn app.main:app --reload --port 8000 |

2. Test Commands

Detect test frameworks and commands:

# Python tests
# Look for: pytest.ini, setup.cfg [tool:pytest], pyproject.toml [tool.pytest]
# Check for: ruff.toml, .flake8, mypy.ini

# JavaScript/TypeScript tests
# Look for: jest.config.*, vitest.config.*, playwright.config.*, cypress.config.*
# Read package.json scripts: test, lint, type-check, build

Output the Test Commands table:

## Test Commands

| What | Command | Directory |
|------|---------|-----------|
| Backend tests | pytest | backend/ |
| Backend lint | ruff check . | backend/ |
| Frontend tests | npm test | frontend/ |
| Frontend lint | npm run lint | frontend/ |
| Type check | npx tsc --noEmit | frontend/ |
| E2E tests | npx playwright test | frontend/ |

3. Infrastructure

Detect deployment configuration:

# Railway
[ -f "railway.json" ] || [ -f "railway.toml" ]

# Vercel
[ -f "vercel.json" ] || [ -f ".vercel/project.json" ]

# Fly.io
[ -f "fly.toml" ]

# AWS
[ -d ".aws" ] || [ -f "samconfig.toml" ] || [ -f "serverless.yml" ]

# Docker/Kubernetes
[ -f "Dockerfile" ] || [ -d "k8s" ]

# GitHub Actions
ls .github/workflows/*.yml 2>/dev/null

Output the Infrastructure table:

## Infrastructure

| Platform | Service | Notes |
|----------|---------|-------|
| Railway | backend, frontend | Auto-deploy on push to main |
| GitHub Actions | CI/CD | Lint, test, deploy |

Health endpoints: /health, /api/health

4. Domain

Scan for domain entities and business rules:

# Look for model files
# SQLAlchemy: models/*.py, models.py
# Django: */models.py
# Prisma: prisma/schema.prisma
# TypeORM: entities/*.ts

# Look for enum/status definitions
# State machines, workflow logic

Output the Domain section:

## Domain

{App name} is a {detected description} with the following core entities:
- {Entity1} (statuses: {enum values})
- {Entity2}

Business rules detected:
- {Rule from enum constraints, validators, etc.}

Section 5: Environments

Detect project environments and populate the ## Environments section in CLAUDE.md.

Detection steps:

1. Scan for .env.* files in project root:

   ls .env.* 2>/dev/null | grep -v '.env.example' | grep -v '.env.local'
   

   Extract environment names from suffixes (.env.staging → staging, .env.production → production).

2. Scan CI/CD configs for deploy targets:

   # GitHub Actions
   grep -r 'environment:' .github/workflows/*.yml 2>/dev/null | grep -oP 'environment:\s*\K\w+'
   

3. Scan deploy platform configs:

   • railway.json → Railway environments
   • vercel.json → preview + production
   • fly.toml / fly.*.toml → Fly.io environments
   • Terraform environments/ directories

4. ALWAYS include local as development environment using data from Local Dev Services table.

5. For each environment, populate:

   • Name: environment identifier
   • Type: development | staging | production | preview | canary
   • URL: from env files, deploy config, or <!-- TODO -->
   • Health: from Infrastructure section health endpoints or <!-- TODO -->
   • Deploy: trigger method (manual, branch push, CI/CD)
   • Branch: associated git branch or —

Output format in CLAUDE.md:

## Environments

| Name | Type | URL | Health | Deploy | Branch |
|------|------|-----|--------|--------|--------|
| local | development | http://localhost:{port} | /health | manual | — |
| {name} | {type} | {url} | {health} | {deploy} | {branch} |

Access notes: {platform details, env var file locations}

If no remote environments detected: Write only the local row with a comment:

<!-- No remote environments detected. Run /calibrate for full discovery with platform MCP queries. -->

How It Updates CLAUDE.md

1. Read existing CLAUDE.md
2. For each section being updated:
   • If the section exists with <!-- TODO: --> placeholders → replace with scanned data
   • If the section exists with real content → DO NOT overwrite (user has customized it)
   • If the section doesn't exist → append it
3. Write back the updated CLAUDE.md

CRITICAL: Never overwrite sections that the user has already filled in. Only populate empty/placeholder sections.

Arguments

User Input	Action
/scan	Full scan — all 5 sections
/scan services	Only scan and update Local Dev Services
/scan tests	Only scan and update Test Commands
/scan infra	Only scan and update Infrastructure
/scan domain	Only scan and update Domain
/scan environments	Only scan and update Environments

If No CLAUDE.md Exists

Create one from the template at ~/.claude-agents/templates/CLAUDE.md.template, then populate it with scanned data.