Codebase Trainer docs

Quick start

Run one command in the root of your repository, restart your editor, and ask your agent a question.

npx codebase-trainer setup

Use codebase-trainer feature_slice to show me everything involved in password reset,
then tell me which files I need to change to add rate limiting.

Requirements

Connect your editor

npx codebase-trainer setup does this for you. To do it by hand, add the server to your client's config. The server indexes the folder it is started in, so use project-level configs where your client supports them.

{
  "mcpServers": {
    "codebase-trainer": { "command": "npx", "args": ["-y", "codebase-trainer", "mcp"] }
  }
}

claude mcp add --scope project codebase-trainer -- npx -y codebase-trainer mcp

{
  "mcpServers": {
    "codebase-trainer": { "command": "npx", "args": ["-y", "codebase-trainer", "mcp"] }
  }
}

{
  "servers": {
    "codebase-trainer": { "type": "stdio", "command": "npx", "args": ["-y", "codebase-trainer", "mcp"] }
  }
}

Config generator

Pick your editor and copy the file, or run npx codebase-trainer setup to write it for you.

{
  "mcpServers": {
    "codebase-trainer": {
      "command": "npx",
      "args": [
        "-y",
        "codebase-trainer",
        "mcp"
      ]
    }
  }
}

The eight tools

Every tool takes budget_tokens and reports what it cut. The examples are real responses from the published 2.0.0 package on the benchmark apps, shortened where marked.

{
  "semanticResults": [
    {
      "filePath": "src/app/routes/article/article.controller.ts",
      "startLine": 152, "endLine": 163, "kind": "code", "score": 18.2,
      "snippet": "const comments = await getCommentsByArticle(req.params.slug, req.auth?.user?.id); …"
    },
    {
      "filePath": "src/app/routes/article/article.service.ts",
      "startLine": 476, "endLine": 487, "kind": "code", "score": 17.7,
      "snippet": "const comment = await prisma.comment.create({ …"
    }
  ],
  "mode": "lexical",
  "index": { "fullRebuild": false, "refreshedFiles": 0, "removedFiles": 0 },
  "budget": { "tokens": 348, "budgetTokens": 8000 }
}

Using it with an agent

Agents pick tools from their descriptions, so naming the tool helps the first few times. These are the moments it pays off most.

How it works

Everything runs inside one local Node.js process. No API keys, no vector database, no language server, no telemetry.

CLI reference

Every command takes -d <path> for the repo (default: current folder), and most take --json. Run cb-trainer <command> --help for all options. With npx, use npx codebase-trainer <command>.

Configuration

Nothing needs configuring. For team-wide settings, commit a codebase-trainer.yaml at the repo root. Unknown or malformed settings are ignored and reported by codebase_overview.

exclude: ["generated/**", "**/*.snap"]   # on top of .gitignore and .codebaseignore
embeddings: false                         # or { enabled: true, model: Xenova/all-MiniLM-L6-v2 }
auth:
  guards: [ensureTeamMember]              # your own auth middleware, for the permission map
  publicPaths: ["/api/status"]            # routes that are public by design
budgets:
  defaultTokens: 8000                     # per tool call
  featureSliceTokens: 6000

What is indexed

Source, config and docs files up to 500 KB that are not excluded by .gitignore, .git/info/exclude, .codebaseignore or the built-in list (node_modules, dist, build, .next, virtualenvs, caches). Credential files such as .env and *.pem are never indexed, and secrets inside indexed files are redacted.

Environment variables

Files it writes

Everything generated lives in .codebase/ (index, conventions, reports); add it to .gitignore. Commit codebase-trainer.yaml and your editor's MCP config instead.

Optional neural search

A small local model whose ranking is fused with keyword search by reciprocal rank fusion. It runs on your CPU; nothing leaves your machine. Without opting in, nothing is downloaded.

npm install @huggingface/transformers     # optional peer dependency (~300 MB with its ONNX runtime)
cb-trainer embeddings enable              # downloads MiniLM-L6 (23 MB) once and embeds the index
cb-trainer embeddings status
cb-trainer embeddings disable

Four small models were compared on the tuning questions (MiniLM-L6, bge-small, arctic-embed-xs, jina-v2-small); MiniLM-L6 was best and the gain held on the 28 held-out questions. Encrypted indexes keep neural search off, because vectors would be stored unencrypted. Teams can switch it on for everyone with embeddings: true in codebase-trainer.yaml.

CI and code scanning

Review every pull request with the same checks and see findings in GitHub's Code Scanning tab.

name: codebase-trainer review
on: pull_request
permissions:
  contents: read
  security-events: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - uses: om0852/codebase-trainer@v1
        with: { base: "origin/${{ github.base_ref }}" }
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with: { sarif_file: codebase-trainer.sarif }

Without the action: npx codebase-trainer review --base origin/main --format sarif --output review.sarif. The step fails on error-severity findings (such as a committed secret); set fail-on-error: false on the action to only report.

Benchmark and limits

104 hand-labelled questions on four open-source apps pinned to exact commits: taxonomy (Next.js + Prisma), node-express-realworld (Express + Prisma), nestjs-realworld (NestJS + TypeORM) and create-t3-turbo (tRPC monorepo). The baseline is what an agent does without an index: grep the question's words and open the files with the most matches. Settings were tuned on 76 questions and confirmed on 28 held out.

Upgrading from 1.x

• Node 22 or later is required.
• The index moves from .codebase/embeddings.json to .codebase/index.sqlite and is rebuilt automatically on first use.
• MCP tools have new names. The old names keep working through 2.x and log a deprecation note once per session.

Troubleshooting and FAQ