pilot-shell

How real engineers run Claude Code and Codex

Professional context and harness engineering around the coding agents you already use. Persistent knowledge. Enforced quality. Runtime proof.

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.

---

[!TIP] Pilot's open design companion: Open Claude Design connects Claude Design to the coding agent you already use, with codebase-grounded creation and conflict-aware synchronization. Pilot installs it together with Impeccable, so product context, visual iteration, deterministic checks, and engineering verification work as one design layer.

---

Why Pilot Shell

Claude Code and Codex CLI write code fast — but production-grade software still needs durable context, disciplined implementation, quality control, and proof that the finished system works.

Pilot Shell is a professional context and harness engineering system—not a collection of rules and skills. It coordinates the complete engineering process around the model:

• Quality on every layer — hooks, stop guards, independent reviews, full test/build gates, and browser or device verification prevent “looks done” handoffs
• Persistent context — relevant source, architecture, project standards, prior decisions, and session state survive long work and compaction, with useful findings remembered automatically across Claude Code and Codex
• Professional toolchain — Semble, CodeGraph, ast-grep, language servers, browser automation, and MCP integrations support discovery, structural search, impact analysis, implementation, and runtime proof
• Runtime verification — tests, builds, real CLI/API execution, browser automation, and device checks turn completion claims into evidence
• Human control plane — the Console connects plan and diff review, annotations, progress, evidence, session recovery, shared project knowledge, and usage
• Workflow neutrality — direct requests, native Plan/Goal tools, and Pilot workflows are peer ways to work inside the same harness
• Structured delivery when wanted — /spec, /build, /fix, and /prd add durable artifacts and explicit lifecycle contracts without becoming routing rules for ordinary requests
• One system for Claude Code and Codex — platform-specific adapters preserve one engineering standard while the underlying models continue to improve

Rules, skills, and persistent memory are coordinated parts of this harness. They supply context; they are not the product by themselves. For a longer practitioner’s explanation, read How to build production-ready software assisted with AI tools.

---

Getting Started

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 on macOS): Zentty works especially well with Pilot Shell — its worklanes keep parallel agents and dev servers in separate contexts and show you when a pane needs attention. 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.

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

Uninstalling

Removes Pilot's runtime, Console, statusline, hooks, managed skills/rules/agents, MCP entries, settings injections, and shell aliases. Claude Code, Codex, project files, shared external tools, and user data are preserved:

curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash

The interactive uninstaller asks separately whether to remove proven Pilot-owned external tools and whether to purge Pilot data, then shows the final removal preview. The prompts use the controlling terminal, so they also work with the piped command above.

Optional cleanup stays explicit:

# Also remove external tools that Pilot recorded as or