github.com/maxritter/pilot-shell @v9.9.0

How real engineers run Claude Code and Codex

From requirement to production-grade code — planned, tested, verified.

Spec-driven plans. Enforced quality gates. Persistent knowledge.

Install • Features • Docs • Blog • Website • Changelog

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 and Codex CLI write code fast — but without structure, they skip tests, lose context, and produce 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:

• /prd — brainstorm ideas into clear requirements with optional deep research
• /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
• 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
• Pilot Bot — persistent automation agent with scheduled tasks and background jobs
• Extensions — reusable rules, skills, and MCP servers with team sharing and customization
• Console — local web dashboard with real-time notifications and session management

Getting Started

Prerequisites

At least one AI agent: Pilot Shell supports Claude Code (primary — full feature coverage) and Codex CLI (all workflows, fewer platform features). Install at least one before running the Pilot installer:

• Claude Code: Install via the native installer. If you have the npm or brew version, uninstall it first. Requires a Claude subscription — Max 5x or 20x for solo, Team Premium for teams, Enterprise for organizations.
• Codex CLI: Install via the native installer. If you have the npm or brew version, uninstall it first. Requires an OpenAI subscription — Plus or Pro for solo, Business or Enterprise for teams.

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.

Installation

Works with any existing project. Pilot Shell integrates with Claude Code and Codex CLI, using their built-in concepts (rules, hooks, skills, subagents, MCP) 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). After installation, just run claude or codex directly — Pilot Shell is loaded automatically. Run pilot update to check for updates.

Downgrade

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.9.0
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash

Uninstalling

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

Reset & Refresh

Over time, accumulated session logs and Pilot Shell's caches can slow things down. A periodic reset gives you a clean baseline:

# 1. If using Claude Code, log out first
/logout

# 2. Back up your current config (just in case)
mv ~/.claude.json ~/.claude.json.bak
mv ~/.claude       ~/.claude.bak
mv ~/.codex        ~/.codex.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. Re-activate your license, then start your agent
pilot activate <your-license-key>
claude   # or: codex

Once Pilot Shell is running smoothly again, you can delete the .bak copies. Forgot your license key? Recover it in the Pilot members area.

Using a Dev 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.

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

What the installer does

8-step installer with progress tracking, rollback on failure, and idempotent re-runs. Steps 3 and 4 are agent-conditional — they skip cleanly when the matching agent CLI is not detected. The installer does not install Claude Code or Codex CLI itself; install at least one yourself per the prerequisites above.

1. Prerequisites — Checks/installs Homebrew, Node.js, Python 3.12+, uv, git, jq. Verifies at least one supported agent (Claude Code or Codex CLI) is on the system; aborts with a clear error otherwise.
2. Pilot files — Agent-neutral Pilot Shell-managed assets. Hooks → ~/.pilot/hooks/, Console scripts/UI → ~/.pilot/, MCP server template → ~/.pilot/.mcp.json, raw rule sources → ~/.pilot/rules/ (read by Codex's adapter), plus the canonical skill source at ~/.claude/skills/ (Claude reads natively; Codex adapts in step 4). Always runs.
3. Claude files — Claude-specific assets under ~/.claude/: rules, sub-agents, settings.json (three-way merged), plus the Claude post-install merges (hooks into settings, ~/.claude.json MCP block, model config migration). Skipped when Claude Code CLI is not detected.
4. Codex files — Codex-specific assets: adapted skills → ~/.agents/skills/, review agents → ~/.codex/agents/, ~/.codex/AGENTS.md, ~/.codex/config.toml, ~/.codex/hooks.json. Per-category counts mirror the Claude section. Skipped when Codex CLI is not detected.
5. Config files — Creates .nvmrc and project config.
6. Dependencies — Installs Semble, RTK, CodeGraph, Chrome DevTools MCP, playwright-cli, agent-browser, language servers, and the codex@openai-codex Claude marketplace plugin (skipped on Codex-only systems alongside Chrome DevTools MCP and LSP plugins).
7. Shell integration — Auto-configures bash, fish, and zsh with the pilot admin alias.
8. Finalize — Success message with next steps.

First Steps

Run these commands once in each new project after installing Pilot Shell:

# Claude Code         # Codex CLI
claude                codex
> /setup-rules        > $setup-rules

/setup-rules reads your codebase, discovers your conventions, and generates project-specific rules and MCP server docs — this is how Pilot learns your project. Run it once to start, then again after major architectural changes.

Once your rules are in place, use /create-skill to capture any repeatable workflow as a reusable skill, and /benchmark to measure whether your rules and skills are actually improving outputs. See Additional Workflows for full details on all three.

Core Workflows

Three commands cover the full development cycle — from vague idea to shipped feature. Quality hooks and TDD enforcement run automatically on every task.

/prd — Brainstorm Ideas Into Product Requirements Documents

/prd is the brainstorming surface for ideas that aren't specs yet — vague problem statements and fuzzy shapes. It pitches directions, pressure-tests them with you, and converges on a PRD you can hand to /spec. PRDs are saved to docs/prd/ and visible in the Console's Requirements tab.

# Claude Code                                                  # Codex CLI
claude                                                          codex
> /prd "Add real-time notifications for team updates"           > $prd "Add real-time notifications for team updates"

How /prd works

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, the agent 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.

/spec — Spec-Driven Development

/spec is for new features, refactoring, and architectural work. It provides a complete planning workflow with TDD, verification, and code review (on Claude Code, it replaces the built-in plan mode at Shift+Tab). Collaborative spec review shifts review left — share a single link, teammates annotate inline, feedback flows back into the Console grouped by author.

# Claude Code                                        # Codex CLI
claude                                                codex
> /spec "Add user authentication with OAuth and JWT"  > $spec "Add user authentication with OAuth and JWT"

Discuss  →  Plan  →  Approve  →  Implement (TDD)  →  Verify  →  Done
                                                        ↑         ↓
                                                        └── Loop──┘

How /spec works

/spec auto-detects whether the request is a feature or a bugfix and routes to the right workflow. The three phases below apply to both — the verify step differs slightly (features get E2E scenarios; bugfixes get a Behavior Contract audit, see the /fix section below).

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 in Claude Code or Codex → waits for your approval. Optional Codex Companion Reviewers provide a Claude Code plugin 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 → changes review (mechanism per the Console's Changes Review Mode setting in Claude C