Codebase Analyzer

Analyze any codebase and produce structured metrics with configurable patterns and multiple output formats.

When to use this skill

Use this skill when the user wants to:

• Analyze a codebase for size, structure, and quality metrics
• Get line counts broken down by category (code, tests, docs, scripts, plans)
• See a language breakdown with code and comment lines per language
• Check the test:code ratio
• Find TODO and FIXME annotations across the codebase
• Identify large files that may need refactoring
• Review git churn hotspots (most frequently changed files)
• Export analysis results as JSON or Markdown for docs, PRs, or CI pipelines

Prerequisites

Before running any analysis, ensure:

1. Python 3.10+ is available
2. Dependencies are installed via the setup script
3. (Optional) git is installed if the user wants churn metrics or git-tracked file discovery

No external services, API tokens, or credentials are required. This skill is entirely local and read-only.

Configuration

Configuration is optional. The analyzer works out of the box with sensible defaults. To customize, create a .codebase-analysis.yaml file in the repository root. See references/CONFIG.md for the full schema.

If no config file exists, ask the user if they would like to create one before running the analysis. To help them decide:

1. Quickly inspect the codebase structure (top-level directories, common file types, presence of test/script/doc directories)
2. Suggest a tailored .codebase-analysis.yaml based on what you find — for example, if the repo has a src/ directory with tests in __tests__/, or uses non-standard script directories, reflect that in the suggestion
3. Present the suggested config to the user and let them accept, modify, or skip it
4. If they skip, proceed with built-in defaults

To provide a starting config template, copy the default:

cp <skill_dir>/assets/default-config.yaml <repo_root>/.codebase-analysis.yaml

Pre-flight checks

Before running ANY operation, run the preflight script once. It validates the entire environment in a single pass and reports a clear summary.

python3 <skill_dir>/scripts/analyzer_preflight.py

Optionally, pass --path to also validate the target repository:

python3 <skill_dir>/scripts/analyzer_preflight.py --path <repo_root>

The script checks:

1. Python 3.10+ is available
2. Virtual environment exists at <skill_dir>/.codebase-analyzer-venv/
3. Core dependencies (PyYAML, Rich) are importable
4. Web dependencies (Streamlit, pandas) are importable
5. git is available (optional — always passes, reports status)
6. Skill scripts are all present
7. Target path exists and is a directory (only when --path is provided)
8. Config file presence in the target repo (optional — always passes, reports status)

If the venv does not exist or dependencies are missing, run the setup script:

python3 <skill_dir>/scripts/analyzer_setup_env.py

After setup, all subsequent script commands must use the venv Python:

<skill_dir>/.codebase-analyzer-venv/bin/python <skill_dir>/scripts/analyze.py --path . --output terminal

Workflow

Step 1 — Run pre-flight checks

Run the preflight script and read the output. If any required check fails, resolve it before proceeding.

python3 <skill_dir>/scripts/analyzer_preflight.py --path <repo_root>

Step 2 — Ask about configuration

Check if a .codebase-analysis.yaml already exists in the repo root.

• If it exists, inform the user and proceed with it.
• If it does not exist, ask the user whether they want to create a custom config before running:
  1. Inspect the codebase: list top-level directories, identify test directories, script directories, doc files, and any non-standard project conventions
  2. Generate a suggested .codebase-analysis.yaml tailored to the codebase and present it to the user
  3. If the user accepts (with or without edits), write the config file to <repo_root>/.codebase-analysis.yaml
  4. If the user declines, proceed with built-in defaults

Step 3 — Ask about output format

Ask the user which output format they prefer:

• terminal — Rich-formatted tables printed to the console (best for interactive use)
• json — structured JSON to stdout (best for CI pipelines or programmatic consumption)
• markdown — Markdown report to stdout (best for docs, PRs, or saving to a file)
• web — interactive Streamlit dashboard in the browser with charts, tables, and visual metrics

Also ask:

• Which path to analyze (default: current working directory)
• Which sections to include (default: all, not applicable for web). Available sections: summary, categories, languages, file-distribution, large-files, todos, churn

Step 4 — Run analysis

<skill_dir>/.codebase-analyzer-venv/bin/python <skill_dir>/scripts/analyze.py \
  --path <repo_root> \
  --output <terminal|json|markdown|web> \
  --sections <comma-separated-list-or-all>

Optional flags:

• --config <path> — path to a custom config file (default: <repo_root>/.codebase-analysis.yaml)

Note: When --output web is used, the script launches a Streamlit server and opens the dashboard in the browser. The --sections flag is ignored for web output (all sections are always shown). The command is non-blocking — the server runs until the user stops it (Ctrl+C).

Step 5 — Present results

• For terminal output, the script renders directly to the console
• For json output, capture stdout and present the structured data to the user, or pipe it to a file
• For markdown output, capture stdout and present it or write to a file for documentation
• For web output, the dashboard is already open in the browser — no further action needed

Step 6 — Offer follow-up actions

After analysis, suggest relevant next steps:

• If test:code ratio is low: suggest areas that need more tests
• If there are many TODOs/FIXMEs: offer to list them with file locations
• If large files are found: suggest candidates for refactoring
• If the user wants to save results: offer JSON or Markdown export
• If the user wants to customize patterns: help create a .codebase-analysis.yaml

Operations

Full analysis (all sections)

<skill_dir>/.codebase-analyzer-venv/bin/python <skill_dir>/scripts/analyze.py \
  --path <repo_root> --output terminal

Specific sections only

<skill_dir>/.codebase-analyzer-venv/bin/python <skill_dir>/scripts/analyze.py \
  --path <repo_root> --output terminal --sections summary,languages,todos

JSON export (for CI or programmatic use)

<skill_dir>/.codebase-analyzer-venv/bin/python <skill_dir>/scripts/analyze.py \
  --path <repo_root> --output json > analysis.json

Markdown report (for docs or PRs)

<skill_dir>/.codebase-analyzer-venv/bin/python <skill_dir>/scripts/analyze.py \
  --path <repo_root> --output markdown > ANALYSIS.md

Custom config

<skill_dir>/.codebase-analyzer-venv/bin/python <skill_dir>/scripts/analyze.py \
  --path <repo_root> --config custom-config.yaml --output terminal

Web dashboard (interactive browser UI)

<skill_dir>/.codebase-analyzer-venv/bin/python <skill_dir>/scripts/analyze.py \
  --path <repo_root> --output web

This launches a Streamlit server and opens an interactive dashboard in the browser with:

• Overview metrics (files, lines, code, comments, test:code ratio, docs:code ratio)
• Code vs Tests comparison with charts
• Language breakdown with tabs (All Files / Code Only)
• File size distribution histogram
• Large files and TODO/FIXME tracking
• Category breakdown (code, tests, docs, scripts, plans, test data)

The dashboard caches analysis results for 60 seconds. Stop the server with Ctrl+C.

Available sections

Important rules

1. This skill is read-only. It never modifies user code, config files, or repository state.
2. No credentials or external services required. Everything runs locally.
3. Config is optional. Never block on missing config — defaults work for any codebase.
4. Git is optional. If unavailable, directory walking is used and churn is skipped silently.
5. Present results clearly. Use the output format the user prefers. Default to terminal for interactive use.

Output format details

See references/REPORT_FORMAT.md for sample outputs, section descriptions, and guidance on interpreting key metrics (test:code ratio thresholds, comment percentage guidelines, churn interpretation).

Error handling

The scripts print descriptive error messages to stderr with fix instructions. Exit codes: 0 = success, 1 = dependency error, 2 = config/path error.

Troubleshooting

Future capabilities