codebase-discovery

●─▶●─▶●─▶● codebase-discovery

The canonical reference flow. Point it at any repository and it produces a single self-contained HTML report describing the code that lives there — which packages exist, which entities and services they expose, and how the pieces fit together.

What it does

Four prompt steps, arranged as a fan-out over a shared inventory. The first step (inventory) walks the repository and emits a JSON handoff listing every package, its language, and its top-level structure. Two steps then run in parallel against that inventory: entities enumerates the data shapes (types, schemas, database tables) and services enumerates the runtime components (HTTP endpoints, background jobs, CLI commands). The final step (report) consumes all three handoffs and writes an HTML artifact that combines them into a single browsable document.

The flow is designed as a worked example of the Appendix A shape — one upstream node, two parallel branches, one downstream synthesis — and as a useful tool for onboarding a new engineer or PM onto an unfamiliar codebase.

Sample output

See examples/sample-output.html for a minimal skeleton of the report format. After a real run, artifacts/report.html contains:

• A header with the repository name and the date of the run.
• A "Packages" section listing every package with its purpose and primary language.
• An "Entities" section grouping the data shapes by package.
• A "Services" section grouping the runtime components by package.
• A closing "Architecture" section summarizing how the packages depend on each other.

The exact content varies per run because the summaries are generated by the model.

Estimated cost and duration

• Cost: $0.20 to $0.80 per run on the default sonnet model. Billed to your Claude subscription on Pro or Max — the dollar figure is an API-equivalent estimate, not a charge.
• Duration: 5 to 20 minutes, dominated by the two parallel discovery steps and the final report synthesis.

Both ranges match the relay metadata block in package.json and appear in the pre-run banner.

Install

From a clone of the Relay monorepo:

pnpm install
pnpm --filter @ganderbite/flow-codebase-discovery build

The build step compiles flow.ts to dist/flow.js, which is the artifact the CLI loads. When this flow is published to the catalog, users will instead run:

relay install codebase-discovery

Run

From the repo root:

relay run ./packages/flows/codebase-discovery --repoPath=./ --audience=dev

The path form (./packages/flows/codebase-discovery) tells the CLI to resolve the flow from a local directory. When the run completes, the generated report lands in .relay/runs/<runId>/artifacts/report.html.

Configuration

The flow accepts two inputs:

| Field | Type | Default | Notes | |---|---|---|---| | repoPath | string | (required) | Absolute or relative path to the repository to explore. | | audience | 'pm' \| 'dev' \| 'both' | 'both' | Controls the tone and depth of the generated report. |

There are no per-step model overrides. All four steps run on whichever model your ClaudeProvider selects by default.

Environment

This flow runs on your Claude subscription. Run claude /login once to authenticate before your first run.

Run relay doctor before your first run to confirm Node, the claude binary, auth state, and the .relay directory are all in order.

Customization

Fork the flow by copying the directory:

cp -r packages/flows/codebase-discovery ./my-flow
cd ./my-flow

Then edit:

• prompts/01_inventory.md — change how the walker enumerates packages.
• prompts/02_entities.md and prompts/03_services.md — change the parallel discovery prompts.
• prompts/04_report.md — change the HTML template or the sectioning.
• schemas/*.ts — change the shape of the handoffs the steps exchange.
• flow.ts — add a fifth step, add an input, or swap the artifact extension.

Rebuild with pnpm --filter my-flow build after any change to flow.ts or a schema file.

License

MIT. Copyright Ganderbite.