Airsc is free for everyone. If it helps you, support it with $2–$20.

Support
VISign in
SkillCautionAgent workflow & memorySome setup

pilot-shell

maxritter · maxritter/pilot-shell

A harness around Claude Code and Codex adding spec-driven development, TDD, persistent memory, quality gates, hooks and end-to-end verification.

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.

2.1k stars178License: No licenseUpdated 12 days ago0 opens

Preview

▍

What you can do with it

  • Run spec-driven features with enforced tests before handoff
  • Keep project context and decisions across long sessions
  • Verify finished work in a browser with quality gates

Safety check

Caution

Usable, but read the notes first.

  • ●Installer downloads a remote script and pipes it to the shell.install.sh
  • ●Asks for administrator (sudo) rights.install.sh
  • ●No clear license: check with the author before using it in a commercial product.

Automated scan of the repo files. Always review code you run.

From the README

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:

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
View source on GitHub