Pilot Shell: a harness layer for Claude Code and Codex CLI

The gap Pilot Shell is built to close

Claude Code and Codex CLI are fast at producing code. The README frames the remaining problem as everything around that generation: durable context, disciplined implementation, quality control, and evidence that the finished system runs. Pilot Shell is aimed at engineers who already use one of those agents daily and have hit the point where a session ends, context is compacted, and decisions made earlier are gone.

The stated audience is specific. The prerequisites require at least one agent: Claude Code, described as primary with full feature coverage, or Codex through Codex CLI or the ChatGPT desktop app, described as supporting all workflows with fewer platform features. Both paths assume a paid subscription, with Claude Max 5x or 20x named for solo users, Team Premium for teams, and Enterprise for organizations, and OpenAI Plus or Pro for solo Codex users with Business or Enterprise for teams. If you are not already paying for one of these, Pilot Shell has nothing to attach to.

What actually sits between you and the model

Pilot Shell does not replace the agent. It integrates through the agent's own extension points, which the README lists as rules, hooks, skills, subagents and MCP. The repository layout matches that claim: there are .agents/ and .claude/ directories at the top level alongside AGENTS.md and CLAUDE.md, plus a pilot/ directory and a console/ directory for the human-facing side.

The README is explicit that rules, skills and persistent memory are coordinated parts of the harness rather than the product on their own. The functional claim is that relevant source, architecture, project standards, prior decisions and session state survive long work and compaction, and that findings are remembered across both Claude Code and Codex. Quality control is layered: hooks, stop guards, independent reviews, full test and build gates, and browser or device verification. The stated purpose of that stack is to prevent what the README calls looks-done handoffs.

Workflow neutrality is a design decision worth noting. Direct requests, the agents' native Plan and Goal tools, and Pilot's own workflows are described as peer ways to work inside the same harness. The structured commands (/spec, /build, /fix, /prd) add durable artifacts and lifecycle contracts, but the README says they do not become routing rules for ordinary requests. That is a deliberate constraint: the harness should not force ceremony onto a one-line change.

Installing Pilot Shell and running your first session

Install the agent first. The README points Claude Code users at the native installer and warns that the npm or brew version must be uninstalled first. Codex users install Codex CLI or the ChatGPT desktop app. Only then does the Pilot installer make sense.

The install itself is a single piped script. It installs globally on macOS, Linux, and Windows under WSL2, and the README claims under two minutes.

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

After that, you do not launch anything new. You run the agent as usual, and Pilot Shell loads automatically.

claude

On macOS with the ChatGPT desktop app, the README says to restart the app and open the project there instead. Updates are checked with pilot update.

pilot update

If a release breaks something, the README documents a downgrade path: export the version you want and rerun the same installer script.

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

Removal is a separate script. The README states it removes Pilot's runtime, Console, statusline, hooks, managed skills, rules and agents, MCP entries, settings injections and shell aliases, while preserving Claude Code, Codex, project files, shared external tools and user data.

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

Where the harness model creates friction

Installing a harness means injecting settings into tools you already depend on. The uninstaller documentation is candid about the footprint: settings injections, MCP entries, hooks and shell aliases all have to be removed. That is the honest cost of this design, and it is also the failure mode. If the uninstaller misses an entry, your agent configuration carries Pilot state you did not ask for. The README describes an interactive uninstaller that asks separately about removing proven Pilot-owned external tools and purging Pilot data, then shows a final removal preview. That preview is the thing to read before confirming.

Platform coverage is uneven by design. Claude Code is the primary target with full feature coverage; Codex gets all workflows but fewer platform features. Windows support means WSL2, not native Windows. If your team is standardized on Codex on Windows, you are on the thinner path twice over.

The subscription requirement is the harder boundary. Pilot Shell is not a way to get agentic coding without paying for an agent. There is no local model path documented in the README, and the prerequisites name specific paid tiers. For a solo developer without a Claude or OpenAI subscription, this project is simply not applicable.

Finally, the quality gates cut both ways. Hooks, stop guards and full test and build gates add latency and can block a session that a developer considers finished. The README presents this as the point, and it is, but it is a trade-off against the speed that made the underlying agents attractive.

How this differs from writing your own rules and skills

The realistic alternative is not another product. It is the same agent with a hand-rolled CLAUDE.md or AGENTS.md, a few custom skills, and whatever review habits your team already has. That approach costs nothing and has no installer footprint.

The difference is coordination. A hand-written rules file supplies context and stops there. Pilot Shell's stated design coordinates context with enforcement: hooks and stop guards that fire during a session, independent reviews, and test, build, browser or device verification before a task is called complete. It also carries state across sessions and across both agents, which a static markdown file does not do.

Whether that coordination is worth the footprint depends on team size and turnover. One developer with a stable codebase can keep a rules file accurate by hand. A rotating team on a long-lived codebase is exactly the case where persistent decisions and enforced gates stop being optional, and it is the case the README is written for. The structured /spec, /build, /fix and /prd commands are the clearest expression of that: they produce durable artifacts rather than transient chat.

Maintenance, releases and licence status

The last push to the repository was on 2026-09-09, and the most recent releases are v11.0.0, v11.0.1 and v11.0.2, all dated within three days of each other in early September 2026. That is a fast release cadence on a major version number, which matters for upgrade planning: the README's downgrade instructions exist because version churn is expected, and the VERSION environment variable is the documented escape hatch.

Upgrade cost is low by design. Updates are checked with pilot update, and the installer is re-runnable for both upgrade and downgrade. The real cost is re-verifying your agent configuration after each update, since the project injects hooks, settings and MCP entries.

On licensing, the repository metadata reports NOASSERTION, which means GitHub could not match the LICENSE file to a known SPDX identifier. The LICENSE file exists at the top level, but its terms are not summarized here. Read it directly before commercial use, and treat the NOASSERTION label as a signal that you need to check the actual text rather than assume a standard licence.

Editorial conclusion

Adopt Pilot Shell if you already pay for Claude Code or Codex and your problem is context loss, unverified completion claims or review discipline rather than raw generation speed. Skip it if you have no agent subscription, if you work on Windows outside WSL2, or if you cannot accept hooks and settings injections inside your agent configuration. Verify first that the installer detects the agent you actually use, that the uninstaller removes what it claims to remove, and that the Codex path gives you the workflows you need, since the README states Claude Code has full feature coverage while Codex gets all workflows but fewer platform features.

Frequently asked questions

Official sources

1. Issues
2. maxritter/pilot-shell on GitHub
3. Project website
4. README
5. Releases