https://github.com/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.
https://github.com/kalpeshgamit/codebase-pilot
agent-orchestration ai-context-engine claude-code cli-tool code-compression code-context-engine code-review codebase-packer cursor-ai developer-tools llm-tools mcp-server nodejs security-scanner sub-agents token-optimization typescript vibe-coding windsurf
Last synced: 13 days ago
JSON representation
AI context engine for Claude Code, Cursor, Windsurf — pack, compress, and optimize any codebase. Save 60-90% tokens. Web dashboard on port 7456.
- Host: GitHub
- URL: https://github.com/kalpeshgamit/codebase-pilot
- Owner: kalpeshgamit
- License: mit
- Created: 2026-04-06T13:36:31.000Z (20 days ago)
- Default Branch: main
- Last Pushed: 2026-04-08T15:42:59.000Z (18 days ago)
- Last Synced: 2026-04-10T10:03:02.992Z (16 days ago)
- Topics: agent-orchestration, ai-context-engine, claude-code, cli-tool, code-compression, code-context-engine, code-review, codebase-packer, cursor-ai, developer-tools, llm-tools, mcp-server, nodejs, security-scanner, sub-agents, token-optimization, typescript, vibe-coding, windsurf
- Language: TypeScript
- Homepage: https://kalpeshgamit.github.io
- Size: 18.6 MB
- Stars: 5
- Watchers: 0
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: docs/ROADMAP.md
- Agents: docs/AGENTS.md
Awesome Lists containing this project
README
Stop burning tokens. Start coding smarter.
AI context engine — pack, compress, optimize any codebase for LLMs. Zero cloud. Zero lock-in.
---
## Installation
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
```
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. Open web dashboard
codebase-pilot ui # → http://localhost:7456
```
---
## 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
```bash
codebase-pilot ui # → http://localhost:7456
codebase-pilot ui --stop # stop daemon
codebase-pilot ui --status # check status
```
Port **7456** = PILOT on phone keypad. Runs as background daemon with real-time SSE updates.
### Dashboard
Live stat cards, savings chart, recent sessions — auto-updates via SSE.
### 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
| Feature | Details |
|---------|---------|
| **Pack & Compress** | XML/Markdown output, regex-based compression (8 languages), agent-scoped packing |
| **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** | 7 pages, dark/light theme, glassmorphism UI, real-time SSE updates |
| **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) |
| **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
codebase-pilot scan # re-detect + update
codebase-pilot pack [--compress] [--agent ] # pack for AI context
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] # web dashboard (port 7456)
codebase-pilot serve # MCP server (stdio)
codebase-pilot watch # file watcher
codebase-pilot stats [--global] # usage history
codebase-pilot eval # benchmarks
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:
```bash
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:
```bash
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
```json
{
"mcpServers": {
"codebase-pilot": {
"command": "codebase-pilot",
"args": ["serve"]
}
}
}
```
Same config works for Cursor (`.cursor/mcp.json`) and other MCP clients.
---
## Security Scanner
```bash
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.
```typescript
// Before (150 tokens)
export async function createUser(data: UserInput): Promise {
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 { /* ... */ }
```
Supports: TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, PHP.
---
## Benchmarks
```bash
codebase-pilot eval
Project Files Raw tokens Compressed Ratio Edges Time
-------------- ----- ---------- ---------- ----- ----- ----
codebase-pilot 92 98,798 29,274 70% 134 45ms
```
---
## Uninstall
```bash
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