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 | bashmacOS · 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/prdadd 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
npmorbrewversion, 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 | bashInstalls 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.8 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 | bashThe 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 originally Pilot-installed curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash -s -- --remove-tools # Also delete Pilot memories, sessions, logs, configuration, and unknown files curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash -s -- --purge-data
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) # 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.
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 is not detected. The installer does not install Claude Code, Codex CLI, or ChatGPT itself; install at least one yourself per the prerequisites above.
- 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.
- 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. - 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. - Codex files — Codex-specific assets: adapted skills →
~/.agents/skills/, review agents →~/.codex/agents/, guidance →~/.codex/AGENTS.md, a provider-derived model catalog that preserves new entries while lifting GPT-5.6 and Astra to their published context ceiling →~/.codex/.pilot-model-catalog.json, plus merged~/.codex/config.tomland~/.codex/hooks.json. Skipped when neither Codex CLI nor the ChatGPT-bundled Codex binary is detected. - Config files — Creates
.nvmrcand project config. - Dependencies — Installs the latest checksum-verified Open Claude Design release; the pinned Impeccable CLI, skills, supporting agents, and detector with provider hooks left opt-in; Semble; CodeGraph; ast-grep; Chrome DevTools MCP; playwright-cli; agent-browser; language servers; and the
codex@openai-codexClaude marketplace plugin. Agent-specific dependencies still skip when their target agent is absent. Homebrew is preferred for ast-grep, with an audited pinned npm fallback for hosts without Brew. - Shell integration — Auto-configures bash, fish, and zsh with the
pilotadmin alias and a Codex wrapper that raises a low per-process open-file soft limit without lowering a higher one. - Finalize — Success message with next steps.
First Steps
Start either agent in any project. Work directly, use the agent's native Plan/Goal tools, or invoke a Pilot workflow — these are peer choices, and the same harness stays active around each one.
# Claude Code # Codex CLI
claude codexWhen you want repository-specific shared guidance, run /setup-rules in Claude Code or $setup-rules in Codex. It reads the codebase, discovers conventions, and prepares synchronized rules and MCP guidance; it is useful setup, not a prerequisite for using Pilot.
Use /create-skill to capture a repeatable procedure and /benchmark to measure whether guidance improves output. See Other Pilot Workflows for the full on-demand toolkit.
Ways of Working
Pilot supports three peer paths. Choose the contract that fits the work; none is the escalation path or preferred default for another.
| Path | What it adds |
|---|---|
| Direct request | The shortest route from a clear request to implementation and verification |
| Native agent Plan/Goal tools | The planning, task, approval, and persistence model built into Claude Code or Codex |
| Pilot workflows | Durable requirements, plans, criteria, TDD loops, reviews, and verification evidence |
Pilot Workflows
Pilot's four structured workflows remain available when their explicit artifact or lifecycle contract is useful.
| Workflow | Use it when | Contract |
|---|---|---|
/spec · $spec |
You want ordered tasks approved before implementation | Plan against the real codebase, implement with TDD, review independently, and verify end to end |
/build · $build |
The outcome is clear but the task list should evolve while building | Define acceptance criteria, build in rounds, and let an independent judge turn gaps into the next round |
/fix · $fix |
Existing behavior is broken | Reproduce the defect, write the RED test, repair the root cause, run the quality gate, and audit the result |
/prd · $prd |
The problem, audience, or scope is still unclear | Explore directions and produce a reviewable product requirement document |
/spec and /build are peers: choose /spec for an approved plan and /build for a goal measured by acceptance criteria. Size alone does not decide.
Requirement or goal → plan / criteria → TDD implementation → quality gates
↑ ↓
└─ review and runtime verification loop
Requirements, plans, buildouts, tasks, criteria, and verification evidence live in durable files under docs/. Stop guards keep the workflow open until the obligations pass or are reported unresolved.
Explore all workflow details →
Other Pilot Workflows
Use these on demand; the full procedures live in the documentation.
| Workflow | Purpose |
|---|---|
/investigate · $investigate |
Trace one codebase question with cited evidence and no edits |
/cleanup · $cleanup |
Corroborate dead-code candidates without deleting anything |
/setup-rules · $setup-rules |
Generate modular project guidance from the real codebase |
/create-skill · $create-skill |
Capture and test a reusable procedure |
/benchmark · $benchmark |
Measure a rule or skill against falsifiable before/after evals |
Visual Engineering
Pilot installs Open Claude Design and Impeccable as complementary parts of the harness. Open Claude Design connects the real codebase and coding agent to Claude Design's visual workspace; Impeccable adds focused refinement workflows and deterministic checks.
Ask normally—the design workflow loads in the background, keeps code and design synchronized, and feeds the result into Pilot's implementation and verification process.
Pilot Shell Console
The local Console at localhost:41777 makes the harness visible and steerable.
- Review and annotate requirements, specifications, buildouts, and diffs; feedback flows back into the work that owns them.
- Recover Claude Code and Codex sessions and search source-linked project knowledge.
- Inspect progress, verification evidence, notifications, changes, usage, and costs.
- Manage workflow settings and shared rules, skills, commands, and agents.
Memory capture runs automatically in the background across Claude Code and Codex. Pilot selects an available low-cost provider, handles temporary quota failures, and keeps saved findings searchable without a model call. This adds project history alongside each agent's native context.
Team sharing is optional: keep stored memory local, or let useful findings travel through your project's normal Git commits and pulls. How automatic memory works.
Documentation
For full details on every component, see the Documentation.
Changelog
See the full changelog at GitHub Releases.
Contributing
Found a bug or missing a feature? Open an issue on GitHub.
License
See LICENSE.
How real engineers run Claude Code and Codex
Made with 🩵 by Max Ritter