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, codebase-memory-mcp, playwright-cli, 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

Specific version (see releases):

export VERSION=7.7.1
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash

Uninstall — 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.

Line 1 — Session Metrics (separated by |):

Line 2 — Mode:

• Quick Mode: Quick Mode · /spec for feature implementation and complex bugfixes
• Spec Mode: Plan name, type (feature/bugfix), phase (plan/implement/verify), progress bar, task count, iteration count, and config flags (plan-rev, spec-rev, wt — green = on, dim = off)

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.

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.

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.

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 codebase-memory-mcp
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.

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.

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

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.

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, RTK, codebase-memory-mcp, playwright-cli, and all MCP servers. No copyleft or restrictive-licensed dependencies are introduced into your environment.

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.

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.

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

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.

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 — using Claude Code's Remote Control feature. Start a session via pilot on your computer, then type /remote-control to make it accessible from the Claude Mobile App (iOS/Android) under the Code tab. You can also enable it globally via /config → "Enable Remote Control for all sessions". Remote Control requires the native install of Claude Code (curl -fsSL https://claude.ai/install.sh | bash), not the npm version. Your computer must stay awake — on macOS, use Amphetamine to keep your Mac awake with the display off. To start sessions directly from your phone, install Termius on your mobile device, SSH into your computer, and run pilot. For SSH access outside your home network, install Tailscale on both devices — the Claude App approach works everywhere without extra setup. Troubleshooting: If Remote Control doesn't connect, run /logout followed by /login inside Claude Code to re-authenticate.

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.