Pilot Shell
A spec-driven, TDD-oriented workflow layer for Claude Code and Codex CLI.
Per-dimension scores and reasoning
Evidence shows the installer modifies user config directories (~/.claude, ~/.codex, ~/.pilot) and installs multiple third-party dependencies (Semble, RTK, CodeGraph, Chrome DevTools MCP, playwright-cli, agent-browser), but least privilege is not explicitly addressed. User confirmation is present: /spec and /build workflows have explicit approval gates (Plan Approval), while /fix has no approval but is designed for quick fixes. Data flow transparency is insufficient; no detailed explanation of how data is collected, stored, or shared. Sensitive data handling mentions license keys and config backups but not encryption. Dependency security lists dependencies in pyproject.toml but lacks vulnerability scanning or lock files. External effects include modifying shell configs and global configs, but an uninstall script is provided. Rollback is supported via installer rollback and downgrade/reset options. Source attribution is clear in the license (Max Ritter), but publisher is unverified.
Self-consistency: README workflows align with pyproject.toml test config, but some files are git-crypt encrypted and cannot be verified. Dependency availability: dependencies are listed but no lock files or mirrors. Failure messages: installer has error handling but no detailed logs.
Audience and scenarios: README targets developers using Claude Code and Codex CLI with multiple workflows. Capability boundaries: /fix is limited to single-file bugs, /spec and /build have clear scopes. Trigger precision: commands are clearly triggered but no detailed trigger condition docs. Environment fit: supports macOS, Linux, Windows (WSL2), and Dev Containers.
Information architecture: README is well-structured with TOC and links. Install notes are detailed with prerequisites and steps. Naming stability: command names are stable but no naming convention docs. Examples and FAQ: command examples provided but no FAQ. Known limitations: not explicitly listed. License: custom license, not standard open-source. Versioning and changelog: version in pyproject.toml but no CHANGELOG file. Maintenance responsibility: copyright to Max Ritter but no explicit maintainer.
Output usability: workflows generate PRDs, specs, buildouts with clear formats. Marginal value: unique features like TDD enforcement and quality gates. Cost-benefit: claims 60-90% cost reduction but no concrete data.
Claim traceability: feature descriptions in README lack implementation details. Cross-source corroboration: no third-party verification. Fact-inference separation: performance claims not distinguished from facts.
- The installer modifies user config directories and installs multiple third-party dependencies; test in an isolated environment.
- Some source files are git-crypt encrypted, preventing full security audit.
- The license is custom, not standard open-source; read terms carefully.
- Publisher identity is unverified; proceed with caution.
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 | bashThe 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.