kalpeshgamit/codebase-pilot

1. What this repo is

- codebase-pilot is a local-first Node.js/TypeScript toolchain for preparing codebases as AI context. It does not call AI APIs; instead it scans a repository, scores and compresses it, and exposes the result through CLI, MCP, Claude Code plugin assets, and a web dashboard.

2. Primary entry points

- The main executable is src/bin/codebase-pilot.ts, which fans out into command modules under src/cli/.

- The same core capabilities are also surfaced through src/mcp/server.ts for MCP clients and src/ui/server.ts for the dashboard.

- The plugin/ tree packages Claude Code plugin metadata, hooks, and skills so the same engine can be driven from inside an AI IDE workflow.

3. Core pipeline

- The central data flow is: scan → detect → pack → compress → format → count/record.

- src/scanner/ discovers repository structure, languages, frameworks, databases, test runners, and existing project config.

- src/packer/ collects selected files, applies token accounting, and formats output as Markdown or XML.

- src/compress/ reduces prompt size by preserving signatures and structure while folding implementation bodies.

4. Repository intelligence layer

- src/intelligence/ is the decision-making layer that powers “what matters” selection.

- It includes incremental change detection, git-derived signals, import/dependency analysis, task selection, and graph visualization support.

- This layer is what enables commands like affected-only packing, prune-by-import-graph, blast-radius analysis, and compare-diff token impact.

5. Security boundary

- src/security/ provides a standalone secret scanner using a large pattern set.

- Security scanning is both a first-class CLI operation and an automatic gate in the packing flow: files containing secrets are excluded from packed output.

- This is an important architectural boundary because it separates “context optimization” from “do not leak credentials.”

6. Registries and detection catalogs

- src/registry/ stores curated knowledge about languages, frameworks, databases, and test tools.

- These registries are used by the scanner to classify projects and by generators to produce project-specific configuration.

- In diagrams, this is the metadata/catalog subsystem feeding detection and setup.

7. Local persistence and search

- src/memory/db.ts and src/scanner/database.ts indicate local database-backed storage for usage history and indexing.

- The README also describes full-text search with ranking and snippets, so there is a local searchable data layer behind commands like search, stats, compare, and dashboard views.

- The architecture is designed around local state accumulation over time, not remote services.

8. Web dashboard and daemon

- src/ui/ is a separate runtime path for the always-on dashboard and background service.

- src/ui/server.ts, ws.ts, and pack-worker.ts suggest a Node server serving pages, pushing real-time updates over WebSockets, and offloading packing work to a worker process.

- src/ui/daemon.ts plus the service command indicate a long-lived local daemon model that records usage continuously.

9. MCP and agent integration

- src/mcp/server.ts exposes the engine as MCP tools and prompts, so other AI clients can consume scanning, packing, token counting, health checks, and file listing.

- src/agents/generator.ts plus plugin/skills/codebase-pilot/ represent the agent orchestration layer used by Claude Code workflows.

- The boundary here is: the core engine stays reusable, while client-specific integration is layered on top.

10. Project configuration generation

- src/generators/ creates repo-local AI tooling artifacts such as CLAUDE.md, agents.json, ignore files, slash-command definitions, and platform rule files.

- This subsystem turns scan results into installed project configuration, which is why init is a high-level orchestration command.

- It also validates output before writing, so generation is treated as a controlled boundary rather than ad hoc file edits.

11. CLI command families

- The CLI is organized around distinct operational modes: initialization, scanning, packing, token analysis, impact analysis, security scanning, visualization, dashboard control, service management, and repair/eject utilities.

- compare, impact, tokens, eval, health, fix, and eject are not separate engines; they are views and maintenance actions over the same scanned/packed local data.

12. Distribution and integration surface

- The repo also ships deployment/integration assets: GitHub Actions, Homebrew formula, install script, and Claude Code marketplace metadata.

- These do not change the core architecture, but they show that the product is meant to be installed as a CLI, embedded as a plugin, run as a daemon, or invoked in CI.

13. Repository-level architecture summary

- The main boundary is between core analysis engines (scanner, intelligence, compress, packer, security, registry) and presentation/integration layers (cli, ui, mcp, plugin, generators).

- Data typically flows from repository contents into scan/index state, then into packed/compressed AI context, and finally into local persistence and UI/MCP outputs.

- Everything is intentionally local and offline, with no external cloud dependency in the runtime path.