pilot-shell

Name: pilot-shell
Author: maxritter

Verified

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.

1,782stars

151forks

JavaScript

Installation

# Add to your Claude Code skills
git clone https://github.com/maxritter/pilot-shell

Getting Started

Guides for using ai agents skills like pilot-shell.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

Security ReportVerified

Last scanned: 4/26/2026

{
  "issues": [],
  "status": "PASSED",
  "scannedAt": "2026-04-26T06:11:22.696Z",
  "semgrepRan": false,
  "npmAuditRan": true,
  "pipAuditRan": true
}

README.md

Frequently Asked Questions

What is pilot-shell?

pilot-shell is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by maxritter. 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. It has 1,782 GitHub stars.

Is pilot-shell safe to use?

Yes. pilot-shell passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install pilot-shell?

Clone the repository with "git clone https://github.com/maxritter/pilot-shell" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is pilot-shell written in?

pilot-shell is primarily written in JavaScript. It is open-source under maxritter on GitHub, so you can review or fork the full source.

Are there alternatives to pilot-shell?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh pilot-shell against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

pg-aiguide grepai

How real engineers run Claude Code and Codex

From requirement to production-grade code — planned, tested, verified. Spec-driven plans. Enforced quality gates. Persistent knowledge.

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

macOS · Linux · Windows (WSL2) — installs in under 2 minutes.

Why Pilot Shell

Claude Code and Codex CLI write code fast — but without structure, they skip tests, lose context, and produce inconsistent results. Other frameworks add complexity (dozens of agents, thousands of lines of config) without meaningfully better output.

Pilot Shell is different. Every component solves a real problem with an engineered solution:

/prd — brainstorm ideas into clear requirements with optional deep research
/spec — plans, implements, and verifies features end-to-end with TDD
/fix — bugfix workflow with TDD; bails out when complexity exceeds the standard fix lane
Spec collaboration — share specs with teammates, annotations flow back grouped by author
Quality hooks — enforce linting, formatting, type checking, and tests as quality gates
Context engineering — preserves decisions and knowledge across sessions
Code intelligence — semantic search (Semble) + code knowledge graph (CodeGraph)
Token optimization — 60–90% cost reduction via RTK compression and Semble code search
Pilot Bot — persistent automation agent with scheduled tasks and background jobs
Extensions — reusable rules, skills, and MCP servers with team sharing and customization
Console — local web dashboard with real-time notifications and session management

Prerequisites

At least one AI agent: Pilot Shell supports Claude Code (primary — full feature coverage) and Codex CLI (all workflows, fewer platform features). Install at least one before running the Pilot installer:

Claude Code: Install via the native installer. If you have the npm or brew version, uninstall it first. Requires a Claude subscription — Max 5x or 20x for solo, Team Premium for teams, Enterprise for organizations.
Codex CLI: Install via the native installer. If you have the npm or brew version, uninstall it first. Requires an OpenAI subscription — Plus or Pro for solo, Business or Enterprise for teams.

Terminal (Recommended): cmux works great with Pilot Shell — its vertical tab layout lets you run multiple sessions side by side. 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, 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, just run claude or codex directly — Pilot Shell is loaded automatically. Run pilot update to check for updates.

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=9.10.2
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash

Removes the Pilot binary, plugin files, managed commands/rules, settings and shell aliases:

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

Over time, accumulated session logs and Pilot Shell's caches can slow things down. A periodic reset gives you a clean baseline:

# 1. If using Claude Code, log out first
/logout

# 2. Back up your current config (just in case)
mv ~/.claude.json ~/.claude.json.bak
mv ~/.claude       ~/.claude.bak
mv ~/.codex        ~/.codex.bak
mv ~/.pilot        ~/.pilot.bak

# 3. Reinstall Pilot Shell from the official installer
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash

# 4. Re-activate your license, then start your agent
pilot activate <your-license-key>
claude   # or: codex

Once Pilot Shell is running smoothly again, you can delete the .bak copies. Forgot your license key? Recover it in the Pilot members area.

Pilot Shell works inside Dev Containers. Copy the .devcontainer folder from this repository into your project, adapt it to your needs (base image, extensions, dependencies), and run the installer inside the container. The installer auto-detects the container environment and skips system-level dependencies like Homebrew.

For tighter isolation when working with untrusted code, combine the dev container with Claude Code's /sandbox — bubblewrap, socat, iptables, and ipset are pre-installed in the Dockerfile so it works out of the box on Linux. See Anthropic's development containers and sandboxing docs for hardening patterns (egress allowlist, managed settings, persistent volumes).

8-step installer with progress tracking, rollback on failure, and idempotent re-runs. Steps 3 and 4 are agent-conditional — they skip cleanly when the matching agent CLI is not detected. The installer does not install Claude Code or Codex CLI itself; install at least one yourself per the prerequisites above.

Prerequisites — Checks/installs Homebrew, Node.js, Python 3.12+, uv, git, jq. Verifies at least one supported agent (Claude Code or Codex CLI) is on the system; aborts with a clear error otherwise.
Pilot files — Agent-neutral Pilot Shell-managed assets. Hooks → ~/.pilot/hooks/, Console scripts/UI → ~/.pilot/, MCP server template → ~/.pilot/.mcp.json, raw rule sources → ~/.pilot/rules/ (read by Codex's adapter), plus the canonical skill source at ~/.claude/skills/ (Claude reads natively; Codex adapts in step 4). Always runs.
Claude files — Claude-specific assets under ~/.claude/: rules, sub-agents, settings.json (three-way merged), plus the Claude post-install merges (hooks into settings, ~/.claude.json MCP block, model config migration). Skipped when Claude Code CLI is not detected.
Codex files — Codex-specific assets: adapted skills → ~/.agents/skills/, review agents → ~/.codex/agents/, ~/.codex/AGENTS.md, ~/.codex/config.toml, ~/.codex/hooks.json. Per-category counts mirror the Claude section. Skipped when Codex CLI is not detected.
Config files — Creates .nvmrc and project config.
Dependencies — Installs Semble, RTK, CodeGraph, Chrome DevTools MCP, playwright-cli, agent-browser, language servers, and the codex@openai-codex Claude marketplace plugin (skipped on Codex-only systems alongside Chrome DevTools MCP and LSP plugins).
Shell integration — Auto-configures bash, fish, and zsh with the pilot admin alias.
Finalize — Success message with next steps.

First Steps

Run these commands once in each new project after installing Pilot Shell:

# Claude Code         # Codex CLI
claude                codex
> /setup-rules        > $setup-rules

/setup-rules reads your codebase, discovers your conventions, and generates project-specific rules and MCP server docs — this is how Pilot learns your project. Run it once to start, then again after major architectural changes.

Once your rules are in place, use /create-skill to capture any repeatable workflow as a reusable skill, and /benchmark to measure whether your rules and skills are actually improving outputs. See Additional Workflows for full details on all three.

Three commands cover the full development cycle — from vague idea to shipped feature. Quality hooks and TDD enforcement run automatically on every task.