codebase-pilot

Stop burning tokens. Start coding smarter.
AI context engine — pack, compress, optimize any codebase for LLMs. Zero cloud. Zero lock-in.

Installation

/plugin marketplace add kalpeshgamit/codebase-pilot
/plugin install codebase-pilot

npm install -g codebase-pilot-cli

npx codebase-pilot-cli init

brew install kalpeshgamit/codebase-pilot/codebase-pilot-cli

curl -fsSL https://raw.githubusercontent.com/kalpeshgamit/codebase-pilot/main/install.sh | bash

npm uninstall -g codebase-pilot-cli

Quick Start

# 1. Install
npm install -g codebase-pilot-cli

# 2. Set up your project
cd your-project
codebase-pilot init

# 3. Pack + compress for AI context
codebase-pilot pack --compress --copy

# 4. Scan for secrets before committing
codebase-pilot scan-secrets

# 5. See cost savings
codebase-pilot compare   # "+16K tokens (+$0.05/prompt)"

# 6. Open web dashboard
codebase-pilot ui    # → http://localhost:7456 (health score, trend charts, $)

# 7. (Optional) Install as always-on service
codebase-pilot service   # auto-starts on login, tracks forever

How It Works

Architecture Pipeline Your codebase goes through scan → detect → pack → compress → security scan → output. 98K tokens becomes 7K.	Token Savings Compression alone saves 70%. Add agent scoping for 93% reduction.
Blast Radius Analysis Change a file → see every dependent, transitive import, and affected test. Risk scored 0–100.	Agent Layer Architecture 7 layers — haiku for extraction, sonnet for implementation, opus for review gates.
Multi-Platform Support — one command generates configs for Claude Code, Cursor, Windsurf, and OpenAI Codex.

Token Savings

The tokens command tracks your actual savings over time:

  Savings estimate (per session):
    Without codebase-pilot:   ~98,798 tokens
    With pack --compress:      ~29,274 tokens
    Pilot saves:              ~69,524 tokens per session

  Your savings (from pack runs):
    Today:      3 sessions  — ~92,232 tokens saved
    This week:  5 sessions  — ~147,498 tokens saved

Web Dashboard

codebase-pilot ui               # → http://localhost:7456
codebase-pilot ui --stop        # stop daemon
codebase-pilot ui --status      # check status + diagnostics
codebase-pilot ui --port 8080   # custom port

Port 7456 = PILOT on phone keypad. Runs as background daemon with real-time WebSocket updates. Auto-fallback to next port if 7456 is in use.

Always-On Daemon

Install as a system service — tracks token usage even when the dashboard is closed:

codebase-pilot service           # install (auto-starts on login)
codebase-pilot service --status  # check if running
codebase-pilot service --restart # restart daemon
codebase-pilot service --uninstall

Open the dashboard days or weeks later — all your token history is already there.

Dashboard

Live stat cards (K/M/B abbreviated), savings chart, recent sessions — auto-updates via WebSocket.

Prompts (All Sessions)

User prompts from Claude Code + pack sessions with git context (branch, commit, dirty files). Click any row for detail drawer with token breakdown + savings bar.

Projects (System-Wide)

All projects in one view — sessions, tokens saved, efficiency per project.

Import Graph

Interactive D3.js force-directed graph. Nodes sized by tokens, colored by module. Drag, zoom, search.

Search

Full-text search with BM25 ranking. Highlighted matches with file path + line number.

Agents

Layer architecture, model assignment, context paths, dependencies.

Files

All files with token counts, language tags, percentage of total.

Security

Pattern categories, risk levels, detected secrets — side by side.

Features

Commands

codebase-pilot init [--platform cursor,windsurf,codex]  # scan + generate configs + MCP + hooks
codebase-pilot scan                                      # re-detect + update
codebase-pilot pack [--compress] [--agent <name>]        # pack for AI context
codebase-pilot pack --compress --affected                # incremental — only changed files
codebase-pilot pack --compress --prune <file>            # minimum context via import graph
codebase-pilot pack --compress --dry-run                 # preview without writing output
codebase-pilot scan-secrets [--path <dir>]               # security scan — 180 patterns
codebase-pilot tokens [--agent <name>]                   # token breakdown + savings
codebase-pilot impact [--file <path>]                    # blast radius analysis
codebase-pilot search <query>                            # full-text search
codebase-pilot visualize                                 # D3.js import graph HTML
codebase-pilot ui [--stop | --status | --port N]         # web dashboard (port 7456)
codebase-pilot service [--uninstall | --status]          # install as system service
codebase-pilot serve                                     # MCP server (stdio)
codebase-pilot watch                                     # file watcher
codebase-pilot stats [--global]                          # usage history
codebase-pilot eval                                      # benchmarks
codebase-pilot compare                                   # token impact of changes (+$0.05/prompt)
codebase-pilot health                                    # validate agent setup
codebase-pilot fix                                       # auto-repair stale paths
codebase-pilot eject                                     # remove dependency

Blast Radius

Trace the impact of any file change across your codebase:

codebase-pilot impact --file src/types.ts

  Risk: HIGH (53/100)

  Direct dependents (18):
    src/agents/generator.ts
    src/mcp/server.ts
    src/packer/index.ts
    ...

  Affected tests (5):
    tests/agents/generator.test.ts
    tests/cli/pack.test.ts
    ...

  Total affected: 27 files

MCP Server

Expose codebase-pilot to any MCP-compatible AI tool:

codebase-pilot serve

Tools: scan_project, pack_codebase, count_tokens, health_check, scan_secrets, list_agents, get_agent, detect_languages, get_savings, list_files

Prompts: review, onboard, optimize

{
  "mcpServers": {
    "codebase-pilot": {
      "command": "codebase-pilot",
      "args": ["serve"]
    }
  }
}

Same config works for Cursor (.cursor/mcp.json) and other MCP clients.

Security Scanner

codebase-pilot scan-secrets           # scan current project
codebase-pilot scan-secrets --path .  # specify directory

180 patterns across 15 categories. Runs automatically on every pack — files with detected secrets are excluded from output.

Code Compression

Keeps function signatures, folds bodies. Claude still understands the full API surface.

// Before (150 tokens)
export async function createUser(data: UserInput): Promise<User> {
  const validated = schema.parse(data);
  const user = await db.user.create({ data: validated });
  await sendWelcomeEmail(user.email);
  return user;
}

// After --compress (20 tokens)
export async function createUser(data: UserInput): Promise<User> { /* ... */ }

Supports: TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, PHP.

Incremental Packing

Pack only what changed — save tokens on every iteration:

# First run indexes everything, subsequent runs are incremental
codebase-pilot pack --compress --affected

  Changes detected:
    + 2 added
    ~ 3 modified
  Packing 5 affected files...
  Tokens: ~1,200 (compressed from ~4,800, 75% reduction)

# Minimum context — only files reachable via import graph
codebase-pilot pack --compress --prune src/types.ts

  Pruning to files reachable from: src/types.ts
  Files: 31 packed (from 95 total)
  Tokens: ~7,453 (80% reduction)

# Preview without writing output
codebase-pilot pack --compress --dry-run

  [DRY RUN] Preview — no files written
  Files: 95 | Raw: ~125K | Packed: ~35K (72% reduction)
  Top files by tokens:
    26,039 tokens  src/ui/pages.ts
     5,443 tokens  src/security/patterns.ts
     ...

Claude Code Plugin

Install as a Claude Code plugin for built-in skills and auto-tracking:

/plugin marketplace add kalpeshgamit/codebase-pilot
/plugin install codebase-pilot

4 Skills:

• /pack-context — Pack & compress with --affected, --prune, --dry-run
• /impact-analysis — Blast radius for any file change
• /scan-secrets — Security scan (180 patterns)
• /token-budget — Token counts and savings planning

Auto-tracking: Every prompt you type in Claude Code is captured and displayed on the web dashboard (Prompts page) with git context (branch, commit, dirty files).

MCP Server: Auto-configured — 10 tools available to Claude Code.

Prompt Tracking

Track every AI interaction with full git context:

# init auto-configures hooks + MCP
codebase-pilot init
codebase-pilot ui
# Open http://localhost:7456/prompts

The Prompts page shows:

• User Prompts — actual text typed in Claude Code (via hooks)
• Pack Sessions — token usage with branch, commit, duration, savings
• Click any row — detail drawer with git context + savings breakdown

Privacy & Security — What We Don't Track

codebase-pilot does NOT intercept, proxy, or call any AI provider APIs.

We don't track AI response tokens, API costs, or model outputs. That data belongs to your AI provider (Anthropic, OpenAI, etc.) and accessing it would require API key access — a security risk we refuse to take.

What we track: Only your local codebase context — file tokens, compression savings, git state, and prompt text (via opt-in Claude Code hooks). Everything stays on your machine. Zero cloud. Zero telemetry.

Our goal: Help you reduce the tokens you send to AI tools, not monitor what AI tools send back.

Cost Estimation

Every token count now shows real dollar value:

codebase-pilot pack --compress

  Files:    95 packed
  Tokens:   ~35,388 (compressed from ~125,228, 72% reduction)
  Cost:     ~$0.11 per prompt (saved ~$0.27)

Dashboard shows weekly/monthly cost: $36.25 saved · $18.23 used

Based on Claude Sonnet input pricing ($3/1M tokens). Works with any model — costs scale proportionally.

Compare Changes

See the token impact of your recent changes:

codebase-pilot compare

  Changes:
    + 8 added (3,630 tokens)
    ~ 17 modified (74,562 tokens now, was 61,347)

  Token impact: +16,845 tokens (+$0.05 per prompt)
  Total now:    156,334 tokens (~$0.47/prompt)

  Top changes by tokens:
    ~ 39,257 tokens  src/ui/pages.ts
    ~ 5,632 tokens   src/mcp/server.ts

Export & Badge

# Export full dashboard data as JSON
curl http://localhost:7456/api/export > report.json

# Dynamic SVG badge for README
# Add: ![](http://localhost:7456/api/badge)

GitHub Action

Add token analysis to every PR:

# .github/workflows/token-report.yml
name: Token Report
on: [pull_request]
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kalpeshgamit/codebase-pilot@main
        with:
          command: 'pack --compress --dry-run'

PR comment output:

Available commands: pack --compress --dry-run, scan-secrets, tokens, eval, impact --file <path>

Benchmarks

codebase-pilot eval

  Project         Files  Raw tokens  Compressed  Ratio  Edges  Time
  --------------  -----  ----------  ----------  -----  -----  ----
  codebase-pilot     92      98,798      29,274    70%    134  45ms

Uninstall

npm uninstall -g codebase-pilot-cli    # remove CLI
codebase-pilot eject               # remove project configs (optional)

Node.js >= 18 · MIT License · Contributing · Security

Save tokens. Ship faster.
npm install -g codebase-pilot-cli