Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/maxritter/pilot-shell

The professional development environment for Claude Code: From requirement to production-grade code. Planned, tested, verified.
https://github.com/maxritter/pilot-shell

ai-agents ai-assistant ai-coding ai-coding-tools ai-engineering ai-tools anthropic anthropic-claude claude claude-ai claude-code claude-context claude-mem claude-skills claudecode model-context-protocol spec-driven-development

Last synced: 3 days ago
JSON representation

The professional development environment for Claude Code: From requirement to production-grade code. Planned, tested, verified.

Awesome Lists containing this project

README 

          



Pilot Shell



**The professional development environment for [Claude Code](https://docs.anthropic.com/en/docs/claude-code)**



### Claude Code is powerful. Pilot Shell makes it reliable.



From requirement to production-grade code. Planned, tested, verified.

**Tests enforced. Context optimized. Quality automated.**



[![Stars](https://img.shields.io/github/stars/maxritter/pilot-shell?style=flat&color=F59E0B)](https://github.com/maxritter/pilot-shell/stargazers)

[![Star History](https://img.shields.io/badge/Star_History-chart-8B5CF6)](https://star-history.com/#maxritter/pilot-shell&Date)

[![Downloads](https://img.shields.io/github/downloads/maxritter/pilot-shell/total?color=3B82F6)](https://github.com/maxritter/pilot-shell/releases)

[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-10B981.svg)](https://github.com/maxritter/pilot-shell/pulls)



⭐ [Star this repo](https://github.com/maxritter/pilot-shell) · 🌐 [Website](https://pilot-shell.com) · 📖 [Documentation](https://pilot-shell.com/docs) · 🆕 [Updates](https://www.linkedin.com/in/rittermax/) · 📋 [Changelog](https://pilot.openchangelog.com/)







```bash

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

```



**Works on macOS, Linux, and Windows (WSL2).**







Pilot Shell Demo






---



## Why I Built This



**Claude Code writes code fast**. But without structure, it skips tests, loses context, and produces inconsistent results — especially on complex, established codebases where there are real conventions to follow and real regressions to catch. I tried other frameworks. Most of them add complexity — dozens of agents, elaborate scaffolding, thousands of lines of instruction files — but the output doesn't get a lot better. You just burn more tokens, wait longer and have to deal with a more complex setup.



**So I built Pilot Shell**. Spec-driven development plans, implements, and verifies features end-to-end. Context engineering preserves decisions and knowledge across sessions. Quality hooks enforce linting, formatting, type checking, and TDD on every edit — not as suggestions, but as gates. Semantic search and a code knowledge graph give Claude deep codebase understanding. Token optimization cuts costs by 60–90%. A modular extension system with team sharing makes everything reusable. MCP servers and language servers provide real-time diagnostics and library docs. Every component exists because I hit a real problem — and solved it structurally.



**This isn't a vibe coding tool**, it's agentic engineering that produces production-grade results. You install it once, run `pilot` in any project, then `/setup-rules` to generate your project rules. Use `/prd` to brainstorm and turn vague ideas into clear requirements, then `/spec` to plan, implement, and verify — when it's done, the work is tested and ready to ship. As patterns emerge, `/create-skill` captures your workflows so they're reusable across projects.



---



## Getting Started



### Prerequisites



**Claude Code:** Install [Claude Code](https://code.claude.com/docs/en/quickstart) using the **native installer** before setting up Pilot Shell. If you have the `npm` or `brew` version installed, uninstall it first. If no Claude Code installation is detected, the Pilot installer will attempt to set it up for you.



**Claude Subscription:** Solo developers should choose [Max 5x](https://claude.com/pricing) for moderate usage or [Max 20x](https://claude.com/pricing) for heavy usage. Teams should use [Team Premium](https://claude.com/pricing) (6.25x usage per member, SSO, admin tools, billing management). Companies with stricter compliance or procurement requirements should use [Enterprise](https://claude.com/pricing) (API based pricing applies per usage).



**Chrome Extension (Recommended):** Install the [Claude Code Chrome extension](https://code.claude.com/docs/en/chrome) for browser automation and E2E testing. Pilot automatically detects it and uses it as the preferred tool. When Chrome isn't available, Pilot falls back to [playwright-cli](https://github.com/microsoft/playwright-cli) (reliable element targeting, persistent sessions, tracing) or [agent-browser](https://agent-browser.dev/) (lightweight, fast startup).



**Codex Plugin (Optional):** Install the [Codex plugin](https://github.com/openai/codex-plugin-cc) for adversarial code review powered by OpenAI Codex. When enabled in Console Settings, Codex provides an independent second opinion during `/spec` planning and verification phases. A [ChatGPT Plus](https://chatgpt.com/#pricing) subscription ($20/mo) covers the Codex API usage needed for code reviews.



### Installation



**Works with any existing project.** Pilot Shell is installed on top of Claude Code and uses its built-in concepts like commands, rules, hooks, skills, subagents, MCP, LSP and optimized settings to improve your experience:



```bash

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

```



Installs globally on macOS, Linux, and Windows (WSL2). All tools and rules go to `~/.pilot/` and `~/.claude/`. After installation, `cd` into any project and run `pilot` or `ccp` to start.



What the installer does



7-step installer with progress tracking, rollback on failure, and idempotent re-runs:



1. **Prerequisites** — Checks/installs Homebrew, Node.js, Python 3.12+, uv, git, jq

2. **Claude files** — Sets up `~/.claude/` plugin — rules, commands, hooks, MCP servers

3. **Config files** — Creates `.nvmrc` and project config

4. **Dependencies** — Installs Probe, RTK, CodeGraph, [playwright-cli](https://github.com/microsoft/playwright-cli), [agent-browser](https://agent-browser.dev/), language servers

5. **Shell integration** — Auto-configures bash, fish, and zsh with `pilot` alias

6. **VS Code extensions** — Installs recommended extensions for your stack

7. **Finalize** — Success message with next steps



### Installing a Specific Version



Pin to a specific release (see [releases](https://github.com/maxritter/pilot-shell/releases)):



```bash

export VERSION=7.11.2

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

```



### Uninstalling



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



```bash

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

```



Dev Container



Pilot Shell works inside Dev Containers. Copy the [`.devcontainer`](https://github.com/maxritter/pilot-shell/tree/main/.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.



---



## How It Works



### Pilot Shell Console



A local web dashboard with different views and real-time notifications when Claude needs your input:



Pilot Shell Console — Dashboard



All views



| View              | What it shows                                                                                                                                |

| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |

| **Dashboard**     | Workspace status, active sessions, spec progress, git info, recent activity                                                                  |

| **Specification** | All spec plans with task progress, phase tracking, and iteration history. **Annotate mode** lets you mark up plans visually before approving — select text or click **+** on any block to write a note. **Share with Teammate** generates a compressed share link; **Receive Feedback** imports their annotations with accept/reject controls |

| **Extensions**    | All extensions — local, plugin, and remote — with team sharing via git, diff view, push/pull, and color-coded categories                     |

| **Changes**       | Git diff viewer with staged/unstaged files, branch info, and worktree context. **Review mode** adds inline annotations on diff lines — the agent reads them directly before marking a spec as verified |

| **Memories**      | Browsable observations — decisions, discoveries, bugfixes — with type filters and search                                                     |

| **Sessions**      | Active and past sessions with observation counts and duration                                                                                |

| **Usage**         | Daily token costs, model routing breakdown, and usage trends                                                                                 |

| **Settings**      | Model selection per command/sub-agent, spec workflow toggles (worktree, questions, approval), reviewer toggles (spec review, changes review, optional Codex), extended context (1M) toggle |

| **Help**          | Documentation, guides, and quick-start resources                                                                                             |



Visual plan annotation



When a spec plan is pending approval, the Specifications tab defaults to **Annotate mode**. Two ways to annotate:



- **Select text** — highlight any passage and write a note via the floating toolbar

- **Click +** — hover over any block to add a note without selecting text



Annotations save automatically. The agent reads them at the next checkpoint, revises the plan accordingly, and asks for approval again. This turns plan review into a conversation — you mark what needs changing, the agent addresses it, you review again.



Spec sharing



Share specs and requirements with teammates for async review — no cloud service required:



1. **Share** — Click **Share with Teammate** to generate a compressed link. The entire spec and annotations are encoded into the URL fragment, so no data is transmitted to any server.

2. **Review** — Your colleague opens the link in their Console (or on pilot-shell.com), sees your annotations, and adds their own feedback.

3. **Import** — Click **Receive Feedback** to import their annotations. Each annotation has per-item **accept/reject** controls — accepted annotations merge into your plan, rejected ones are removed from both the sidebar and inline markers.



Everything works locally. The link is self-contained — the recipient doesn't need access to your machine, repository, or any shared service.



Code review



After a spec completes all automated checks, the agent prompts you to review the changes in the **Changes** tab:



1. **Enable Review mode** — toggle it in the Changes tab header

2. **Annotate diffs** — click **+** on any diff line to add an inline note. Annotations save automatically.

3. **Agent addresses feedback** — the agent reads every annotation and resolves them before marking the spec as verified



This gives you a final quality gate with direct, line-level feedback — the same workflow as a PR review, but before the code ever leaves your machine.



### Status Line



A three-line dashboard rendered below every Claude Code response. Replaces the default status line with real-time session metrics, spec progress, and version info — all color-coded.



```

Opus 4.6 [1M] | █████░▓ 60% [604K] | +156 -23 | main +2 ~3 | $1.45 | Savings: 65%

Spec: my-feature feature [implement] ████░░░░ 3/6

Pilot 8.2.1 (Solo) · CC 2.1.79 (Max) · sessions 2 · memories 12

```



All fields explained



**Line 1 — Session Metrics** (separated by `|`):



| Widget            | Description                                                                     |

| ----------------- | ------------------------------------------------------------------------------- |

| **Model**         | Active model in short form (`Opus 4.6 [1M]`, `Sonnet 4.6`)                      |

| **Context**       | Effective context usage with progress bar, buffer indicator, and token count. Green < 80%, Yellow 80–95%, Red 95%+ |

| **Lines changed** | `+added -removed` in session (hidden when usage API data available)             |

| **Git**           | Branch with staged (`+N`) / unstaged (`~N`) counts                              |

| **Cost**          | Session cost in USD. Green < $1, Yellow $1–5, Red $5+                           |           |

| **RTK savings**   | Token savings percentage from RTK proxy (`Savings: N%`), shown when no usage data |



**Line 2 — Mode:**



- **Quick Mode:** `Quick Mode`

- **Spec Mode:** Plan name, type (`feature`/`bugfix`), phase (`plan`/`implement`/`verify`), progress bar, task count, and iteration count



**Line 3 — Version & Session Info:**



`Pilot  () · CC  () · sessions  · memories `



Pilot tier: Solo, Team, or Trial with time remaining. Claude subscription (Pro/Max/Team/Enterprise) detected via `claude auth status` and cached for 24 hours.



### /prd — Generate Product Requirements Documents



**Use `/prd` before `/spec` when requirements are unclear.** It's a strategic thought partner that turns vague ideas into concrete Product Requirements Documents (PRDs) through one-on-one conversation — with optional research, challenging assumptions, exploring trade-offs, and defining scope before you commit to building.



```bash

pilot

> /prd "Add real-time notifications for team updates"

> /prd "We need better onboarding — users drop off after signup"

```



Choose a research tier at the start: **Quick** (skip), **Standard** (web search for competitors, prior art, best practices), or **Deep** (parallel research agents for comprehensive findings). The conversation produces a PRD with problem statement, core user flows, scope boundaries, and technical context — then offers to hand off directly to `/spec` for implementation. PRDs are saved to `docs/prd/` and visible in the Console's **Requirements** tab.



### /spec — Spec-Driven Development



**`/spec` replaces Claude Code's built-in plan mode** (Shift+Tab). It provides a complete planning workflow with TDD, verification, and code review — use `/spec` instead of plan mode for all planned work.



Features, bug fixes, refactoring — describe it and `/spec` handles the rest. Auto-detects whether it's a feature or a bugfix and adapts the workflow. Specs are saved to `docs/plans/` and visible in the Console's **Specification** tab.



```bash

pilot

> /spec "Add user authentication with OAuth and JWT tokens"   # → feature mode

> /spec "Fix the crash when deleting nodes with two children"  # → bugfix mode (auto-detected)

```



```

Discuss  →  Plan  →  Approve  →  Implement (TDD)  →  Verify  →  Done

                                                        ↑         ↓

                                                        └── Loop──┘

```



Pilot Shell Console — Specifications



Feature Mode



Full exploration workflow for new functionality, refactoring, or architectural changes.



**Plan:** Explores codebase with semantic search → asks clarifying questions → writes detailed spec with scope, tasks, and definition of done → for UI features, writes **E2E test scenarios** (step-by-step, browser-executable) that become the verification contract → **spec-review sub-agent** validates completeness → waits for your approval. Optional **Codex adversarial review** provides an independent second opinion when enabled.



**Implement:** Creates an isolated git worktree → implements each task with strict TDD (RED → GREEN → REFACTOR) → quality hooks auto-lint, format, and type-check every edit → full test suite after each task.



**Verify:** Full test suite + actual program execution → **unified review sub-agent** (compliance + quality + goal) → for UI features, executes each E2E scenario step-by-step via browser automation (pass/fail tracked, results written to plan) → auto-fixes findings → squash merges to main on success.



Bugfix Mode



Investigation-first workflow for targeted fixes. Finds the root cause before touching any code.



**Investigate:** Reproduces the bug → traces backward through the call chain to find the **root cause** at a specific `file:line` → compares against working code patterns → states the fix with confidence level. If 3+ hypotheses fail, escalates as an architectural problem.



**Test-Before-Fix:** Writes a regression test that FAILS on current code → implements the minimal fix at the root cause → verifies all tests pass. Defense-in-depth validation at multiple layers when the bug involves data flowing through shared code paths.



**Verify:** Lightweight verification — regression test confirmation → full test suite → lint + type check → quality checks. No review sub-agents — the regression test proves the fix works, the full suite proves nothing else broke.



**Why this matters:** Root cause investigation prevents "fix one thing, break another." The regression test locks in the fix. No formal notation overhead — just trace, test, fix, verify.



### Quick Mode



Just chat — no plan, no approval gate. Quality hooks and TDD enforcement still apply. Best for small tasks and exploration. For anything that needs a plan, use `/spec` — not Claude Code's built-in plan mode.



### Claude CLI Flag Passthrough



All Claude Code CLI flags work directly with `pilot` — current and future. Pilot forwards any flag it doesn't recognize to the Claude CLI automatically.



```bash

pilot --channels plugin:telegram@claude-plugins-official

pilot --model opus --verbose

pilot --resume

```



### Headless Mode



Run Pilot non-interactively with `-p` for CI/CD pipelines, scripts, and automated workflows. All Claude Code CLI flags work — `--output-format`, `--allowedTools`, `--channels`, `--continue`, `--bare`, etc.



```bash

pilot -p "Run tests and fix failures" --allowedTools "Bash,Read,Edit"

pilot -p "Summarize this project" --output-format json

pilot --channels plugin:telegram@official -p "Check messages"

```



### /setup-rules — Generate Modular Rules



Explores your codebase, discovers conventions, generates modular rules and documents MCP servers. Run once initially, then anytime your project changes significantly.



```bash

pilot

> /setup-rules

```



What /setup-rules Does



11 phases that read your codebase and produce comprehensive AI context:



0. **Reference** — load best practices for rule structure, path-scoping, and quality standards

1. **Read existing rules** — inventory all `.claude/rules/` files, detect structure and path-scoping

2. **Migrate unscoped assets** — prefix with project slug for better sharing

3. **Quality audit** — check rules against best practices (size, specificity, stale references, conflicts)

4. **Explore codebase** — semantic search with Probe CLI, structural analysis with CodeGraph

5. **Compare patterns** — discovered vs documented conventions

6. **Sync project rule** — update `{slug}-project.md` with current tech stack, structure, commands

7. **Sync MCP docs** — smoke-test user MCP servers, document working tools

8. **Discover new rules** — find undocumented patterns worth capturing

9. **Cross-check** — validate all references, ensure consistency across generated files

10. **Summary** — report all changes made



**For monorepos:** Organizes rules in nested subdirectories by product and team, with `paths` frontmatter to scope rules to specific file types. Generates a `README.md` documenting the structure.



### /create-skill — Reusable Skill Creator



Builds a reusable skill from any topic — explores the codebase and creates it interactively with you. If no topic is given, evaluates the current session for extractable knowledge.



```bash

pilot

> /create-skill "Automate the review and triaging of our PR Bot comments"

```



What /create-skill Does



6 phases that turn domain knowledge into a reusable skill:



1. **Reference** — load use case categories, complexity spectrum, file structure template, description formula, security restrictions

2. **Understand** — explore the codebase for relevant patterns, ask clarifying questions, or evaluate the current session for extractable knowledge

3. **Check existing** — search project and global skills to avoid duplicates

4. **Create** — write to `.claude/skills/` (project) or `~/.claude/skills/` (global), apply portability and determinism checklists

5. **Quality gates** — structure checklist (SKILL.md naming, frontmatter fields), content checklist (error handling, examples, exclusions), triggering test (should/shouldn't trigger), iteration signals

6. **Test & iterate** — run test prompts with sub-agents, evaluate results, optimize description triggering



**Use case categories:**



| Category                      | Best For                                                                   |

| ----------------------------- | -------------------------------------------------------------------------- |

| **Document & Asset Creation** | Consistent reports, designs, code with embedded style guides and templates |

| **Workflow Automation**       | Multi-step processes with validation gates and iterative refinement        |

| **MCP Enhancement**           | Workflow guidance on top of MCP tool access, multi-MCP coordination        |



**Skill structure:** Each skill is a folder with a `SKILL.md` file (case-sensitive), optional `scripts/`, `references/`, and `assets/` directories. The YAML frontmatter description determines when Claude loads the skill — it must include what the skill does, when to use it, and specific trigger phrases. Progressive disclosure keeps context lean: frontmatter loads always (~100 tokens), SKILL.md loads on activation, linked files load on demand.



### Extensions



Rules, commands, skills, and agents — all plain markdown files in `.claude/` (project) or `~/.claude/` (global). The Console Extensions page lets you browse, edit, compare, and share everything from one place. Team sharing supports [APM](https://github.com/microsoft/apm) format for cross-tool compatibility.



Pilot Shell Console — Extensions



Extension categories



| Extension    | Location            | When it loads                               |

| ------------ | ------------------- | ------------------------------------------- |

| **Skills**   | `.claude/skills/`   | Automatically when relevant                 |

| **Rules**    | `.claude/rules/`    | Every session, or by file type              |

| **Commands** | `.claude/commands/` | On demand via `/command-name`               |

| **Agents**   | `.claude/agents/`   | Spawned as sub-agents for specialized tasks |



Use `/setup-rules` to auto-generate rules from your codebase. Use `/create-skill` to capture workflows as reusable skills.



Scopes: Global, Project, Plugin



**Project** extensions live in `.claude/` — commit them so teammates get them on `git clone`. **Global** extensions live in `~/.claude/` — personal and available across all projects. Move extensions between scopes with one click.



**Plugin** extensions come from installed Claude Code plugins (`claude plugin install `). They appear as read-only items — visible but not editable.



Team sharing & APM (Team tier)



Connect a git repository to share extensions across your team:



- **Push** local extensions to the team remote

- **Pull** remote extensions to your machine (global or project scope)

- **Compare** local vs remote with a built-in side-by-side diff view

- **Conflict detection** — when local and remote differ, choose which version to keep



**APM format** — check one box and your remote becomes an [APM package](https://microsoft.github.io/apm/introduction/key-concepts/), directly installable via `apm install owner/repo` by anyone using Copilot, Cursor, OpenCode, or Claude. Extensions are automatically converted to APM conventions on push:



| Pilot Shell | APM Remote |

| --- | --- |

| `rules/my-rule.md` | `instructions/my-rule.instructions.md` |

| `commands/my-cmd.md` | `prompts/my-cmd.prompt.md` |

| `skills/my-skill/SKILL.md` | `skills/my-skill/SKILL.md` |

| `agents/my-agent.md` | `agents/my-agent.agent.md` |



APM-compatible frontmatter is injected automatically. An `apm.yml` manifest is generated. Toggling APM on/off migrates existing extensions in a single commit.



---



## Demo



A full-stack project — created from **scratch with a single prompt**, then extended with **3 features built in parallel** using `/spec` and Git worktrees. Every line of code tested and verified by Pilot, zero manual code edits. **[Check out the Demo Project here →](https://github.com/maxritter/pilot-shell-demo)**



---



## Under the Hood



For full details on every component, see the **[Documentation](https://pilot-shell.com/docs/)**.



| Component | What it does |

| --- | --- |

| [**Hooks Pipeline**](https://pilot-shell.com/docs/features/hooks) | 15 hooks across 7 events — quality checks on every file edit (ruff, ESLint, go vet), TDD enforcement, token optimization via RTK (60–90% savings), memory capture, and session lifecycle management |

| [**Context Optimization**](https://pilot-shell.com/docs/features/context-optimization) | Lean context strategies — conditional rule loading, progressive skill disclosure, lazy MCP tool loading, RTK output compression. Compaction resilience for 200K windows |

| [**Smart Model Routing**](https://pilot-shell.com/docs/features/model-routing) | Opus for planning, Sonnet for implementation and verification. Configurable per-phase via Console Settings. 1M context available — included with API plans (Team, Enterprise); Max plan requires all models set to Opus |

| [**Rules & Standards**](https://pilot-shell.com/docs/features/rules) | 9 built-in rules (workflow, testing, verification, debugging, tools) + 5 coding standards activated by file type (Python, TypeScript, Go, Frontend, Backend) |

| [**MCP Servers**](https://pilot-shell.com/docs/features/mcp-servers) | 6 servers: library docs, persistent memory, web search, GitHub code search, web page fetching, code knowledge graph |

| [**Language Servers**](https://pilot-shell.com/docs/features/language-servers) | Real-time diagnostics for Python (basedpyright), TypeScript (vtsls), Go (gopls). Auto-installed, auto-configured |

| [**Pilot CLI**](https://pilot-shell.com/docs/features/cli) | Session management, headless mode (`-p`) for CI/CD and scripts, worktree isolation, licensing, context monitoring. Run `pilot` or `ccp` to start |



---



## What Users Say



> "I stopped reviewing every line Claude writes. The hooks catch formatting and type errors automatically, TDD catches logic errors, and the spec verifier catches everything else. I review the plan, approve it, and the output is production-grade."



> "Other frameworks I tried added so much overhead that half my tokens went to the system itself. Pilot Shell is lean — quick mode has zero scaffolding, and even /spec only adds structure where it matters. More of my context goes to actual work."



> "The persistent memory changed everything. I can pick up a project after a week and Claude already knows my architecture decisions, the bugs we fixed, and why we chose certain patterns. No more re-explaining the same context every session."



---



## License



Pilot Shell is source-available under a commercial license. See the [LICENSE](LICENSE) file for full terms.



| Tier           | Seats | Includes                                                                                                        |

| :------------- | :---- | :-------------------------------------------------------------------------------------------------------------- |

| **Solo**       | 1     | All features, continuous updates, community support via [GitHub Issues][gh-issues]                              |

| **Team**       | Multi | Solo + extension sharing, seat management, priority support, team onboarding                                    |

| **Enterprise** | 100+  | Team + full source code access (launcher, console, all components), dedicated support   |



A **free 7-day trial** starts automatically on install — full features, no license required. All plans work across multiple personal machines — one subscription, all your devices.



[gh-issues]: https://github.com/maxritter/pilot-shell/issues



Details and licensing at [pilot-shell.com](https://pilot-shell.com).



---



## Rolling Out for Your Team?



I'd love to help figure out if Pilot Shell is the right fit for your team and get everyone set up. For organizations with 100+ developers, the **[Enterprise tier](https://form.typeform.com/to/J7h2jjfw)** includes full source code access.



**[Book a Call](https://calendly.com/rittermax/pilot-shell)** · **[Enterprise Inquiry](https://form.typeform.com/to/J7h2jjfw)** · **[Send an Email](mailto:mail@maxritter.net)** · **[Connect on LinkedIn](https://www.linkedin.com/in/rittermax/)**



---



## FAQ



Does Pilot Shell send my code or data to external services?



**No code, files, prompts, project data, or personal information ever leaves your machine through Pilot Shell.** All development tools — code search (Probe), code intelligence (CodeGraph), persistent memory (Pilot Shell Console), session state, and quality hooks — run entirely locally.



Pilot Shell makes external calls **only for licensing**. Here is the complete list:



| When                              | Where             | What is sent                     |

| --------------------------------- | ----------------- | -------------------------------- |

| License validation (once per 24h) | `api.polar.sh`    | License key, organization ID     |

| License activation (once)         | `api.polar.sh`    | License key, machine fingerprint |

| Trial start (once)                | `pilot-shell.com` | Hashed hardware fingerprint      |



That's it — three calls total, each sent at most once (validation re-checks daily). No OS, no architecture, no Python version, no locale, no analytics, no heartbeats. The validation result is cached locally, and Pilot Shell works fully offline for up to 7 days between checks. Beyond these licensing calls, the only external communication is between Claude Code and Anthropic's API — using your own subscription or API key. If you enable the optional [Codex plugin](https://github.com/openai/codex-plugin-cc), adversarial reviews are sent to OpenAI's API — this is opt-in and disabled by default.



Is Pilot Shell enterprise-compliant for data privacy?



Yes. Your source code, project files, and development context never leave your machine through Pilot Shell. The only external calls are license validation (daily, license key only) and one-time activation/trial start (machine fingerprint only). No OS info, no version strings, no analytics, no telemetry. Enterprises using Claude Code with their own API key or Anthropic Enterprise subscription can add Pilot Shell without changing their data compliance posture.



Do I need a separate Anthropic subscription?



Yes. Pilot Shell enhances Claude Code — it doesn't replace it. You need an active Claude subscription — [Max 5x or 20x](https://claude.com/pricing) for solo developers, [Team Premium](https://claude.com/pricing) for teams, or [Enterprise](https://claude.com/pricing) for organizations with compliance or procurement requirements. Pilot Shell adds quality automation on top of whatever Claude Code access you already have.



Does Pilot Shell support AI models beyond Claude?



Pilot Shell is built for Claude Code and uses Anthropic's Claude models (Opus, Sonnet) for all planning, implementation, and verification. Additionally, the optional [Codex plugin](https://github.com/openai/codex-plugin-cc) adds OpenAI-powered adversarial review during `/spec` — an independent second opinion on your plans and code changes. Codex reviewers are disabled by default and can be enabled in Console Settings → Spec Workflow → Codex Reviewers.



Does Pilot Shell work with existing projects?



Yes — that's the primary use case. Pilot Shell doesn't scaffold or restructure your code. You install it, run `/setup-rules`, and it explores your codebase to discover your tech stack, conventions, and patterns. From there, every session has full context about your project. The more complex and established your codebase, the more value Pilot Shell adds — quality hooks catch regressions, persistent memory preserves decisions across sessions, and `/spec` plans features against your real architecture.



Does Pilot Shell work with any programming language?



Pilot Shell's quality hooks (auto-formatting, linting, type checking) currently support Python, TypeScript/JavaScript, and Go out of the box. TDD enforcement, spec-driven development, persistent memory, context optimization, and all rules and standards work with any language that Claude Code supports. You can add custom hooks for additional languages.



Can I use Pilot Shell on multiple projects?



Yes. Pilot Shell installs once globally and works across all your projects — you don't need to reinstall per project. All tools, rules, commands, and hooks live in `~/.pilot/` and `~/.claude/`, available everywhere. Just `cd` into any project and run `pilot`. Each project can optionally have its own `.claude/` rules, custom skills, and MCP servers for project-specific behavior. Run `/setup-rules` in each project to generate project-specific documentation and standards.



Why does Pilot Shell use bypass permissions mode?



Pilot Shell sets Claude Code to `bypassPermissions` mode by default so the `/spec` workflow can run autonomously — planning, implementing, and verifying without pausing for permission prompts at every tool call. This is what enables the end-to-end spec-driven development experience.



**In Quick Mode (regular chat), you have full control.** Press `Shift+Tab` at any time to cycle through Claude Code's permission modes:



| Mode             | Behavior                                              |

| ---------------- | ----------------------------------------------------- |

| **Plan**         | Claude proposes changes, you approve before execution |

| **Accept Edits** | File edits auto-approved, other actions still prompt  |

| **Normal**       | Fine-grained permission prompts for each tool call    |



You can also set a persistent default in `~/.claude/settings.json` by changing the `defaultMode` field to `acceptEdits`, `default`, `plan`, or `dontAsk`. Pilot Shell preserves your choice across updates — the installer merges permissions additively and never overwrites user customizations.



Can I add my own rules, commands, skills, and agents?



Yes. Create your own in your project's `.claude/` folder — rules, commands, skills, and agents are all plain markdown files. Your project-level assets load alongside Pilot Shell's built-in defaults and take precedence when they overlap. `/setup-rules` auto-discovers your codebase patterns and generates project-specific rules. `/create-skill` builds reusable skills from any topic interactively. View and manage all extensions on the Console Extensions page.



For monorepos, organize rules in nested subdirectories by product and team (e.g. `.claude/rules/my-product/team-x/`). Team-level rules must use `paths` frontmatter so they only load when working on relevant files. `/setup-rules` validates this structure, enforces path-scoping, and generates a `README.md` to document the organization.



Can I use Pilot Shell inside a Dev Container?



Yes. Copy the `.devcontainer` folder from this repository into your project, adapt it to your needs (base image, extensions, dependencies), and install Pilot Shell inside the container. Everything works the same — hooks, rules, MCP servers, persistent memory, and the Console dashboard all run inside the container. This is a great option for teams that want a consistent, reproducible development environment.



---



## Changelog



See the full changelog at [pilot.openchangelog.com](https://pilot.openchangelog.com/).



---



## Contributing



**Pull Requests** — New features, improvements, and bug fixes are welcome. You can improve Pilot Shell with Pilot Shell — a self-improving loop where your contributions make the tool that makes contributions better.



**Bug Reports** — Found a bug? [Open an issue](https://github.com/maxritter/pilot-shell/issues) on GitHub.



---






**Claude Code is powerful. Pilot Shell makes it reliable.**