GitHub - kalpeshgamit/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.

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

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
`dispatch`	`/codebase-pilot:dispatch`	Break work into sub-agents via agents.json patterns
`healthcheck`	`/codebase-pilot:healthcheck`	Validate agent setup — context paths, layers, models

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

10 Tools + 3 Prompts

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

Connect to Claude Code

{
  "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.

Categories

Category	Examples
Cloud	AWS, GCP, Azure, DigitalOcean, Supabase, Cloudflare
VCS / CI	GitHub, GitLab, Bitbucket, CircleCI, Travis
Payment	Stripe, Razorpay, Square, Braintree, Plaid, PayPal
AI LLMs	OpenAI, Anthropic, Groq, Perplexity, xAI
AI Infra	HuggingFace, Replicate, Together, Fireworks
AI DevTools	LangSmith, Pinecone, Weaviate, Qdrant
Messaging	Slack, Twilio, SendGrid, Mailgun, Resend
Database	MongoDB, PostgreSQL, Redis, PlanetScale, Neon
Dev Infra	npm, Docker, Doppler, Vault, PostHog
Monitoring	Sentry, Datadog, New Relic, Grafana
Crypto	Ethereum, Solana, Bitcoin private keys
Crypto Keys	RSA, EC, DSA, OpenSSH, PGP blocks
Generic	password=, secret=, api_key=, Bearer tokens

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, auto health checks, and prompt tracking:

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

5 Skills (chained):

/pilot-check — Full health check in one pass (chains all 4 below, saves ~75% tokens)
/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 Health Check on Session Start: When you open Claude Code, the plugin automatically runs a chained health check (pack analysis + secret scan + change comparison). Claude sees your project status before you type anything — zero manual commands.

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

MCP Server: Auto-configured — 10 tools + 3 prompts 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

Data	Source
Prompt text	Claude Code `UserPromptSubmit` hook
Token usage	Every `pack` / MCP `pack_codebase` call
Git context	Branch, commit message, hash, dirty count
Duration	Pack execution time

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:

Metric	Value
Files	95
Raw tokens	125,228
Packed tokens	35,388
Savings	72%
Cost saved	$0.27 per prompt
Secrets	Clean

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

Name		Name	Last commit message	Last commit date
Latest commit History 226 Commits
.claude-plugin		.claude-plugin
.github		.github
Formula		Formula
docs		docs
plugin		plugin
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.safeskill.yml		.safeskill.yml
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
action.yml		action.yml
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation