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

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.

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.

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.

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