Pilot Shell

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=8.7.0
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

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:

1. Prerequisites — Checks/installs Homebrew, Node.js, Python 3.12+, uv, git, jq
2. Claude files — Sets up ~/.claude/ plugin — rules, commands, hooks, MCP servers
3. Config files — Creates .nvmrc and project config
4. Dependencies — Installs Probe, RTK, CodeGraph, context-mode (better-sqlite3), Chrome DevTools MCP, playwright-cli, agent-browser, language servers
5. Shell integration — Auto-configures bash, fish, and zsh with pilot alias
6. VS Code extensions — Installs recommended extensions for your stack
7. Finalize — Success message with next steps

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 → for UI features, writes E2E test scenarios (step-by-step, browser-executable) that become the verification contract → spec-review sub-agent validates completeness → waits for your approval. Optional Codex adversarial review provides an independent second opinion when enabled.

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) → for UI features, executes each E2E scenario step-by-step via browser automation (pass/fail tracked, results written to plan) → auto-fixes findings → squash merges to main on success.

For local bugs. Single file, obvious-once-traced root cause. No plan file, no approval mid-flow, no separate verify phase. TDD still enforced — bugfixes without a failing test don't ship.

• Investigate: Reproduce the bug → trace to root cause at file:line with codegraph_context + targeted reads → state confidence (High/Medium required to proceed). For UI / async / race bugs, add temporary SPEC-DEBUG:-marked logs at component boundaries before tracing.
• RED: Write the failing test via an existing public entry point → run, must fail with the documented symptom.
• Fix: Minimal change at the root cause. Symptom patches are forbidden. Reproducing test must pass, then the targeted test module. Diff sanity check (root-cause file in diff, no unplanned files, < 20 lines, symptom-patching grep) catches issues with the fix itself.
• Verify End-to-End: The primary correctness signal. Run the actual program with the original input (Claude Code Chrome → Chrome DevTools MCP → playwright-cli → agent-browser for UI; CLI / API / REPL / job trigger for non-UI) and capture concrete evidence. A passing unit test alone is never accepted as proof.
• Quality Gate: Lint + types + build + full anti-regression suite, once.
• Bail-out: If investigation reveals the bug is multi-component, architectural, needs defense-in-depth at multiple layers, or two fix attempts have failed, /fix stops cleanly and tells you to re-invoke with /spec. It does not silently switch lanes.

When you type /spec "<bug description>", the full bugfix workflow runs — for bugs that warrant a written plan, approval, code review, and the full verify ceremony.

• Behavior Contract: every plan pins down Given / When / Currently / Expected / Anti-regression — the invariant the fix must produce and the behavior it must not break
• Three uniform tasks (always, regardless of bug size): Write Reproducing Test (RED) → Implement Fix at Root Cause → Quality Gate
• Verify audit: always-on cp+trap revert-test (proves the reproducing test would genuinely fail without the fix — rules out retroactive rubber-stamp tests) + root-cause-at-source audit (flags symptom patches and caller-side workarounds) + original-symptom re-check — no sub-agents, tests carry the proof
• Iteration cap at 3: after three failed verify cycles, the workflow stops and asks if the bug is architectural rather than letting you loop forever

When to use /prd over /spec: /prd is for what and why; /spec is for how. Reach for /prd first when you only have a problem statement, want to riff across multiple directions, or need scope boundaries defined before someone starts building.

Flow: two modes, picked automatically from how fuzzy the idea is:

1. Ideate — free-form prose, Claude pitches 3-5 directions, you react (only runs when the idea is vague)
2. Clarify → Converge → Write — structured multiple-choice questions once the shape is known, then the PRD is written

Research tiers (picked at the start):

The final PRD covers problem statement, core user flows, scope boundaries, and technical context — then offers to hand off directly to /spec for implementation.

12 phases that read your codebase and produce comprehensive AI context:

0. Reference — load best practices for rule structure, path-scoping, and quality standards
1. Read existing rules — inventory all .claude/rules/ files, detect structure and path-scoping. Also detects CLAUDE.md and AGENTS.md (the cross-framework agent context file used by Codex, Cursor, etc.)
2. Migrate unscoped assets — prefix with project slug for better sharing
3. Quality audit — check rules against best practices (size, specificity, stale references, conflicts)
4. Explore codebase — semantic search with Probe CLI, structural analysis with CodeGraph
5. Compare patterns — discovered vs documented conventions
6. Sync project rule — update {slug}-project.md with current tech stack, structure, commands. Migrates CLAUDE.md / AGENTS.md content into modular rules
7. Sync MCP docs — smoke-test user MCP servers, document working tools
8. Discover new rules — find undocumented patterns worth capturing
9. Cross-check — validate all references, ensure consistency across generated files
10. Sync AGENTS.md — if AGENTS.md already exists, offer to re-export the updated rules into it so non-Claude agents see the same context. Always asks first, never creates the file if absent, preserves user-authored sections
11. Summary — report all changes made

For monorepos: Organizes rules in nested subdirectories by product and team, with paths frontmatter to scope rules to specific file types. Generates a README.md documenting the structure.

6 phases that turn domain knowledge into a reusable skill:

1. Reference — load use case categories, complexity spectrum, file structure template, description formula, security restrictions
2. Understand — explore the codebase for relevant patterns, ask clarifying questions, or evaluate the current session for extractable knowledge
3. Check existing — search project and global skills to avoid duplicates
4. Create — write to .claude/skills/ (project) or ~/.claude/skills/ (global), apply portability and determinism checklists
5. Quality gates — structure checklist (SKILL.md naming, frontmatter fields), content checklist (error handling, examples, exclusions), triggering test (should/shouldn't trigger), iteration signals
6. Test & iterate — run test prompts with sub-agents, evaluate results, optimize description triggering

Use case categories:

Skill structure: Each skill is a folder with a SKILL.md file (case-sensitive), optional scripts/, references/, and assets/ directories. The YAML frontmatter description determines when Claude loads the skill — it must include what the skill does, when to use it, and specific trigger phrases. Progressive disclosure keeps context lean: frontmatter loads always (~100 tokens), SKILL.md loads on activation, linked files load on demand.

Six phases turn a rule or skill into a before/after comparison with an actionable plan:

1. Intake — pick up an existing benchmarks/<target>/evals.json or author one

2. Target discovery — classify as skill or rules

3. Author evals — draft 3 falsifiable assertions; falsifiability gate ensures baseline actually fails

4. Execute — run both configs in isolated sandboxes; grader subagent scores every assertion

5. Present findings — three layers, scannable top-to-bottom:

   Layer	Content
   Verdict	One labeled sentence with a recommended next step. Delta bands: 🟢 Strong (≥ +0.50) / 🟢 Moderate (+0.20) / 🟡 Weak (+0.05) / ⚪ Indistinguishable (±0.05) / 🔴 Regression (< −0.05)
   Quadrant breakdown	Counts each assertion as Signal (✓/✗) / Baseline (✓/✓) / Unreachable (✗/✗) / Regression (✗/✓). The dominant quadrant drives the plan
   Per-eval drill-down	Only divergent assertions get a row; matching ones fold into header counts so the report stays under one screen

6. Improvement plan — ≤ 5 ranked proposals in a uniform format ([TARGET] or [EVALS] tag, location, current quote, replacement, "Lever" line). You pick: apply target edits, iterate on evals, both, or save the plan and stop. Re-runs land in a fresh runs/<ts>/ so iteration deltas stay legible.

Isolation: each run gets its own sandbox directory; a globally-installed copy of the target in ~/.claude/ is auto-hidden for the duration and restored afterward (with on-disk recovery manifest covering SIGKILL / power loss / segfault). Conditional-loading frontmatter (path: / paths:) is stripped from the copy installed into the with sandbox so the target loads unconditionally for every prompt — without that, rules scoped to e.g. paths: ["**/*.py"] would stay dormant in both configs and the delta would collapse to 0.00. The source file is never modified.

Key flags: --runs N (default 1), --configs with,without, --workers N, --model, --no-isolate-global, --restore-hidden.

Line 1 — Session Metrics (separated by |):

Line 2 — Mode:

• Quick Mode: Quick Mode
• Spec Mode: Plan name, type (feature/bugfix), phase (plan/implement/verify), progress bar, task count, and iteration count

Line 3 — Version & Session Info:

Pilot <version> (<tier>) · CC <version> (<subscription>) · sessions <N> · memories <N>

Pilot tier: Solo, Team, or Trial with time remaining. Claude subscription (Pro/Max/Team/Enterprise) detected via claude auth status and cached for 24 hours.

Each view with project-specific data has an inline Project Filter dropdown — switch projects without leaving the page. Dashboard stats tiles are clickable — navigate directly to the relevant view.

When a spec plan is pending approval, the Specifications tab defaults to Annotate mode. Two ways to annotate:

• Select text — highlight any passage and write a note via the floating toolbar
• Click + — hover over any block to add a note without selecting text

Annotations save automatically. The agent reads them at the next checkpoint, revises the plan accordingly, and asks for approval again. This turns plan review into a conversation — you mark what needs changing, the agent addresses it, you review again.

Share specs and requirements with teammates for async review — no cloud service required:

1. Share — Click Share with Teammate to generate a compressed link. The entire spec and annotations are encoded into the URL fragment, so no data is transmitted to any server.
2. Review — Your colleague opens the link in their Console (or on pilot-shell.com), sees your annotations, and adds their own feedback.
3. Import — Click Receive Feedback to import their annotations. Each annotation has per-item accept/reject controls — accepted annotations merge into your plan, rejected ones are removed from both the sidebar and inline markers.

Everything works locally. The link is self-contained — the recipient doesn't need access to your machine, repository, or any shared service.

After a spec completes all automated checks, the agent prompts you to review the changes in the Changes tab:

1. Enable Review mode — toggle it in the Changes tab header
2. Annotate diffs — click + on any diff line to add an inline note. Annotations save automatically.
3. Agent addresses feedback — the agent reads every annotation and resolves them before marking the spec as verified

This gives you a final quality gate with direct, line-level feedback — the same workflow as a PR review, but before the code ever leaves your machine.

Use /setup-rules to auto-generate rules from your codebase. Use /create-skill to capture workflows as reusable skills.

Project extensions live in .claude/ — commit them so teammates get them on git clone. Global extensions live in ~/.claude/ — personal and available across all projects. Move extensions between scopes with one click.

Plugin extensions come from installed Claude Code plugins (claude plugin install <name>). They appear as read-only items — visible but not editable.

Connect a git repository to share extensions across your team:

• Push local extensions to the team remote
• Pull remote extensions to your machine (global or project scope)
• Compare local vs remote with a built-in side-by-side diff view
• Conflict detection — when local and remote differ, choose which version to keep

APM format — check one box and your remote becomes an APM package, directly installable via apm install owner/repo by anyone using Copilot, Cursor, OpenCode, or Claude. Extensions are automatically converted to APM conventions on push:

APM-compatible frontmatter is injected automatically. An apm.yml manifest is generated. Toggling APM on/off migrates existing extensions in a single commit.

Replaced skill fragments stay pinned to upstream by hash. pilot customize status surfaces drift when Pilot upgrades a replaced step; pilot customize diff <skill>/<step-id> shows what changed so you can port improvements. See the Customization guide for the full schema.

The layout is the same whether you publish it as a git repo or keep it as a local folder. Directory names map 1:1 to ~/.claude/:

my-customization/
├── customization.json          # Required: metadata + optional skill overlays
├── settings.json               # Optional: deep-merges into ~/.claude/settings.json
├── claude.json                 # Optional: deep-merges into ~/.claude.json
├── .mcp.json                   # Optional: replaces ~/.claude/pilot/.mcp.json
├── .lsp.json                   # Optional: replaces ~/.claude/pilot/.lsp.json
├── skills/                     # → ~/.claude/skills/
│   ├── spec-plan/steps/
│   │   └── security-review.md  # New step injected into spec-plan
│   └── team-deploy/            # Brand-new skill
│       ├── manifest.json
│       ├── orchestrator.md
│       └── steps/01-stage.md
├── rules/                      # → ~/.claude/rules/
│   ├── team-standards.md       # Additive
│   └── testing.md              # Overrides core (same filename)
├── hooks/                      # → ~/.claude/pilot/hooks/
│   ├── team-lint-check.sh
│   └── hooks.json              # Registers team-lint-check.sh alongside Pilot's hooks
└── agents/                     # → ~/.claude/pilot/agents/
    └── team-reviewer.md

Only ship the files and directories you need. A repo with just rules/ is a valid customization; so is one with just .mcp.json.

No code, files, prompts, project data, or personal information ever leaves your machine through Pilot Shell. All development tools — code search (Probe), code intelligence (CodeGraph), 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:

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. If you enable the optional Codex plugin, adversarial reviews are sent to OpenAI's API — this is opt-in and disabled by default.

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.

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.

Pilot Shell is built for Claude Code and uses Anthropic's Claude models (Opus, Sonnet) for all planning, implementation, and verification. The Codex plugin is included and adds OpenAI-powered adversarial review during /spec — an independent second opinion on your plans and code changes. Run /codex:setup to authenticate, then enable the reviewers in Console Settings → Reviewers.

Yes — that's the primary use case. Pilot Shell doesn't scaffold or restructure your code. You install it, run /setup-rules, 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.

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 optimization, and all rules and standards work with any language that Claude Code supports. You can add custom hooks for additional languages.

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 /setup-rules in each project to generate project-specific documentation and standards.

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:

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.

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. /setup-rules auto-discovers your codebase patterns and generates project-specific rules. /create-skill builds reusable skills from any topic interactively. View and manage all extensions on the Console Extensions 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. /setup-rules validates this structure, enforces path-scoping, and generates a README.md to document the organization.

Yes — the Customization feature on Team and Enterprise plans lets you modify what Pilot Shell auto-installs, not just add alongside it. Tweak the built-in /spec workflow (insert a security-review step, replace the planning template, disable a step you don't need), adjust existing rules, register additional hooks, add review agents, change which MCP or LSP servers get configured, and override the auto-applied settings.json and claude.json. Source is either a git repo for your team or a local directory for personal use — no git needed for a one-off tweak.

On Team, every developer runs pilot customize install <source> once and stays in sync via pilot customize update. Skill overlays stay pinned to Pilot's upstream by hash, so when Pilot ships an improvement to a step you replaced, pilot customize status flags the drift and pilot customize diff shows you what changed.

Enterprise adds full source-code access to Pilot itself (launcher, console, all components) on top of everything Team gets — so you can fork, audit, and modify the entire stack for regulated environments. See the Customization guide for the full schema.

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.

For tighter isolation when working with untrusted code, layer Claude Code's /sandbox on top — the Dockerfile pre-installs bubblewrap, socat, iptables, and ipset so it works out of the box. See Anthropic's development containers and sandboxing docs for the hardening patterns.

pilot is for interactive development — you chat with Claude, use /spec for planned work or quick mode for ad-hoc tasks, and drive every session yourself. It's your daily coding tool.

pilot bot is for unattended automation — it launches Claude Code as a persistent background agent that runs 24/7. You define scheduled jobs (health checks, deployments, monitoring) and the bot executes them on a cron schedule with heartbeat monitoring. If the Telegram plugin is installed, you can send tasks to the bot from your phone and receive results back. Think of pilot as your IDE and pilot bot as your ops assistant.