# Codebase Trainer

> Codebase Trainer (npm package `codebase-trainer`, CLI `cb-trainer`) is an open-source, MIT-licensed local MCP server and CLI for AI coding agents such as Claude Code, Cursor and VS Code. One tool call returns every file a feature touches, from the UI and API client to the route handler, service, database model, auth checks and tests, with file:line evidence, inside a token budget. It runs fully offline with no API keys, needs Node.js 22 or later, and is set up with `npx codebase-trainer setup` in a repository.

Key facts, measured on a public benchmark of 104 hand-labelled questions across four open-source apps (Next.js + Prisma, Express + Prisma, NestJS + TypeORM, a tRPC monorepo), compared with an agent that greps and reads files:

- Right file in the top 5 results: 84% (grep: 66%); 94% with the optional local neural model.
- Median tokens read to reach the right file: 1,062 (grep: 3,974), about 3.7 times fewer.
- `feature_slice` returns 83% of a feature's needed files in one call, in a median 4,552 tokens; 33% of the files it returns were labelled as needed.
- Test selection caught 220 of 220 failing tests in a mutation test while skipping about 60% of the test suite per change.
- Search takes 43 ms at p50 and 50 ms at p95 on a 10,000-file repository.
- Best for JavaScript and TypeScript web apps (Next.js, Express, NestJS, tRPC, Prisma, Drizzle, TypeORM); Python is partly supported.

The eight MCP tools: `search`, `feature_slice`, `trace_flow`, `impact`, `review_diff`, `api_map`, `codebase_overview`, `quality_scan`. Every tool accepts `budget_tokens`.

## Docs

- [Quick start](https://codebase-trainer.vercel.app/docs.html#quickstart): one command, restart the editor, ask.
- [Connect your editor](https://codebase-trainer.vercel.app/docs.html#clients): config for Claude Code (.mcp.json), Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json) and Windsurf.
- [The eight tools](https://codebase-trainer.vercel.app/docs.html#tools): what each returns, with real output.
- [CLI reference](https://codebase-trainer.vercel.app/docs.html#cli): every `cb-trainer` command.
- [Configuration](https://codebase-trainer.vercel.app/docs.html#config): `codebase-trainer.yaml`, environment variables, what is indexed.
- [CI and code scanning](https://codebase-trainer.vercel.app/docs.html#ci): GitHub Action and SARIF output.
- [Benchmark and limits](https://codebase-trainer.vercel.app/docs.html#benchmark): methodology, every number, and where it is weak.
- [Troubleshooting](https://codebase-trainer.vercel.app/docs.html#faq)

## Project

- [Source code on GitHub](https://github.com/om0852/codebase-trainer)
- [npm package](https://www.npmjs.com/package/codebase-trainer)
- [Benchmark data and scripts](https://github.com/om0852/codebase-trainer/tree/main/bench)

## Optional

- [Full README as plain text](https://codebase-trainer.vercel.app/llms-full.txt)
- [Implementation plan with measured results per phase](https://github.com/om0852/codebase-trainer/blob/main/docs/IMPLEMENTATION_PLAN.md)