Pilot Shell
A spec-driven, TDD-oriented workflow layer for Claude Code and Codex CLI.
What does this agent do, and when should you use it?
Pilot Shell is a local development workflow layer for Claude Code and Codex CLI, structured around moving work from requirements to verified code. Its /prd, /spec, and /fix commands cover product requirements, feature or architectural work, and narrowly scoped bug fixes, with test-driven development and quality checks built into the flows. The installer deploys rules, skills, review agents, hooks, MCP configuration, and Console files; Claude Code is the primary integration with full coverage, while Codex CLI supports all workflows with fewer platform features. A local Console at localhost:41777 surfaces specifications, requirements, sessions, memories, extensions, changes, and usage. It is not a standalone model or hosted coding service: it operates through an already installed Claude Code or Codex CLI client and its project tooling.
After /setup-rules, it reads a codebase’s existing rules, CLAUDE.md, AGENTS.md, and code patterns to generate modular project rules and optionally document working MCP servers. /prd turns an early idea into a document under docs/prd/ through discussion, clarification, and optional research; /spec explores the codebase, asks questions, writes a specification, waits for approval, then implements in an isolated git worktree using RED→GREEN→REFACTOR while running quality hooks, tests, review, and browser-driven UI verification. /fix reproduces a defect, uses codegraph_context and semble search to trace the root cause, requires a failing test before a minimal fix, then runs end-to-end, lint, type, build, and regression checks. The installer also brings in tools including Semble, RTK, CodeGraph, Chrome DevTools MCP, playwright-cli, and agent-browser, while the Console displays workflow artifacts and notifications.
- A solo developer using Claude Code wants to turn an OAuth/JWT authentication request into an approved specification before implementing and validating it in an isolated worktree.
- A Codex CLI user joining an existing repository needs to run $setup-rules so the workflow can derive and maintain project conventions from the codebase.
- A maintainer has a localized defect with an identifiable root cause and wants /fix to establish a failing test before making the smallest root-cause change and executing the actual program.
- A product and engineering team needs colleagues to annotate a PRD or specification before approval through the local Console.
- A team wants evidence that a rule or skill improves outputs, so it runs /benchmark with and without the target in isolated sandboxes and reviews assertion deltas.
What are this agent's strengths and limitations?
- Provides distinct /prd, /spec, and /fix workflows for requirements, planning, approval, TDD implementation, verification, and review rather than only generic prompting.
- /spec uses an isolated git worktree and incorporates quality hooks, full-suite testing, changes review, and browser-executable UI scenarios into its documented flow.
- /setup-rules derives modular rules from the repository, existing rule files, and context files, with an optional AGENTS.md sync.
- The local Console at localhost:41777 brings specifications, requirements, memories, sessions, extensions, and Git changes together and supports annotations on requirements and plans.
- It requires an installed and subscribed Claude Code or Codex CLI client; the installer explicitly does not install either client.
- Codex CLI supports the workflows, but the documentation explicitly says it has fewer platform features than Claude Code.
- Installation writes to user-level locations including ~/.pilot and, depending on the client, Claude, Codex, and ~/.agents configuration paths, and installs multiple tools; teams should assess local-configuration impact first.
- Several capabilities depend on network access, MCP, browser automation, Semble, RTK, and CodeGraph; the supplied material does not document an offline or minimal-dependency mode.
- The repository metadata gives the license as NOASSERTION, and the supplied material does not establish the license terms beyond pointing to a LICENSE file.
How do you install or deploy this agent?
Install at least one supported client yourself first—Claude Code or Codex CLI—and hold the applicable subscription. Claude Code is the primary integration; Codex CLI supports every workflow with fewer platform features. The installer supports macOS, Linux, and Windows WSL2. Then run:
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
The installer checks or installs Homebrew, Node.js, Python 3.12+, uv, git, and jq, and writes matching client configuration when that client is detected. Start it afterward with claude or codex.
How do you use this agent?
Open the target project with claude or codex, then initialize project rules once: use /setup-rules in Claude Code or $setup-rules in Codex CLI. For an undeveloped product idea, run /prd "..." (or $prd "..." in Codex); for a feature, refactor, or architectural task, use /spec "..." (or $spec "..."); for a local bug, use /fix "..." (or $fix "..."). /spec pauses after planning for approval before implementation and verification. If /fix finds a multi-component or architectural issue, it directs the user to rerun the work through /spec.
How does this agent compare with similar options?
Pilot Shell documents Claude Code as its primary integration with full feature coverage, while Codex CLI can run all workflows with fewer platform features. It is positioned as a workflow and quality layer built on those CLIs’ existing rules, hooks, skills, subagents, and MCP concepts, rather than as a replacement for either CLI.