maxritter/pilot-shell

How real engineers run Claude Code and Codex: spec-driven planning, enforced TDD, persistent memory, and quality enforcement on all levels. Make your agents production-ready.

Pilot Shell – AI‑augmented command‑line for Claude Code & Codex

What it is – A thin shell/CLI that sits on top of Anthropic’s Claude Code (primary) or OpenAI’s Codex and adds a structured, test‑driven development workflow. It turns raw code‑generation prompts into repeatable, quality‑checked pipelines that cover requirement gathering, specification, implementation, bug‑fixing and autonomous building.

Why it exists – Claude Code and Codex can write code quickly, but without a framework they:

  • skip tests and linting,
  • lose context between sessions,
  • produce inconsistent results. Pilot Shell injects spec‑driven and goal‑driven processes, quality gates, and persistent “memory” so the AI behaves more like a disciplined engineering teammate.

Core concepts & commands

Command When to use What it does
/prd You have a vague idea or problem statement. Brainstorms, does optional web research, and produces a Product Requirements Document saved under docs/prd/.
/spec You have a clear feature or bug to work on. Guides the AI through Plan → Approve → Implement (TDD) → Verify → Done, with automatic lint/format/type checks and optional collaborative spec review.
/build You want to reach a concrete goal without a full spec. Generates a short task list + acceptance criteria, then iteratively builds, judges, and refines until the criteria pass.
/fix You need a bug‑fix that fits a test‑driven flow. Runs a focused TDD loop; aborts if the fix becomes too complex.
pilot (admin alias) Managing the installation, updates, and configuration. Installs/uninstalls the runtime, activates licenses, switches models, etc.

Highlighted features

  • Quality hooks – linting, formatting, type‑checking and test execution are enforced automatically for every edit.
  • Context engineering & memory sharing – decisions, rules, and “memories” are persisted in ~/.pilot/ and can be shared via the project repo.
  • Semantic search (Semble) + code‑knowledge graph (CodeGraph) – fast, accurate code‑base look‑ups that reduce token usage.
  • Token optimization – 60‑90 % cost reduction through RTK compression and the Semble search.
  • Pilot Bot – a persistent background agent that can run scheduled tasks or long‑running jobs.
  • Extensions – reusable rules, skills, and MCP (Message‑Control‑Protocol) servers that teams can share.
  • Console – a local web dashboard showing real‑time notifications, session logs and the current requirements/specs.

Installation (quick‑start)

# one‑liner works on macOS, Linux and Windows (WSL2)
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash

The installer:

  1. Checks for Homebrew, Node, Python 3.12+, git, jq.
  2. Detects a supported AI agent (Claude Code or Codex) – you must install one beforehand.
  3. Deploys Pilot assets under ~/.pilot/ and agent‑specific adapters.
  4. Installs supporting tools (Semble, RTK, CodeGraph, Playwright, Chrome‑DevTools MCP, language servers, etc.).
  5. Adds shell aliases (pilot, claude/codex wrappers) for bash, fish and zsh.

To uninstall while keeping your data:

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

Add --purge-data to delete ~/.pilot/.

Prerequisites

  • Claude Code – native installer (requires an Anthropic subscription) or
  • Codex CLI / ChatGPT desktop (requires an OpenAI subscription).
  • A modern terminal (Zentty recommended, but iTerm2, Ghostty, etc. work).

Typical workflow example

# start Claude Code (or Codex)
claude                     # or: codex

# 1️⃣ Create a PRD
> /prd "Add real‑time notifications for team updates"

# 2️⃣ Turn it into a spec and implement
> /spec "Add real‑time notifications for team updates"
# – Pilot walks you through planning, writes E2E tests, implements with TDD, verifies and merges.

# 3️⃣ If you later need a quick fix
> /fix "Notifications stop after page reload"

All steps are logged, and the generated specs, rules and memories live in the repo for future reuse.

Who might benefit?

  • Software engineers who already use Claude Code or Codex and want a disciplined, repeatable workflow.
  • Teams that need shared specifications, quality gates and a way to persist AI‑generated knowledge across members.
  • Solo developers looking to reduce token costs while keeping AI assistance safe and test‑driven.

Links

Related

  • Project
    sangrokjung/claude-forge

    A professional equipment pack for Claude Code that adds specialist agents, safety hooks, and automated workflows to transform the terminal AI into a full-scale development kit.

  • Project
    wesammustafa/Claude-Code-Everything-You-Need-to-Know

    A thorough, example‑rich tutorial for Anthropic’s Claude Code CLI, covering installation, prompt engineering, and advanced extensions (Skills, Hooks, Sub‑agents, Workflows, MCP) to let developers use Claude for repo‑wide code analysis, editing, testing and automation.

  • Project
    fengshao1227/ccg-workflow

    A workflow engine for Claude Code that turns it into a multi-model orchestrator, delegating specialized work to other LLMs for complex software development.

  • Dispatch
    Mastering Claude Code: From Prompting to Programmable Engineering

    A deep dive into transforming Claude Code from a simple chatbot into a sophisticated autonomous agent using custom skills, subagents, and the Model Context Protocol.

  • Project
    Prorise-cool/Claude-Code-Multi-Agent

    Claude Code Multi‑Agent is an open‑source framework that gives Anthropic’s Claude Code project awareness and expert‑agent capabilities. It uses a Python Hook system and a locally‑run Ollama model to automatically detect the codebase type, analyse user intent, load 300+ domain‑specific “Skills” (backend, frontend, testing, security, etc.), and enforce automatic documentation (DEVELOPMENT.md, KNOWLEDGE.md, CHANGELOG.md). After cloning, installing Ollama, a model, and uv, you drop your project into the repo and Claude Code instantly knows its context, suggests appropriate tools, and can be driven with slash commands like `/backend‑specialist` or workflow commands such as `/kiro/spec`. Key points: - Zero‑config start; all configuration lives in `.claude/settings.json` and `prompts.json`. - Hooks run on session start, user prompt, tool use, etc., handling project detection, intent analysis, and doc updates. - Skills are defined by `SKILL.md` files and are auto‑discovered. - Works entirely locally (no external API), integrates with Git, and is MIT‑licensed. Ideal for developers or small teams who want a reproducible, on‑premise AI coding assistant.