Harness for Claude Code and Codex

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, RTK, 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.

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

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

# 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

# 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

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                codex

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

Pilot Workflows

Pilot's four structured workflows remain available when their explicit artifact or lifecycle contract is useful.

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

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.

Explore the Console →

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.