Codebase Pilot

Stop burning tokens. Start coding smarter. AI context engine — pack, compress, optimize any codebase for LLMs. 100% free. Zero cloud. Zero API calls. No subscription. No account.

Unlike AI coding assistants that charge per token, codebase-pilot never calls any AI API. It runs entirely on your machine and saves you money on every prompt you send.

---

Installation

Claude Code Plugin

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

npm (recommended)

npm install -g codebase-pilot-cli

npx (no install)

npx codebase-pilot-cli init

Homebrew (macOS)

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

Install script

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

Update

npm update -g codebase-pilot-cli

Uninstall

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

---

Why codebase-pilot

Most AI developer tools call an AI API on your behalf — you pay per token, per month, or per seat.

codebase-pilot is different:

| | codebase-pilot | Context Packers | AI Coding Assistants | |--|:-:|:-:|:-:| | Price | Free forever | Free (basic) | $10–$50/month | | Calls AI APIs | Never | No | Yes — you pay | | Runs locally | Always | Yes | Cloud-dependent | | Token savings | 60–90% | 20–50% | None (adds tokens) | | Security scanning | 180 patterns | Basic | None | | Workflow skills | 19 built-in | None | Varies | | Agent orchestration | 7-layer | None | None | | Web dashboard | Full analytics | None | None | | Zero telemetry | ✅ | ✅ | ❌ |

codebase-pilot doesn't replace your AI assistant — it makes every prompt cheaper and smarter.

---

Maximum Token Savings — Stack These Together

codebase-pilot compresses your codebase. Other plugins compress different things. Stack them for the best results:

Without any optimization:   150,000 tokens  (~$0.45/prompt)
+ codebase-pilot pack       →  41,000 tokens  (72% reduction)
+ --affected (incremental)  →   8,000 tokens  (95% on iterations)
+ --agent scoping           →   4,000 tokens  (only relevant files)
+ session memory plugin     →   3,000 tokens  (no repeated history)
= Total savings: ~98% vs baseline

Layer 1 — Codebase (codebase-pilot)

| Technique | Command | Savings | |-----------|---------|---------| | Full compress | codebase-pilot pack --compress | 60–90% | | Incremental (changed files only) | codebase-pilot pack --compress --affected | 95%+ on iterations | | Import graph prune (only what matters) | codebase-pilot pack --compress --prune src/file.ts | 80–95% | | Agent scoping (one agent's files only) | codebase-pilot pack --compress --agent | 85–95% | | Aggressive .claudeignore | Exclude build/, dist/, node_modules/, *.lock | 10–30% | | Token budget check before starting | /codebase-pilot:token-budget | Prevents overload |

Layer 2 — Session Memory (complementary plugins)

| Plugin | What it compresses | How it helps | |--------|-------------------|-------------| | Session memory plugins (claude-mem etc.) | Past conversation history | No repeated context across sessions | | Workflow plugins (pro-workflow, get-shit-done) | Planning prompts + specs | Leaner task setup | | Tool efficiency plugins (goodvibes) | MCP tool call payloads | Smaller per-tool overhead |

Layer 3 — Prompt Engineering

| Technique | Savings | |-----------|---------| | Use /codebase-pilot:thinking — design before coding | Avoids expensive re-work loops | | Use sub-agents — fresh context per task | Each agent starts clean, no accumulated history | | Use --dry-run to preview before loading | Load only what you need | | Keep CLAUDE.md lean — facts only, no prose | Every line loads every session | | Use /codebase-pilot:pilot-check at session start | Identifies token hogs before you start |

> Key insight: codebase-pilot and session memory plugins solve different problems. > codebase-pilot compresses what your code looks like now. > Memory plugins compress what Claude did in previous sessions. > Stack both for near-zero redundant tokens.

---

How It Works

Your Codebase → scan → detect → pack → compress → security scan → AI-ready output
   150K tokens                                              → 41K tokens (~$0.12/prompt)

The Pipeline:

| Step | What happens | Impact | |------|-------------|--------| | Scan | Detect languages, frameworks, databases, test runners | 76 languages, 58 frameworks | | Pack | Collect files, apply agent scoping, format as XML/MD | Structured AI context | | Compress | Keep signatures, fold function bodies | 70% token reduction | | Security | 180 pattern secret scan, auto-exclude detected files | Zero leaked credentials | | --affected | SHA-256 hash — only pack changed files | 95%+ savings on iterations | | --prune | Import graph traversal — minimum viable context | Only files that matter |

Result: 150K tokens → 41K packed → $0.12/prompt instead of $0.45 (saves $0.33 per prompt, ~$36/week for active use).

---

Token Savings

codebase-pilot pack --compress

  Files:    104 packed
  Tokens:   ~41,496 (compressed from ~150,810, 72% reduction)
  Cost:     ~$0.12 per prompt (saved ~$0.33)

codebase-pilot compare

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

The dashboard tracks savings over time: $36.25 saved this week — real dollars, not abstract tokens.

---

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

| Platform | Mechanism | |----------|-----------| | macOS | launchd (auto-start on login, KeepAlive) | | Linux | systemd user unit (auto-start, restart on failure) | | Windows | Task Scheduler (runs at logon, restart on crash) |

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

Dashboard

Health score, sparklines, 7-day trend chart, $ cost, smart suggestions — dark navy theme with animated gradient branding.

Prompts

User prompts from Claude Code (via hooks) + all pack sessions with git context (branch, commit, dirty files). Click any row for detail drawer.

Projects

Cross-project comparison chart, efficiency progress bars, savings by project. System-wide token tracking.

Import Graph

Interactive D3.js force-directed graph with stats overlay (nodes, edges, directories). Click nodes for blast radius.

Search

Full-text BM25 search with quick-search tips, result count badge, highlighted matches with file path + line number.

Agents

Summary stats with model cost indicators (Haiku $, Opus $$$$), layer architecture, agent cards with context paths.

Files

File size warnings (red L >10K, orange M >5K tokens), language distribution, per-file token breakdown with lazy loading.

Security

97% health score badge, risk distribution chart (critical/high/medium/low), pattern categories, detected secrets with drawer.

---

Features

| Feature | Details | |---------|---------| | Pack & Compress | XML/Markdown output, regex-based compression (8 languages), agent-scoped packing | | Incremental Pack | --affected packs only changed files (SHA-256), --prune uses import graph for minimal context | | Prompt Tracking | Captures actual Claude Code prompts via hooks, git context (branch, commit, dirty), duration | | Plugin Marketplace | Install via /plugin marketplace add — 19 built-in skills, auto health check on session start, MCP auto-config | | Security Scanner | 180 patterns across 15 categories — cloud, payment, AI, crypto, generic | | Blast Radius | Import graph analysis, risk scoring (0-100), affected test detection | | Full-Text Search | SQLite FTS5 with BM25 ranking, snippet extraction, highlighted matches | | Web Dashboard | 8 pages, dark/light theme, glassmorphism UI, real-time WebSocket, auto-port fallback | | MCP Server | 10 tools + 3 prompts over stdio — works with Claude Code, Cursor, Zed | | Multi-Platform | Generates CLAUDE.md, .cursorrules, .windsurfrules, AGENTS.md | | Agent System | 7-layer sub-agents with haiku/sonnet/opus model routing | | Watch Mode | Chokidar file watching, debounced re-scan, auto-update configs | | Incremental | SHA-256 hash-based change detection — only re-scans modified files | | Visualization | D3.js interactive force-directed import graph (drag, zoom, search) | | Benchmarks | eval command — tokens, compression ratio, import edges, timing | | Usage Stats | Per-project + system-wide savings tracking (today/week/month) | | Cost Estimation | Real $ per prompt — "$0.12/prompt, saved $0.32" (Claude Sonnet pricing) | | Health Score | Project health 0-100 — compression, file sizes, usage, gamified | | Compare | compare shows token impact of changes — "+16K tokens (+$0.05/prompt)" | | GitHub Action | CI/CD: auto-comment on PRs with token report + cost saved | | Pre-commit Hook | Auto-scans secrets before every commit — blocks if detected | | Export API | /api/export — full JSON data, /api/badge — dynamic SVG | | Always-On Daemon | System service (launchd/systemd/Task Scheduler), auto-pack, tracks forever | | 76 Languages | 3 tiers: 17 full ecosystem, 21 package+test, 38 extension-only | | 58 Frameworks | Next.js, Django, Gin, Axum, Spring Boot, Rails, Laravel, and more | | 39 Test Runners | Vitest, pytest, Go test, Cargo test, JUnit, RSpec, and more | | 32 ORMs | Prisma, SQLAlchemy, GORM, Diesel, Hibernate, ActiveRecord, and more | | Config Validation | Validates agents.json, hooks before writing — prevents invalid configs | | Zero Cloud | No API calls, no accounts, no telemetry. Everything runs locally |

---

Commands

codebase-pilot init [--platform cursor,windsurf,codex]  # scan + generate configs + MCP + hooks
codebase-pilot scan                                      # re-detect + update
codebase-pilot pack [--compress] [--agent ]        # pack for AI context
codebase-pilot pack --compress --affected                # incremental — only changed files
codebase-pilot pack --compress --prune             # minimum context via import graph
codebase-pilot pack --compress --dry-run                 # preview without writing output
codebase-pilot scan-secrets [--path ]               # security scan — 180 patterns
codebase-pilot tokens [--agent ]                   # token breakdown + savings
codebase-pilot impact [--file ]                    # blast radius analysis
codebase-pilot search                             # 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

---

How It All Fits Together

codebase-pilot has three layers — use whichever fits your workflow:

| Layer | How to use | Where it runs | |-------|-----------|---------------| | CLI | codebase-pilot pack, codebase-pilot scan-secrets | Terminal — standalone, works anywhere | | MCP Server | codebase-pilot serve | Background process — exposes 10 tools directly to Claude Code, Cursor, Zed | | Slash Commands | /codebase-pilot:thinking, /codebase-pilot:debugging | Inside Claude Code — 21 project-level commands |

The slash commands call the CLI internally — they work even without the MCP server running.

---

Built-in Skills

codebase-pilot ships 19 skills — no additional plugins required. Every workflow is covered out of the box.

All skills use the codebase-pilot: prefix. Type /codebase-pilot in Claude Code to see the full list.

Session Start

| Skill | Trigger | What it does | |-------|---------|-------------| | codebase-pilot | /codebase-pilot | Session start — establishes all available skills and working context |

Context Tools

| Skill | Trigger | What it does | |-------|---------|-------------| | pilot-check | /codebase-pilot:pilot-check | Full health check (pack + secrets + token budget + agent validation) | | pack-context | /codebase-pilot:pack-context | Compress codebase for LLM context window | | scan-secrets | /codebase-pilot:scan-secrets | 180-pattern security scan | | impact-analysis | /codebase-pilot:impact-analysis | Blast radius of file changes | | token-budget | /codebase-pilot:token-budget | Token counts per file, context planning |

Workflow Skills

| Skill | Trigger | What it does | |-------|---------|-------------| | thinking | /codebase-pilot:thinking | Turn ideas into designs and specs | | writing-plans | /codebase-pilot:writing-plans | Implementation plans from specs | | executing-plans | /codebase-pilot:executing-plans | Execute plans task-by-task | | test-driven-development | /codebase-pilot:test-driven-development | Red-green-refactor TDD | | debugging | /codebase-pilot:debugging | Root cause before any fix | | subagent-driven-development | /codebase-pilot:subagent-driven-development | Fresh subagent per task | | sync-agents | /codebase-pilot:sync-agents | Parallel independent agents | | finishing-a-development-branch | /codebase-pilot:finishing-a-development-branch | Complete dev branch: verify, PR, merge | | requesting-code-review | /codebase-pilot:requesting-code-review | Request code review with full context | | receiving-code-review | /codebase-pilot:receiving-code-review | Handle review feedback systematically | | verification-before-completion | /codebase-pilot:verification-before-completion | Pre-completion quality checklist | | using-git-worktrees | /codebase-pilot:using-git-worktrees | Git worktree management for parallel dev | | writing-skills | /codebase-pilot:writing-skills | Create new skills following established patterns |

Agent Ops

| Skill | Trigger | What it does | |-------|---------|-------------

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kalpeshgamit
• Source: kalpeshgamit/codebase-pilot
• License: MIT
• Homepage: https://kalpeshgamit.github.io

Install and usage instructions live in the source repository linked above.