codebase-pilot-cli

v1.0.0

Published

16 minutes ago

Claude Code context engine — pack, compress, and optimize any codebase for AI. Save 60-90% tokens.

Downloads

3,025

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

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 — 5 skills (chained), 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

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.

| 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)