# Codebase Pilot

> AI context engine for Claude Code, Cursor, Windsurf — pack, compress, and optimize any codebase. Save 60-90% tokens. Web dashboard on port 7456.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kalpeshgamit-codebase-pilot`
- **Verified:** Pending review
- **Seller:** [kalpeshgamit](https://agentstack.voostack.com/s/kalpeshgamit)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kalpeshgamit](https://github.com/kalpeshgamit)
- **Source:** https://github.com/kalpeshgamit/codebase-pilot
- **Website:** https://kalpeshgamit.github.io

## Install

```sh
agentstack add mcp-kalpeshgamit-codebase-pilot
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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)

```bash
npm install -g codebase-pilot-cli
```

npx (no install)

```bash
npx codebase-pilot-cli init
```

Homebrew (macOS)

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

Install script

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

Update

```bash
npm update -g codebase-pilot-cli
```

Uninstall

```bash
npm uninstall -g codebase-pilot-cli
```

## Quick Start

```bash
# 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

```bash
codebase-pilot pack --compress

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

```bash
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

```bash
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:

```bash
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](https://github.com/kalpeshgamit)
- **Source:** [kalpeshgamit/codebase-pilot](https://github.com/kalpeshgamit/codebase-pilot)
- **License:** MIT
- **Homepage:** https://kalpeshgamit.github.io

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kalpeshgamit-codebase-pilot
- Seller: https://agentstack.voostack.com/s/kalpeshgamit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.