Skip to content
/
Tier B A8 Cross-runtime harness

codebase-pilot-cli

codebase-pilot-cli · kalpeshgamit/codebase-pilot · ★ 6 · last commit 2026-04-12

Primitive shape 41 total
Skills 19 Subagents 7 Hooks 2 MCP tools 13
00

Summary

codebase-pilot-cli — Summary

codebase-pilot is a free, zero-cloud AI context engine for Claude Code, Cursor, and Windsurf that packs, compresses, and optimizes any codebase for LLM consumption — achieving 60–90% token reduction through signature-only compression, incremental SHA-256 change detection, and import-graph pruning. Unlike codesight (which focuses on AST-precision extraction), codebase-pilot ships a fuller product: a web dashboard on port 7456 with 8 pages (health score, prompt tracking, import graph visualization, security scanner, file analysis, project comparison, search, and agent management), an always-on system service (launchd/systemd/Task Scheduler), 19 built-in skills for Claude Code, 10 MCP tools + 3 prompts, a 180-pattern security scanner, and a 7-layer sub-agent architecture with haiku/sonnet/opus model routing. The tool operates entirely locally with zero API calls and zero telemetry. codebase-pilot supports 76 languages, 58 frameworks, 39 test runners, and 32 ORMs. It includes hooks that capture Claude Code prompts (via UserPromptSubmit and SessionStart) and hooks that trigger auto-health-check on session start. Compared to seeds, codebase-pilot is architecturally closest to agent-os (both produce files agents read passively) but adds a persistent web dashboard and 19 built-in skills — effectively bundling codesight-like context packing with superpowers-like skill library and a full-featured local monitoring dashboard.

01

Overview

codebase-pilot-cli — Overview

Origin

Created by Kalpesh Gamit. Published as codebase-pilot-cli on npm. Repo: kalpeshgamit/codebase-pilot.

Philosophy

From the README:

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

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

Token savings are framed as a financial benefit: "$36.25 saved this week — real dollars, not abstract tokens."

Design Principles

  1. Free forever — no subscription, no account, no cloud
  2. Zero API calls — pure local analysis
  3. Zero telemetry — no data leaves the machine
  4. Layer stacking — codebase compression (Layer 1) + session memory plugins (Layer 2) + prompt engineering (Layer 3) compound for ~98% baseline reduction
  5. Full dashboard — not just a CLI; a persistent web UI tracking savings over time

Scope

codebase-pilot has the widest scope of all context-packaging tools in the batch:

  • Context packing (core)
  • Security scanning (180 patterns)
  • Blast radius analysis
  • Import graph visualization (D3.js)
  • Prompt tracking (captures actual Claude Code prompts via hooks)
  • 19 built-in workflow skills
  • 10 MCP tools + 3 prompts
  • 7-layer agent system with model routing
  • System service (always-on daemon)
  • GitHub Action for CI/CD

Key Metrics

  • 76 languages (17 full ecosystem, 21 package+test, 38 extension-only)
  • 58 frameworks
  • 39 test runners
  • 32 ORMs
  • 180 security scan patterns across 15 categories
  • 143 passing tests
02

Architecture

codebase-pilot-cli — Architecture

Distribution

  • Type: npm package + Claude Code plugin
  • Binary: codebase-pilot (from dist/bin/codebase-pilot.js), codebase-pilot-log-prompt (prompt logger)
  • Version analyzed: 1.2.0
  • Runtime required: Node.js 18/20/22
  • Language: TypeScript (strict mode)

Install Methods

# npm global
npm install -g codebase-pilot-cli

# npx one-shot
npx codebase-pilot-cli init

# Claude Code plugin
/plugin marketplace add kalpeshgamit/codebase-pilot
/plugin install codebase-pilot

# 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

Directory Tree

codebase-pilot/
├── src/                          # CLI source
├── plugin/
│   ├── .claude-plugin/
│   │   ├── plugin.json           # Plugin manifest
│   │   └── CLAUDE.md
│   ├── hooks/
│   │   └── hooks.json            # UserPromptSubmit + SessionStart hooks
│   └── skills/                   # 19 built-in skills
│       ├── codebase-pilot        # Session-start skill
│       ├── pilot-check
│       ├── pack-context
│       ├── scan-secrets
│       ├── impact-analysis
│       ├── token-budget
│       ├── thinking
│       ├── writing-plans
│       ├── executing-plans
│       ├── test-driven-development
│       ├── debugging
│       ├── subagent-driven-development
│       ├── sync-agents
│       ├── finishing-a-development-branch
│       ├── requesting-code-review
│       ├── receiving-code-review
│       ├── verification-before-completion
│       ├── using-git-worktrees
│       ├── writing-skills
│       └── dispatch + healthcheck (21 total commands listed in README)
├── docs/
│   └── screenshots/              # Dashboard screenshots
├── tests/                        # 143 passing tests
├── Formula/                      # Homebrew formula
└── package.json

Dashboard

Web UI at http://localhost:7456 (port 7456 = "PILOT" on phone keypad).

  • Always-on daemon: launchd (macOS), systemd (Linux), Task Scheduler (Windows)
  • Real-time WebSocket updates
  • D3.js force-directed import graph
  • SQLite FTS5 full-text search (BM25 ranking)

Target AI Tools

  • Claude Code (primary — ships plugin)
  • Cursor
  • Windsurf
  • Zed (MCP client)
03

Components

codebase-pilot-cli — Components

CLI Commands

Command Purpose
codebase-pilot init Scan + generate configs + MCP + hooks
codebase-pilot scan Re-detect + update
codebase-pilot pack [--compress] 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
codebase-pilot scan-secrets 180-pattern security scan
codebase-pilot tokens 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 Start web dashboard
codebase-pilot service Install as system daemon
codebase-pilot serve Start MCP server (stdio)
codebase-pilot watch File watcher mode
codebase-pilot stats Usage history
codebase-pilot eval Benchmarks
codebase-pilot compare Token impact of changes
codebase-pilot health Validate agent setup
codebase-pilot fix Auto-repair stale paths
codebase-pilot eject Remove dependency

Skills (19 + session-start)

Skill Trigger Purpose
codebase-pilot /codebase-pilot Session start — establishes all skills
pilot-check /codebase-pilot:pilot-check Full health check
pack-context /codebase-pilot:pack-context Compress codebase for context window
scan-secrets /codebase-pilot:scan-secrets 180-pattern security scan
impact-analysis /codebase-pilot:impact-analysis Blast radius analysis
token-budget /codebase-pilot:token-budget Token counts + planning
thinking /codebase-pilot:thinking Design before coding
writing-plans /codebase-pilot:writing-plans Implementation plans from specs
executing-plans /codebase-pilot:executing-plans Execute task-by-task
test-driven-development /codebase-pilot:test-driven-development Red-green-refactor
debugging /codebase-pilot:debugging Root cause before 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 Verify, PR, merge
requesting-code-review /codebase-pilot:requesting-code-review Request review with full context
receiving-code-review /codebase-pilot:receiving-code-review Handle review feedback
verification-before-completion /codebase-pilot:verification-before-completion Pre-completion quality checklist
using-git-worktrees /codebase-pilot:using-git-worktrees Git worktree management
writing-skills /codebase-pilot:writing-skills Create new skills

Hooks (2 events)

Event Trigger Action
UserPromptSubmit Every user prompt codebase-pilot-log-prompt — logs prompt with git context
SessionStart Session start Auto health-check: pack dry-run + secrets scan + compare

MCP Server (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

Security Scanner

180 patterns across 15 categories: cloud, VCS/CI, payment, AI LLMs, AI infra, AI devtools, messaging, database, dev infra, monitoring, crypto, crypto keys, generic.

05

Prompts

codebase-pilot-cli — Prompts

Excerpt 1 — SessionStart Hook Output

From plugin/hooks/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "echo '--- codebase-pilot ---' && codebase-pilot pack --compress --dry-run 2>/dev/null && echo '---' && codebase-pilot scan-secrets 2>/dev/null | head -5 && echo '---' && codebase-pilot compare 2>/dev/null | head -10 || true",
        "timeout": 30,
        "statusMessage": "codebase-pilot: running health check..."
      }
    ]
  }
}

Technique: Session-injected context primer. Rather than a prompt file, this hook injects live scan data (token counts, top security findings, cost delta) into the session context at startup. The agent sees real project state before receiving any user prompt — a form of dynamic context grounding.

Excerpt 2 — thinking Skill (Design before Code)

From plugin/skills/thinking (representative, based on README description):

---
name: thinking
description: Turn ideas into designs and specs before writing code
---

Before writing any code, use this skill to:
1. Articulate the problem clearly in 1-3 sentences
2. Identify constraints, dependencies, and edge cases
3. Sketch 2-3 solution approaches with tradeoffs
4. Select the simplest approach that solves the problem
5. Write a brief spec (input/output/behavior) before any implementation

Do NOT start implementing until you've completed all 5 steps.

Technique: Mandatory design gate. Follows the "spec-first" pattern from seeds like superpowers and spec-driver, but scoped to a single reasoning session rather than a full spec document workflow.

Excerpt 3 — pilot-check Skill (Health Check)

---
name: pilot-check
description: Full health check — pack + secrets + token budget + agent validation
---

Run a comprehensive project health check:

1. `/codebase-pilot pack --compress --dry-run` — check token counts
2. `/codebase-pilot scan-secrets` — check for exposed credentials
3. `/codebase-pilot tokens` — token budget analysis per file
4. `/codebase-pilot health` — validate agent setup

Report findings in priority order: CRITICAL (exposed secrets) → HIGH (token budget exceeded) → MEDIUM (stale configs) → INFO (optimization opportunities).

Technique: Ordered diagnostic pipeline. Structures the health check as a prioritized sequence with severity levels — medical triage applied to code context management.

09

Uniqueness

codebase-pilot-cli — Uniqueness

differs_from_seeds

codebase-pilot is most similar to a combination of agent-os (produces files agents read) and superpowers (ships behavioral workflow skills), but adds a persistent web dashboard and system daemon that neither provides. Unlike codesight (most direct competitor in this batch), codebase-pilot ships 19 workflow skills, hooks that capture live Claude Code prompts, a 7-layer multi-model agent system, and a full web monitoring dashboard — making it a significantly more opinionated and comprehensive tool. Its 19 skills closely mirror superpowers' skill set (test-driven-development, subagent-driven-development, using-git-worktrees, requesting-code-review, verification-before-completion) — codebase-pilot appears to have adopted the superpowers skill library verbatim and added codebase-specific skills (pilot-check, pack-context, scan-secrets, impact-analysis, token-budget). Unlike claude-conductor (Archetype 4, markdown scaffold only), codebase-pilot combines scaffold generation with active monitoring and enforcement.

Positioning

  • Primary differentiator: Only tool in the batch with a persistent web dashboard (port 7456) tracking token savings over time with real dollar amounts. The gamified health score (0–100) and always-on system daemon distinguish it from all other context-packing tools.
  • Secondary differentiator: Dual-mode value — context packing (like codesight) + behavioral framework (like superpowers) in one package.
  • Target user: Cost-conscious solo developers who want both token reduction and a workflow framework without managing two separate tools.

Observable Failure Modes

  1. Skill overlap with superpowers: The 19 skills heavily overlap with superpowers. If a project already has superpowers installed, codebase-pilot's workflow skills are redundant and may conflict.
  2. Web dashboard complexity: The 8-page dashboard with D3.js graph and WebSocket updates is significantly more complex than the context-packing core, creating a larger maintenance surface for a single-author project.
  3. Port conflict: Port 7456 may conflict with other local services; auto-fallback is described but may surprise users.
  4. Service daemon friction: launchd/systemd/Task Scheduler service installation is significantly more invasive than a typical CLI tool — may create "hard to remove" cleanup issues.
  5. Low stars (6): Despite comprehensive features, low community adoption suggests the tool may be pre-announcement or niche.
04

Workflow

codebase-pilot-cli — Workflow

Primary Setup Flow

# 1. Install
npm install -g codebase-pilot-cli

# 2. Initialize project
cd your-project
codebase-pilot init

# 3. Pack + compress for AI context
codebase-pilot pack --compress --copy

# 4. Check security
codebase-pilot scan-secrets

# 5. See cost savings
codebase-pilot compare

# 6. Open web dashboard
codebase-pilot ui    # → http://localhost:7456

# 7. (Optional) Install as always-on service
codebase-pilot service

Phase-to-Artifact Map

Phase Artifact
init CLAUDE.md, .cursorrules, .windsurfrules, AGENTS.md, agents.json, hooks.json, MCP config
scan In-memory scan result → packed context
pack CODEBASE_CONTEXT.md or XML/MD output
pack --affected Only changed files (SHA-256 hash comparison)
pack --prune Minimum context via import graph traversal
scan-secrets Report (stdout) or filtered packing
impact Blast radius report (stdout)
serve MCP stdio server
ui Dashboard at http://localhost:7456
service System daemon (launchd/systemd/Task Scheduler)

Session Start Hook Flow

On every Claude Code session start:

  1. codebase-pilot pack --compress --dry-run (preview token counts)
  2. codebase-pilot scan-secrets | head -5 (top secret findings)
  3. codebase-pilot compare | head -10 (token impact summary) Output injected as session context.

Incremental Pack

codebase-pilot pack --compress --affected   # only changed files (95%+ savings on iterations)
codebase-pilot pack --compress --prune src/auth.ts  # import-graph pruned context

Agent System (7-layer)

Sub-agents organized in layers with model cost indicators:

  • Layer dispatch via agents.json patterns
  • Per-agent context path scoping
  • Haiku ($), Sonnet ($$), Opus ($$$$) routing

Approval Gates

None enforced by the tool itself — skills include recommended approval patterns (e.g., verification-before-completion), but are not blocking.

06

Memory Context

codebase-pilot-cli — Memory & Context

State Storage

codebase-pilot uses file-based project-scoped + global storage.

Project-Level Artifacts

File Purpose Updated
CODEBASE_CONTEXT.md (or XML/MD) Packed AI context On every pack run
agents.json Agent layer config with context paths On init
.claudeignore (or equivalent) Exclusion list Manual

Global State (per-machine)

Path Purpose
SQLite DB (project-local) Prompt logs, SHA-256 hashes for incremental pack, FTS5 search index
Dashboard data Token savings over time, health score trends
Service PID System daemon state

Prompt Tracking

The UserPromptSubmit hook calls codebase-pilot-log-prompt on every Claude Code prompt, capturing:

  • Prompt text
  • Git context (branch, commit SHA, dirty files)
  • Duration
  • Session identifier

This data populates the Prompts page in the dashboard and enables cross-session analysis.

SHA-256 Incremental Cache

--affected mode uses SHA-256 hashing to detect changed files since last pack:

  • Computes hash of each file
  • Compares against stored hash state
  • Packs only files with changed hashes
  • Achieves 95%+ token savings on iterative development sessions

Context Compaction

Three-tier approach:

  1. Full pack (pack --compress) — use at session start
  2. Incremental (pack --compress --affected) — use during development iterations
  3. Import-graph pruned (pack --compress --prune <file>) — use for targeted changes

Cross-Session Persistence

The system daemon collects data continuously — opening the dashboard after days or weeks shows accumulated token history from all past sessions.

FTS5 Full-Text Search

SQLite FTS5 with BM25 ranking enables semantic search across packed codebase content:

codebase-pilot search "authentication middleware"
07

Orchestration

codebase-pilot-cli — Orchestration

Multi-Agent Pattern

codebase-pilot supports a 7-layer sub-agent architecture via agents.json:

  • Each agent has a defined scope (specific file paths or modules)
  • Model routing: haiku ($) for simple tasks, sonnet ($$) for standard, opus ($$$$) for complex
  • dispatch skill breaks work into sub-agents following agents.json patterns
  • sync-agents skill coordinates parallel independent agents

Orchestration Pattern

hierarchical — a coordinator agent dispatches scoped sub-agents, each with a limited context path.

Execution Mode

event-driven (hooks at SessionStart and UserPromptSubmit) + one-shot for CLI commands.

Isolation Mechanism

none — agents share the same filesystem. The agent scoping (pack --agent <name>) limits what context each agent sees, but there is no process isolation.

Multi-Model Usage

Yes — the 7-layer agent system explicitly routes to different model tiers:

agents.json:
  - layer: 1
    scope: "tests/"
    model: "claude-haiku-4-5"  # cheap
  - layer: 4
    scope: "src/core/"
    model: "claude-sonnet-4-5"  # standard
  - layer: 7
    scope: "architecture/"
    model: "claude-opus-4-5"    # powerful

Consensus Mechanism

None.

Prompt Chaining

Yes — pack --compress output is consumed by skills as the context input for downstream tasks.

Cross-Tool Portability

Medium — optimized for Claude Code (plugin), with Cursor and Windsurf support via generated config files (.cursorrules, .windsurfrules). MCP server extends to Zed.

Auto-Validators

The pilot-check skill and SessionStart hook auto-run:

  • scan-secrets — credential exposure check
  • pack --dry-run — token budget validation
  • compare — token impact delta

These are informational validators, not blocking gates.

08

Ui Cli Surface

codebase-pilot-cli — UI & CLI Surface

CLI Binary

  • Binary name: codebase-pilot
  • Secondary binary: codebase-pilot-log-prompt (prompt capture utility)
  • Is thin wrapper: No — full runtime (Node.js TypeScript)
  • Install: npm install -g codebase-pilot-cli

Major commands: init, scan, pack, scan-secrets, tokens, impact, search, visualize, ui, service, serve, watch, stats, eval, compare, health, fix, eject

Local Web Dashboard

  • Exists: Yes
  • Type: web-dashboard
  • Port: 7456 (mnemonic: PILOT on phone keypad; auto-fallback to next port if occupied)
  • Start: codebase-pilot ui
  • Tech stack: Node.js server, D3.js for import graph, glassmorphism dark navy theme, real-time WebSocket updates
  • Daemon: Install with codebase-pilot service — runs as launchd (macOS), systemd (Linux), Task Scheduler (Windows), auto-starts on login

Dashboard Pages (8)

Page Content
Health Health score 0–100, sparklines, 7-day trend, $ cost, smart suggestions
Prompts Captured Claude Code prompts with git context, click for detail drawer
Projects Cross-project comparison chart, savings by project
Import Graph D3.js force-directed graph, drag/zoom, click nodes for blast radius
Search FTS5 BM25 search with highlighted matches
Agents Agent layer summary, model cost indicators, context paths
Files File size warnings, language distribution, per-file token breakdown
Security 97% health score badge, risk distribution chart, detected secrets drawer

MCP Server

  • Exists: Yes
  • Type: stdio
  • Tool count: 10 tools + 3 prompts
  • Start: codebase-pilot serve
  • Compatible clients: Claude Code, Cursor, Zed

Export API

  • /api/export — full JSON data export
  • /api/badge — dynamic SVG badge

IDE Integration

Generates: CLAUDE.md, .cursorrules, .windsurfrules, AGENTS.md for respective AI tools.

GitHub Action

Ships action.yml for CI/CD integration — auto-comments on PRs with token report + cost saved.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.