pilot-shell

Name: pilot-shell
Author: maxritter

Verified

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,085stars

178forks

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
}

Compare with similar skills

See how pilot-shell compares with popular alternatives.

pilot-shell vs ecc

See comparison

pilot-shell vs hermes agent

See comparison

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. 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. It has 2,085 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

ECC

by affaan-m

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

275,610

unreal-mcp memmy-agent

⚠️ Third-Party Software Notice

This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.

Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.

Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.

Read the Terms of Service

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.

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.

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:

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: Install Codex CLI or the ChatGPT desktop app. Pilot detects the CLI and the Codex binary bundled with ChatGPT on macOS. Requires an OpenAI subscription — Plus or Pro for solo, Business or Enterprise for teams.

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.

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

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 originally Pilot-installed
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash -s -- --remove-tools

# Also delete Pilot memories, sessions, logs, configuration, and unknown files
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash -s -- --purge-data

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)
# Using CLAUDE_CONFIG_DIR? Substitute it for ~/.claude, and back up
# "$CLAUDE_CONFIG_DIR/.claude.json" instead of ~/.claude.json.
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 is not detected. The installer does not install Claude Code, Codex CLI, or ChatGPT 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, Codex CLI, or the Codex binary bundled with ChatGPT on macOS) is on the system; aborts with a clear error otherwise.
**Pi