Codebase Viewer
Produces a structured codebase map — not a file listing but an annotated architecture view with entry points, dependency flow, test coverage, and danger zones.
Workflow
1. TREE
Generate directory structure (2-3 levels deep) with role annotations:
- Each directory gets a one-line role description
- Mark directories as: source, test, config, docs, build, generated, vendored
- Flag empty directories and their likely purpose
- Respect .gitignore — skip node_modules, vendor, build outputs
2. ENTRY
Identify entry points — where execution begins:
main functions (Go, Rust, Python)
- CLI command handlers
- HTTP route registrations
- Event listeners and subscribers
- Scheduled task definitions
- Test suites (as secondary entry points)
3. DEPS
Map the dependency graph:
- External dependencies from go.mod / package.json / Cargo.toml / requirements.txt
- Internal package import relationships
- Circular dependency detection
- Heavyweight dependencies (large transitive dep trees)
4. TESTS
Scan for test coverage:
- Which packages/directories have test files
- Test-to-source ratio per directory
- Packages with zero tests (flag as risk)
- Test patterns in use (unit, integration, e2e, benchmark)
5. PATTERNS
Identify architectural patterns:
- Clean architecture / hexagonal / onion (ports-and-adapters)
- MVC / MVVM
- Microservice boundaries
- Monolith with internal module separation
- Event-driven / message-passing
- Repository pattern / service layer
6. DRAGONS
Flag areas of concern — severity-labeled:
- CRITICAL: Files >1000 lines, circular dependencies, hardcoded secrets
- WARNING: Files >500 lines, deeply nested code (>4 levels), TODO/FIXME density >5 per file
- INFO: No tests for package, outdated dependencies, unused imports
7. CONTRACTS
Identify interfaces and API boundaries:
- Go interfaces and their implementors
- HTTP API surface (routes, methods, request/response types)
- gRPC / protobuf definitions
- Event schemas
- Configuration contracts (env vars, config files)
8. REPORT
Produce structured codebase map as markdown:
- Header with repo name, language, size metrics
- Each section from above as a headed section
- Summary statistics table (files, lines, packages, test coverage %)
9. SUGGEST (optional, only if requested)
Based on findings, suggest 3 high-value improvements:
- Highest-risk dragon to address first
- Biggest test coverage gap
- Most impactful architectural improvement
Reading Rules
- For files >50KB: use Grep to find relevant sections, then read with offset/limit
- Never read files >200KB in one shot
- Check file size with wc -c before reading large files
- Prefer targeted reads over full-file reads for analysis
1---2name: codebase-viewer-23description: "Structured codebase intelligence: directory tree with roles, entry points, dependency graph, test coverage map, and annotated 'here be dragons' warnings."4---56# Codebase Viewer78Produces a structured codebase map — not a file listing but an annotated architecture view with entry points, dependency flow, test coverage, and danger zones.910## Workflow1112### 1. TREE13Generate directory structure (2-3 levels deep) with role annotations:14- Each directory gets a one-line role description15- Mark directories as: source, test, config, docs, build, generated, vendored16- Flag empty directories and their likely purpose17- Respect .gitignore — skip node_modules, vendor, build outputs1819### 2. ENTRY20Identify entry points — where execution begins:21- `main` functions (Go, Rust, Python)22- CLI command handlers23- HTTP route registrations24- Event listeners and subscribers25- Scheduled task definitions26- Test suites (as secondary entry points)2728### 3. DEPS29Map the dependency graph:30- External dependencies from go.mod / package.json / Cargo.toml / requirements.txt31- Internal package import relationships32- Circular dependency detection33- Heavyweight dependencies (large transitive dep trees)3435### 4. TESTS36Scan for test coverage:37- Which packages/directories have test files38- Test-to-source ratio per directory39- Packages with zero tests (flag as risk)40- Test patterns in use (unit, integration, e2e, benchmark)4142### 5. PATTERNS43Identify architectural patterns:44- Clean architecture / hexagonal / onion (ports-and-adapters)45- MVC / MVVM46- Microservice boundaries47- Monolith with internal module separation48- Event-driven / message-passing49- Repository pattern / service layer5051### 6. DRAGONS52Flag areas of concern — severity-labeled:53- **CRITICAL**: Files >1000 lines, circular dependencies, hardcoded secrets54- **WARNING**: Files >500 lines, deeply nested code (>4 levels), TODO/FIXME density >5 per file55- **INFO**: No tests for package, outdated dependencies, unused imports5657### 7. CONTRACTS58Identify interfaces and API boundaries:59- Go interfaces and their implementors60- HTTP API surface (routes, methods, request/response types)61- gRPC / protobuf definitions62- Event schemas63- Configuration contracts (env vars, config files)6465### 8. REPORT66Produce structured codebase map as markdown:67- Header with repo name, language, size metrics68- Each section from above as a headed section69- Summary statistics table (files, lines, packages, test coverage %)7071### 9. SUGGEST (optional, only if requested)72Based on findings, suggest 3 high-value improvements:73- Highest-risk dragon to address first74- Biggest test coverage gap75- Most impactful architectural improvement7677## Reading Rules78- For files >50KB: use Grep to find relevant sections, then read with offset/limit79- Never read files >200KB in one shot80- Check file size with wc -c before reading large files81- Prefer targeted reads over full-file reads for analysis