pilot-shell

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.

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
• /build — names a goal, then runs autonomously: judge loops until criterion passes
• /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
• Memory sharing — share captured memories with your team through the project repo
• 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

Prerequisites

At least one AI agent: Pilot Shell supports Claude Code (primary — full feature coverage) and Codex through Codex CLI or the ChatGPT desktop app (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: Install Codex CLI or the ChatGPT desktop app. Pilot detects the CLI and the Codex binary bundled with ChatGPT on macOS. 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 or ChatGPT desktop, 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, run claude or codex directly. On macOS, you can instead restart ChatGPT desktop and open the project there. Pilot Shell loads automatically in either Codex client. Run pilot update to check for updates.

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=10.6.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

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)
# Using CLAUDE_CONFIG_DIR? Substitute it for ~/.claude, and back up
# "$CLAUDE_CONFIG_DIR/.claude.json" instead of ~/.claude.json.
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.

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

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 is not detected. The installer does not install Claude Code, Codex CLI, or ChatGPT 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, Codex CLI, or the Codex binary bundled with ChatGPT on macOS) 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, canonical raw sources → ~/.pilot/rules/, ~/.pilot/skills/, and ~/.pilot/agents/. Each agent's adapter consumes these sources in its own format. Always runs.
3. Claude files — Claude-specific assets under the Claude config directory ($CLAUDE_CONFIG_DIR, else ~/.claude): rules, sub-agents, settings.json (three-way merged), plus the Claude post-install merges (hooks into settings, app-config 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/, guidance → ~/.codex/AGENTS.md, an expanded GPT-5.6 Sol model catalog → ~/.codex/.pilot-model-catalog.json, plus merged ~/.codex/config.toml and ~/.codex/hooks.json. Skipped when neither Codex CLI nor the ChatGPT-bundled Codex binary is 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 and a Codex wrapper that raises a low per-process open-file soft limit without lowering a higher one.
8. Finalize — Success message with next steps.

macOS and Codex open-file limits: The Codex CLI wrapper raises a low soft limit toward 1024 for that Codex process, never exceeding the hard limit or chan