The professional development environment for Claude Code
Start a task, grab a coffee, come back to production-grade code.
Tests enforced. Context preserved. Quality automated.
⭐ Star this repo · 🌐 Website · 📖 Documentation · 🆕 Updates · 📋 Changelog
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bashWorks on macOS, Linux, and Windows (WSL2).
Claude Code writes code fast. But without structure, it skips tests, loses context, and produces inconsistent results — especially on complex, established codebases where there are real conventions to follow and real regressions to catch. I tried other frameworks. Most of them add complexity — dozens of agents, elaborate scaffolding, thousands of lines of instruction files — but the output doesn't get better. You just burn more tokens, wait longer, and deal with more things breaking.
So I built Pilot Shell. Instead of adding process on top, it bakes quality into every interaction. Linting, formatting, and type checking run as enforced hooks on every edit. TDD is mandatory, not suggested. Context is preserved across sessions. Every rule exists because I hit a real problem: a bug that slipped through, a regression that shouldn't have happened, a session where Claude cut corners and nobody caught it.
This isn't a vibe coding tool, it's true agentic engineering, but without the added complexity. You install it once, run pilot in any project, then /sync to learn your codebase. The guardrails are just there. The end result is that you can walk away — start a /spec task, approve the plan, go grab a coffee. When you come back, the work is tested, verified, formatted, and ready to ship.
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).
Works with any existing project. Pilot Shell doesn't scaffold or restructure your code — it installs globally and adapts to your conventions.
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bashInstalls 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.
What the installer does
7-step installer with progress tracking, rollback on failure, and idempotent re-runs:
- Prerequisites — Checks Homebrew, Node.js, Python 3.12+, uv, git
- Dependencies — Installs Probe, playwright-cli, language servers, property-based testing tools
- Shell integration — Auto-configures bash, fish, and zsh with
pilotalias - Config & Claude files — Sets up
.claude/plugin, rules, commands, hooks, MCP servers - VS Code extensions — Installs recommended extensions for your stack
- Automated updater — Checks for updates on launch with release notes and one-key upgrade
- Cross-platform — macOS, Linux, Windows (WSL2)
Installing a specific version or uninstalling
Specific version (see releases):
export VERSION=7.5.6
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bashUninstall — 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 | bashDev Container
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.
/spec replaces Claude Code's built-in plan mode (Shift+Tab). It provides a complete planning workflow with TDD, verification, and code review — use /spec instead of plan mode for all planned work.
Features, bug fixes, refactoring — describe it and /spec handles the rest. Auto-detects whether it's a feature or a bugfix and adapts the workflow.
pilot
> /spec "Add user authentication with OAuth and JWT tokens" # → feature mode
> /spec "Fix the crash when deleting nodes with two children" # → bugfix mode (auto-detected)Plan → Approve → Implement (TDD) → Verify → Done
↑ ↓
└── Loop──┘
Feature Mode
Full exploration workflow for new functionality, refactoring, or architectural changes.
Plan: Explores codebase with semantic search → asks clarifying questions → writes detailed spec with scope, tasks, and definition of done → plan-reviewer sub-agent validates completeness → waits for your approval.
Implement: Creates an isolated git worktree → implements each task with strict TDD (RED → GREEN → REFACTOR) → quality hooks auto-lint, format, and type-check every edit → full test suite after each task.
Verify: Full test suite + actual program execution → unified review sub-agent (compliance + quality + goal) → auto-fixes findings → squash merges to main on success.
Bugfix Mode
Investigation-first workflow for targeted fixes. Finds the root cause before touching any code.
Investigate: Reproduces the bug → traces backward through the call chain to find the root cause at a specific file:line → compares against working code patterns → states the fix with confidence level. If 3+ hypotheses fail, escalates as an architectural problem.
Test-Before-Fix: Writes a regression test that FAILS on current code → implements the minimal fix at the root cause → verifies all tests pass. Defense-in-depth validation at multiple layers when the bug involves data flowing through shared code paths.
Verify: Lightweight verification — regression test confirmation → full test suite → lint + type check → quality checks. No review sub-agents — the regression test proves the fix works, the full suite proves nothing else broke.
Why this matters: Root cause investigation prevents "fix one thing, break another." The regression test locks in the fix. No formal notation overhead — just trace, test, fix, verify.
Just chat — no plan, no approval gate. 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.
| Command | What it does |
|---|---|
/sync |
Explores your codebase, discovers conventions, builds a search index, updates project rules. Run once initially, then anytime your project changes. |
/learn |
Captures non-obvious discoveries as reusable skills. Triggers automatically or on demand. |
| Share | Share skills, rules, commands, and agents across machines and teams — global sync, project mode, org hub. |
Create your own rules, commands, skills, and agents — all plain markdown files in .claude/. Then share them across machines, projects, and organizations via Skillshare.
Create assets in your project:
| Asset | Location | When it loads |
|---|---|---|
| Rules | .claude/rules/ |
Every session, or by file type |
| Commands | .claude/commands/ |
On demand via /command-name |
| Skills | .claude/skills/ |
Automatically when relevant |
| Agents | .claude/agents/ |
Spawned as sub-agents for specialized tasks |
/sync explores your codebase and generates project-specific rules. /learn captures debugging discoveries as reusable skills. Add MCP servers in .mcp.json and run /sync to generate documentation. For monorepos, organize rules in subdirectories by team with paths frontmatter to scope by file type.
Share all four asset types — skills, rules, commands, and agents — across boundaries via Skillshare. Works with 50+ AI tools (Claude Code, Cursor, Codex, Windsurf, and more) so you have one source of truth for all your AI assets.
| Mode | Scope | How it works |
|---|---|---|
| Project | Single repo, team-wide | Commit .skillshare/skills/ to your repo — team members get assets on git clone |
| Global | Personal, all projects | Sync skills, rules, commands, and agents — push/pull across your machines via git |
| Organization | All projects, org-wide | Tracked repos distribute curated assets — hub index enables search |
Manage sharing via the skillshare CLI and view all shared assets on the Console Share page.
A local web dashboard with different views and real-time notifications when Claude needs your input:
All views
| View | What it shows |
|---|---|
| Dashboard | Workspace status, active sessions, spec progress, git info, recent activity |
| Specification | All spec plans with task progress, phase tracking, and iteration history |
| Changes | Git diff viewer with staged/unstaged files, branch info, and worktree context |
| Memories | Browsable observations — decisions, discoveries, bugfixes — with type filters and search |
| Sessions | Active and past sessions with observation counts and duration |
| Share | Skill sharing — view assets, source/sync status, CLI reference |
| Usage | Daily token costs, model routing breakdown, and usage trends |
| Settings | Model selection per command/sub-agent, extended context toggle, spec workflow toggles |
| Help | Documentation, guides, and quick-start resources |
A full-stack project — created from scratch with a single prompt, then extended with 3 features built in parallel using /spec. Every line of code was planned, implemented, tested, and verified entirely by AI. Zero manual code edits, zero bug fixes by a human. Watch the demo and browse the code →
Hooks fire automatically across the entire lifecycle — formatting, linting, type checking, TDD enforcement, context preservation, and memory capture. Every file edit triggers quality checks. Every session start restores state. Every session end persists context.
All hooks by lifecycle event
| Hook | Type | What it does |
|---|---|---|
| Memory loader | Blocking | Loads persistent context from Pilot Shell Console memory |
post_compact_restore.py |
Blocking | After auto-compaction: re-injects active plan, task state, and context |
| Session tracker | Async | Initializes user message tracking for the session |
| Hook | Type | What it does |
|---|---|---|
tool_redirect.py |
Blocking | Blocks WebSearch/WebFetch (MCP alternatives exist), EnterPlanMode/ExitPlanMode (/spec conflict). Hints Probe CLI for semantic Grep patterns. |
| Hook | Type | What it does |
|---|---|---|
file_checker.py |
Blocking | Dispatches to language-specific checkers: Python (ruff + basedpyright), TypeScript (Prettier + ESLint + tsc), Go (gofmt + golangci-lint). Auto-fixes formatting. |
file_checker.py (TDD) |
Non-blocking | Checks if implementation files were modified without failing tests first. Shows reminder to write tests. Excludes test files, docs, config, TSX, and infrastructure. |
context_monitor.py |
Non-blocking | Monitors context usage. Warns at ~80% (informational) and ~90%+ (caution). Prompts /learn at key thresholds. |
| Memory observer | Async | Captures development observations to persistent memory. |
| Hook | Type | What it does |
|---|---|---|
pre_compact.py |
Blocking | Captures Pilot Shell state (active plan, task list, key context) to persistent memory before compaction fires. |
| Hook | Type | What it does |
|---|---|---|
spec_stop_guard.py |
Blocking | If an active spec exists with PENDING or COMPLETE status,blocks stopping. Forces verification to complete before the session can end. |
| Session summarizer | Async | Saves session observations to persistent memory for future sessions. |
| Hook | Type | What it does |
|---|---|---|
session_end.py |
Blocking | Stops the worker daemon when no other Pilot Shell sessions are active. Sends real-time dashboard notification. |
Pilot Shell preserves context automatically across compaction boundaries. Before compaction fires, hooks capture the active plan, task list, and key decisions to persistent memory. After compaction, hooks restore everything — work continues exactly where it left off. Multiple sessions can run in parallel on the same project without interference.
How the effective context display works
Claude Code reserves ~16.5% of the context window as a compaction buffer, triggering auto-compaction at ~83.5% raw usage. Pilot Shell rescales this to an effective 0–100% range so the status bar fills naturally to 100% right before compaction fires. A ▓ buffer indicator at the end of the bar shows the reserved zone. The context monitor warns at ~80% effective (informational) and ~90%+ effective (caution) — no confusing raw percentages.
Opus for planning — where reasoning quality matters most. Sonnet for implementation and verification — where a clear spec makes fast execution predictable. All model assignments are configurable per-component via the Pilot Shell Console settings.
Phase-by-phase breakdown
| Phase | Default | Why |
|---|---|---|
| Planning | Opus | Exploring your codebase, designing architecture, and writing the spec requires deep reasoning. A good plan is the foundation of everything. |
| Plan Verification | Sonnet | The plan-reviewer sub-agent validates completeness and challenges assumptions on every feature spec. (disabled by default) |
| Implementation | Sonnet | With a solid plan, writing code is straightforward. Sonnet is fast, cost-effective, and produces high-quality code when guided by a clear spec. |
| Code Verification | Sonnet | The unified spec-reviewer agent handles deep code review (compliance + quality + goal). The orchestrator runs mechanical checks and applies fixes. (disabled by default) |
Choose between Sonnet 4.6 and Opus 4.6 for the main session, each command, and sub-agents. A global "Extended Context (1M)" toggle enables the 1M token context window across all models simultaneously. Note: 1M context models require a Max (20x) or Enterprise subscription — not available to all users.
Production-tested best practices loaded into every session. Core rules cover workflow, testing, verification, debugging, and tools. Coding standards activate conditionally by file type. These aren't suggestions, they're enforced.
Core Workflow
task-and-workflow.md— Task management, /spec orchestration, deviation handlingtesting.md— TDD workflow, test strategy, coverage requirementsverification.md— Execution verification, completion requirements
Development Practices
development-practices.md— Project policies, debugging methodology, git rulescontext-management.md— Auto-compaction and context preservationpilot-memory.md— Online learning triggers
Tools
research-tools.md— Search priority and tool selection guidecli-tools.md— Pilot CLI, Probe CLI semantic searchplaywright-cli.md— Browser automation for E2E UI testing
Collaboration
skill-sharing.md— Skillshare CLI reference and sharing modes
Coding Standards (activated by file type)
| Standard | Activates On | Coverage |
|---|---|---|
| Python | *.py |
uv, pytest, ruff, basedpyright, type hints |
| TypeScript | *.ts, *.tsx, *.js, *.jsx |
npm/pnpm, Jest, ESLint, Prettier, React patterns |
| Go | *.go |
Modules, testing, formatting, error handling |
| Frontend | *.tsx, *.jsx, *.html, *.vue, *.css |
Components, CSS, accessibility, responsive design |
| Backend | **/models/**, **/routes/**, **/api/**, etc. |
API design, data models, query optimization, migrations |
MCP servers provide external context in every session — library docs, persistent memory, web search, GitHub code search, and web page fetching.
All servers
| Server | Purpose |
|---|---|
| lib-docs | Library documentation lookup — get API docs for any dependency |
| mem-search | Persistent memory search — recall context from past sessions |
| web-search | Web search via DuckDuckGo, Bing, and Exa |
| grep-mcp | GitHub code search — find real-world usage patterns across repos |
| web-fetch | Web page fetching — read documentation, APIs, references |
Real-time diagnostics and go-to-definition for Python (basedpyright), TypeScript (vtsls), and Go (gopls). Auto-installed, auto-configured via .lsp.json, and auto-restart on crash.
The pilot binary (~/.pilot/bin/pilot) manages sessions, worktrees, licensing, and context. Run pilot or ccp to start Claude with Pilot Shell enhancements. All commands support --json for structured output.
Session & Context
| Command | Purpose |
|---|---|
pilot |
Start Claude with Pilot Shell enhancements, auto-update, and license check |
pilot run [args...] |
Same as above, with optional flags (e.g., --skip-update-check) |
pilot check-context --json |
Get current context usage percentage |
pilot register-plan <path> <status> |
Associate a plan file with the current session |
pilot sessions [--json] |
Show count of active Pilot Shell sessions |
Worktree Isolation
| Command | Purpose |
|---|---|
pilot worktree create --json <slug> |
Create isolated git worktree for safe experimentation |
pilot worktree detect --json <slug> |
Check if a worktree already exists |
pilot worktree diff --json <slug> |
List changed files in the worktree |
pilot worktree sync --json <slug> |
Squash merge worktree changes back to base branch |
pilot worktree cleanup --json <slug> |
Remove worktree and branch when done |
pilot worktree status --json |
Show active worktree info for current session |
License & Auth
| Command | Purpose |
|---|---|
pilot activate <key> |
Activate a license key on this machine |
pilot deactivate |
Deactivate license on this machine |
pilot status [--json] |
Show current license status |
pilot verify [--json] |
Verify license (used by hooks) |
pilot trial --check [--json] |
Check trial eligibility |
pilot trial --start [--json] |
Start a trial |
"I stopped reviewing every line Claude writes. The hooks catch formatting and type errors automatically, TDD catches logic errors, and the spec verifier catches everything else. I review the plan, approve it, and the output is production-grade."
"Other frameworks I tried added so much overhead that half my tokens went to the system itself. Pilot Shell is lean — quick mode has zero scaffolding, and even /spec only adds structure where it matters. More of my context goes to actual work."
"The persistent memory changed everything. I can pick up a project after a week and Claude already knows my architecture decisions, the bugs we fixed, and why we chose certain patterns. No more re-explaining the same context every session."
Pilot Shell is source-available under a commercial license. See the LICENSE file for full terms.
| Tier | Seats | Includes |
|---|---|---|
| Solo | 1 | All features, continuous updates, community support via GitHub Issues |
| Team | Multi | Solo + team license management, seat management, priority support, team onboarding |
All plans work across multiple personal machines — one subscription, all your devices.
Details and licensing at pilot-shell.com.
Let's figure out if Pilot Shell is the right fit for your team and get everyone set up.
Book a Call · Send an Email · Connect on LinkedIn
Does Pilot Shell send my code or data to external services?
No code, files, prompts, project data, or personal information ever leaves your machine through Pilot Shell. All development tools — code search (Probe), persistent memory (Pilot Shell Console), session state, and quality hooks — run entirely locally.
Pilot Shell makes external calls only for licensing. Here is the complete list:
| When | Where | What is sent |
|---|---|---|
| License validation (once per 24h) | api.polar.sh |
License key, organization ID |
| License activation (once) | api.polar.sh |
License key, machine fingerprint |
| Trial start (once) | pilot-shell.com |
Hashed hardware fingerprint |
That's it — three calls total, each sent at most once (validation re-checks daily). No OS, no architecture, no Python version, no locale, no analytics, no heartbeats. The validation result is cached locally, and Pilot Shell works fully offline for up to 7 days between checks. Beyond these licensing calls, the only external communication is between Claude Code and Anthropic's API — using your own subscription or API key.
Is Pilot Shell enterprise-compliant for data privacy?
Yes. Your source code, project files, and development context never leave your machine through Pilot Shell. The only external calls are license validation (daily, license key only) and one-time activation/trial start (machine fingerprint only). No OS info, no version strings, no analytics, no telemetry. Enterprises using Claude Code with their own API key or Anthropic Enterprise subscription can add Pilot Shell without changing their data compliance posture.
What are the licenses of Pilot Shell's dependencies?
All external tools and dependencies that Pilot Shell installs and uses are open source with permissive licenses (MIT, Apache 2.0, BSD). This includes ruff, basedpyright, Prettier, ESLint, gofmt, uv, Probe, playwright-cli, and all MCP servers. No copyleft or restrictive-licensed dependencies are introduced into your environment.
Do I need a separate Anthropic subscription?
Yes. Pilot Shell enhances Claude Code — it doesn't replace it. You need an active Claude subscription — Max 5x or 20x for solo developers, Team Premium for teams, or Enterprise for organizations with compliance or procurement requirements. Pilot Shell adds quality automation on top of whatever Claude Code access you already have.
Does Pilot Shell work with Codex, Gemini CLI, OpenCode, or other AI coding tools?
No. Pilot Shell is built exclusively for Claude Code. Every hook, rule, command, and workflow is engineered specifically for Claude's tool-use protocol, prompt format, and session lifecycle. Pilot Shell also only supports Claude Sonnet 4.6 and Claude Opus 4.6 — these are the models that produce the best results, and every rule and prompt is optimized for their behavior. Supporting other tools or models would mean compromising on quality, which is the opposite of what Pilot Shell is designed to do.
Does Pilot Shell work with existing projects?
Yes — that's the primary use case. Pilot Shell doesn't scaffold or restructure your code. You install it, run /sync, and it explores your codebase to discover your tech stack, conventions, and patterns. From there, every session has full context about your project. The more complex and established your codebase, the more value Pilot Shell adds — quality hooks catch regressions, persistent memory preserves decisions across sessions, and /spec plans features against your real architecture.
Does Pilot Shell work with any programming language?
Pilot Shell's quality hooks (auto-formatting, linting, type checking) currently support Python, TypeScript/JavaScript, and Go out of the box. TDD enforcement, spec-driven development, persistent memory, context preservation hooks, and all rules and standards work with any language that Claude Code supports. You can add custom hooks for additional languages.
Can I use Pilot Shell on multiple projects?
Yes. Pilot Shell installs once globally and works across all your projects — you don't need to reinstall per project. All tools, rules, commands, and hooks live in ~/.pilot/ and ~/.claude/, available everywhere. Just cd into any project and run pilot. Each project can optionally have its own .claude/ rules, custom skills, and MCP servers for project-specific behavior. Run /sync in each project to generate project-specific documentation and standards.
Do I need to run the installer from inside a project directory?
No. You can run the installer from any directory — your home folder, a parent folder containing multiple repos, anywhere. Everything installs globally to ~/.pilot/ and ~/.claude/. The only file written to the current directory is .nvmrc (a Node.js version hint).
Should I still use Claude Code's built-in plan mode (Shift+Tab)?
No — use /spec instead. Claude Code's built-in plan mode (Shift+Tab → "plan") is unstructured: plans live only in the conversation, have no consistent format, aren't saved as files, and disappear when the session ends. There's no verification, no TDD enforcement, and no way to resume or review a plan later.
/spec is a drop-in replacement that fixes all of this. Plans are written as structured markdown files in docs/plans/ with a consistent format — scope, tasks, definition of done, and approval status. They persist across sessions, can be edited before approval, and drive a complete workflow: plan → implement with TDD → verify with code review. The plan file becomes the single source of truth for the entire task.
Use /spec for all planned work. Use Quick Mode (regular chat) for small tasks and exploration. There's no reason to use Claude Code's built-in plan mode when Pilot Shell is installed.
Why does Pilot Shell use bypass permissions mode?
Pilot Shell sets Claude Code to bypassPermissions mode by default so the /spec workflow can run autonomously — planning, implementing, and verifying without pausing for permission prompts at every tool call. This is what enables the end-to-end spec-driven development experience.
In Quick Mode (regular chat), you have full control. Press Shift+Tab at any time to cycle through Claude Code's permission modes:
| Mode | Behavior |
|---|---|
| Plan | Claude proposes changes, you approve before execution |
| Accept Edits | File edits auto-approved, other actions still prompt |
| Normal | Fine-grained permission prompts for each tool call |
You can also set a persistent default in ~/.claude/settings.json by changing the defaultMode field to acceptEdits, default, plan, or dontAsk. Pilot Shell preserves your choice across updates — the installer merges permissions additively and never overwrites user customizations.
Can I add my own rules, commands, skills, and agents?
Yes. Create your own in your project's .claude/ folder — rules, commands, skills, and agents are all plain markdown files. Your project-level assets load alongside Pilot Shell's built-in defaults and take precedence when they overlap. /sync auto-discovers your codebase patterns and generates project-specific rules. /learn extracts reusable knowledge from sessions into custom skills. Manage sharing via the skillshare CLI and view all shared assets on the Console Share page.
For monorepos, organize rules in nested subdirectories by product and team (e.g. .claude/rules/my-product/team-x/). Team-level rules must use paths frontmatter so they only load when working on relevant files. /sync validates this structure, enforces path-scoping, and generates a README.md to document the organization.
Can I use Pilot Shell inside a Dev Container?
Yes. Copy the .devcontainer folder from this repository into your project, adapt it to your needs (base image, extensions, dependencies), and install Pilot Shell inside the container. Everything works the same — hooks, rules, MCP servers, persistent memory, and the Console dashboard all run inside the container. This is a great option for teams that want a consistent, reproducible development environment.
See the full changelog at pilot.openchangelog.com.
Pull Requests — New features, improvements, and bug fixes are welcome. You can improve Pilot Shell with Pilot Shell — a self-improving loop where your contributions make the tool that makes contributions better.
Bug Reports — Found a bug? Open an issue on GitHub.
Claude Code is powerful. Pilot Shell makes it reliable.