How real engineers run Claude Code.
From requirement to production-grade code — planned, tested, verified. Spec-driven plans. Enforced quality gates. Persistent knowledge.
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
macOS · Linux · Windows (WSL2) — installs in under 2 minutes.
Why Pilot Shell
Claude Code writes code fast — but without structure, it skips tests, loses context, and produces inconsistent results. Other frameworks add complexity (dozens of agents, thousands of lines of config) without meaningfully better output.
Pilot Shell is different. Every component solves a real problem with an engineered solution:
/spec— plans, implements, and verifies features end-to-end with TDD/fix— bugfix workflow with TDD; bails out when complexity exceeds the standard fix lane/prd— brainstorm ideas into clear requirements through with optional deep research- Spec collaboration — share specs with teammates, annotations flow back grouped by author
- Quality hooks — enforce linting, formatting, type checking, and tests as quality gates
- Context engineering — preserves decisions and knowledge across sessions
- Code intelligence — semantic search (Semble) + code knowledge graph (CodeGraph)
- Token optimization — 60–90% cost reduction via RTK compression and Semble code search
- Extensions — reusable rules, skills, and MCP servers with team sharing and customization
- Console — local web dashboard with real-time notifications and session management
- Pilot Bot — persistent automation agent with scheduled tasks and background jobs
Run pilot for Spec-Driven Development with /spec, or pilot bot for 24/7 automations.
Prerequisites
Claude Code: Install Claude Code using the native installer before setting up Pilot Shell. If you have the npm or brew version installed, uninstall it first. If no Claude Code installation is detected, the Pilot installer will attempt to set it up for you.
Claude Subscription: Solo developers should choose Max 5x for moderate usage or Max 20x for heavy usage. Teams should use Team Premium (6.25x usage per member, SSO, admin tools, billing management). Companies with stricter compliance or procurement requirements should use Enterprise (API based pricing applies per usage).
Terminal (Recommended): cmux works great with Pilot Shell — its vertical tab layout lets you run multiple sessions side by side. Any modern terminal works: Ghostty, iTerm2, or the built-in macOS/Linux terminal.
Claude Chrome (Recommended): Install the Claude Code Chrome extension for browser automation and E2E testing. Pilot automatically detects it and uses it as the preferred tool. When the extension isn't available, Pilot falls back to Chrome DevTools MCP (direct CDP access, Lighthouse, performance tracing), then playwright-cli (persistent sessions, tracing) or agent-browser (lightweight, fast startup).
Codex Plugin (Included): The Codex plugin is installed automatically with Pilot. It provides adversarial code review powered by OpenAI Codex — an independent second opinion during /spec planning and verification. Run /codex:setup once to authenticate, then enable reviewers in Console Settings → Reviewers. A ChatGPT Plus subscription ($20/mo) covers the Codex API usage.
Installation
Works with any existing project. Pilot Shell is installed on top of Claude Code and uses its built-in concepts like commands, rules, hooks, skills, subagents, MCP, LSP and optimized settings to improve your experience:
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
Installs globally on macOS, Linux, and Windows (WSL2). All tools and rules go to ~/.pilot/ and ~/.claude/. After installation, cd into any project and run pilot or ccp to start.
If you encounter an issue or unfixed bug in the latest version, you can always go back to a previous version (see releases):
export VERSION=9.0.6
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
Removes the Pilot binary, plugin files, managed commands/rules, settings and shell aliases:
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash
Over time, Claude Code's accumulated session logs and Pilot Shell's caches can slow things down. A periodic reset gives you a clean baseline:
# 1. Inside Claude Code, log out
/logout
# 2. Back up your current config (just in case)
mv ~/.claude.json ~/.claude.json.bak
mv ~/.claude ~/.claude.bak
mv ~/.pilot ~/.pilot.bak
# 3. Reinstall Pilot Shell from the official installer
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
# 4. Start Pilot, sign in to Claude, and re-activate your license
pilot
pilot activate <your-license-key>
Once Pilot Shell is running smoothly again, you can delete the .bak copies. Forgot your license key? Recover it in the Pilot members area.
Pilot Shell works inside Dev Containers. Copy the .devcontainer folder from this repository into your project, adapt it to your needs (base image, extensions, dependencies), and run the installer inside the container. The installer auto-detects the container environment and skips system-level dependencies like Homebrew.
For tighter isolation when working with untrusted code, combine the dev container with Claude Code's /sandbox — bubblewrap, socat, iptables, and ipset are pre-installed in the Dockerfile so it works out of the box on Linux. See Anthropic's development containers and sandboxing docs for hardening patterns (egress allowlist, managed settings, persistent volumes).
7-step installer with progress tracking, rollback on failure, and idempotent re-runs:
- Prerequisites — Checks/installs Homebrew, Node.js, Python 3.12+, uv, git, jq
- Claude files — Installs into
~/.claude/(native layout) — rules, commands, hooks, MCP servers, agents - Config files — Creates
.nvmrcand project config - Dependencies — Installs Semble, RTK, CodeGraph, Chrome DevTools MCP, playwright-cli, agent-browser, language servers
- Shell integration — Auto-configures bash, fish, and zsh with
pilotalias - VS Code extensions — Installs recommended extensions for your stack
- Finalize — Success message with next steps
Just chat — no plan, no approval gate. Quick mode is the default: quality hooks and TDD enforcement still apply, best for small tasks and exploration. For anything that needs a plan, use /spec — not Claude Code's built-in plan mode.
/spec — Spec-Driven Development
/spec replaces Claude Code's built-in plan mode (Shift+Tab) for new features, refactoring, and architectural work. It provides a complete planning workflow with TDD, verification, and code review. Collaborative spec review shifts review left — share a single link, teammates annotate inline, feedback flows back into the Console grouped by author.
pilot
> /spec "Add user authentication with OAuth and JWT tokens"
> /spec "Migrate the REST API to GraphQL"
Discuss → Plan → Approve → Implement (TDD) → Verify → Done
↑ ↓
└── Loop──┘
<img src="docs/img/spe