Pilot Shell: a harness layer for Claude Code and Codex CLI
Professional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.
At a glance
- What is it?
- Pilot Shell wraps the coding agents you already pay for with hooks, memory, quality gates and a review console. It is a workflow commitment rather than a drop-in plugin, and the licence file does not name a standard licence.
- Who is it for?
- Adopt Pilot Shell if you already hold a Claude Max, Team or Enterprise subscription (or an OpenAI Plus, Pro, Business or Enterprise plan) and you want the same engineering standard applied across Claude Code and Codex. Skip it if you work outside those two agents, if you need a named OSI licence before you can ship, or if you are on the npm or brew build of Claude Code, since the prerequisites require uninstalling those first.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap Pilot Shell targets: agents that finish before the code works
Coding agents are good at producing a plausible diff. The README frames the problem bluntly: Claude Code and Codex CLI write code fast, but production software still needs durable context, disciplined implementation, quality control, and proof that the finished system works. The failure mode it names is the looks-done handoff, where a session ends with a summary that no test, build or browser check has confirmed.
The audience is narrow and specific. You need an existing paid agent subscription before anything else: Claude Max 5x or 20x for solo work, Team Premium for teams, Enterprise for organizations, or an OpenAI Plus, Pro, Business or Enterprise plan. Pilot Shell is not a model and not an agent. It installs around one you already run and changes how that agent behaves inside a repository. If you have not picked an agent yet, this project has nothing to offer you.
What the harness actually coordinates
The README describes the architecture as coordinated parts rather than a rule pack. Rules, skills and persistent memory supply context; the README states explicitly that they are not the product by themselves. Around them sit hooks and stop guards that fire at defined points, independent reviews, and full test and build gates. Runtime verification extends past the terminal into browser automation and device checks.
Context persistence is the second pillar. Relevant source, architecture notes, project standards, prior decisions and session state are meant to survive long sessions and compaction, and findings are remembered automatically across both Claude Code and Codex. The toolchain listed in the README is Semble, CodeGraph, ast-grep, RTK, language servers, browser automation and MCP integrations. Those names are given without per-tool documentation in the supplied material, so how each one is wired is not something I can describe.
A Console provides the human side: plan and diff review, annotations, progress, evidence, session recovery, shared project knowledge and usage. Structured delivery is opt-in through slash commands. The README names /spec, /build, /fix and /prd, and is careful to say these add durable artifacts and explicit lifecycle contracts without becoming routing rules for ordinary requests. Direct requests and the native Plan and Goal tools remain peer ways to work.
Install commands and the update path
Installation is a single piped script:
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
The README states it installs globally on macOS, Linux and Windows under WSL2, and that it works with any existing project. After installation you run claude or codex directly. On macOS you can instead restart the ChatGPT desktop app and open the project there; the README says Pilot Shell loads automatically in either Codex client.
Updates go through pilot update. To pin a version, the README gives this pattern:
export VERSION=11.0.2 curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
The uninstall script is published at uninstall.sh in the same repository and is described as removing 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. The README notes the interactive prompts use the controlling terminal, so they still work when the script is piped. Removal of Pilot-owned external tools and purging of Pilot data are separate prompts, which means a default uninstall leaves some things behind unless you answer the follow-ups.
Claude Code is the primary target; Codex gets fewer platform features
The prerequisites section is the clearest statement of asymmetry in the whole README. Claude Code is labelled primary with full feature coverage. Codex, through Codex CLI or the ChatGPT desktop app, gets all workflows but fewer platform features. The README does not enumerate which platform features are missing on Codex, so if your team is Codex-only, that gap is unquantified from the supplied material and is the first thing to check in the documentation site.
There is a second, harsher prerequisite. If you installed Claude Code through npm or brew, the README instructs you to uninstall it first and use the native installer instead. That is a migration cost paid before Pilot Shell does anything, and it will collide with existing tooling or CI images that assume the npm binary is present.
Subscription requirements are not incidental either. The README points solo users at Max 5x or 20x and teams at Team Premium, which means Pilot Shell is effectively gated behind a higher tier than a casual Claude Code user holds.
Where the design creates friction, and when to pick something else
Pilot Shell is opinionated about process. Hooks, stop guards and gates are described as enforcing quality on every layer, which by construction means the agent will be blocked or redirected at points where an unguarded session would simply continue. Teams that want the agent to move fast and accept occasional rework will find that friction is the feature, not a bug to configure away. The README does not describe an escape hatch for disabling individual gates, so I cannot say how granular that control is.
The install is also global rather than per project. It injects settings, hooks, MCP entries and shell aliases into your environment and integrates with any existing project. That is convenient, and it also means the harness is present in every repository you open, not only the ones you want governed.
A real alternative is to compose the same idea from the agents' own primitives. Claude Code supports rules, hooks, skills, subagents and MCP servers natively, and the README itself says Pilot Shell builds on those concepts. A team willing to maintain its own CLAUDE.md, hook scripts and MCP config gets a harness tuned to exactly one codebase, with no global install, no Console, and no shared memory across projects. The difference is maintenance ownership: Pilot Shell ships the coordination and updates it through pilot update, while the hand-rolled route leaves every gate, memory convention and review step for you to write and keep working as the agents change. The hand-rolled route also gives up the cross-agent standard, since keeping Claude Code and Codex aligned is work Pilot Shell claims to do for you.
Maintenance cost, release cadence and the licence question
The release history in the supplied material shows v11.0.0 on 2026-09-07, v11.0.1 the next day, and v11.0.2 on 2026-09-09. Three releases in three days at a major version boundary is a fast cadence, and the README's own downgrade section anticipates that you may hit an issue or unfixed bug in the latest version. Budget for the possibility that a pinned VERSION is the safer default on a team, and note that the downgrade path is the same install script with an environment variable, so reverting is cheap.
Upgrade cost beyond that is not documented in the material I have. There is no migration guide for the v10 to v11 step, no statement about whether persistent memory survives a version change, and no compatibility matrix for the external tools the README lists. Those are open questions, not settled ones.
The licence is the sharpest unresolved item. The repository metadata reports NOASSERTION, which means no standard licence identifier was detected, and the README does not state terms. NOASSERTION is not the same as permissive and not the same as proprietary; it means the terms have to be read from the licence file itself. I am not giving legal advice, and I have not read that file. For internal use this may be a formality. For redistribution, or for anything shipped to customers that embeds Pilot Shell, read the licence text at the repository root before you build a process around it.
Editorial conclusion
Adopt Pilot Shell if you already hold a Claude Max, Team or Enterprise subscription (or an OpenAI Plus, Pro, Business or Enterprise plan) and you want the same engineering standard applied across Claude Code and Codex. Skip it if you work outside those two agents, if you need a named OSI licence before you can ship, or if you are on the npm or brew build of Claude Code, since the prerequisites require uninstalling those first. Verify before you commit: run the installer on one repository, open the Console and confirm plan and diff review behave as you expect, then read the licence file at the repository root, because the metadata reports NOASSERTION and the README does not state terms.
Community notes