python standards

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.

<details>
<summary><b>Downgrade</b></summary>

If you encounter an issue or unfixed bug in the latest version, you can always go back to a previous version (see releases):

<details>
<summary><b>Uninstalling</b></summary>

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

<details>
<summary><b>Using a Dev Container</b></summary>

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.

</details>

<details>
<summary><b>What the installer does</b></summary>

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

</details>

---

<h2 id="features">How It Works</h2>

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.

/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.

<img src="docs/img/specifications.png" alt="Pilot Shell Console — Specifications" width="700">

<details>
<summary><b>Feature Mode</b></summary>

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.

</details>

<details>
<summary><b>Bugfix Mode</b></summary>

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.

</details>

Status Line

Pilot shell ships with its own advanced status line with real-time session metrics and spec progress:

<img src="docs/img/statusline.png" alt="Pilot Shell Status Line" width="700">

<details>
<summary><b>All fields explained</b></summary>

Line 1 — Session Metrics (separated by |):

| Widget | Description |
| ----------------- | ------------------------------------------------------------------------------- |
| Model | Active model in short form (Opus 4.7 [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+ | |
| Savings | Token savings percentage from RTK proxy (Savings: N%), shown when no usage data |

Line 2 — Mode:

Line 3 — Version & Session Info:

Pilot <version> (<tier>) · CC <version> (<subscription>) · sessions <N> · memories <N>

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.

</details>

Pilot Shell Console

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

<img src="docs/img/dashboard.png" alt="Pilot Shell Console — Dashboard" width="700">

<details>
<summary><b>All views</b></summary>

Each view with project-specific data has an inline Project Filter dropdown — switch projects without leaving the page. Dashboard stats tiles are clickable — navigate directly to the relevant view.

| View | What it shows |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Dashboard | Global command center — 8 clickable stat cards, 4 recent cards (Specifications, Requirements, Sessions, Memories) with "Show all" links. Active specs as pills in the top bar, notification bell in top right. |
| Sessions | Browse past sessions with search. Copy the session ID and use /resume <session-id> in Claude Code to jump back into any session. |
| Memories | Browsable observations — decisions, discoveries, bugfixes — with type filters and search. Each memory shows its session — click to navigate. |
| Requirements | PRD documents with view/annotate modes. Selected shown as a tab, others in a Previous dropdown. |
| Specifications | 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 |
| Usage | Daily token costs, model routing breakdown, and usage trends |
| Help | Documentation, guides, and quick-start resources |
| 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 with pricing info |

</details>

<details>
<summary><b>Visual plan annotation</b></summary>

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

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.

</details>

<details>
<summary><b>Spec sharing</b></summary>

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

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

</details>

<details>
<summary><b>Code review</b></summary>

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

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.

</details>

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:

<img src="docs/img/extensions.png" alt="Pilot Shell Console — Extensions" width="700">

<details>
<summary><b>Extension categories</b></summary>

| 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.

</details>

<details>
<summary><b>Scopes: Global, Project, Plugin</b></summary>

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 <name>). They appear as read-only items — visible but not editable.

</details>

<details>
<summary><b>Team sharing & APM (Team tier)</b></summary>

Connect a git repository to share extensions across your team:

APM format — check one box and your remote becomes an APM package, 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.

</details>

Customization

Customize everything Pilot auto-installs — tweak the built-in /spec workflow, modify existing rules, register additional hooks, add agents, and adjust the auto-applied settings.json, claude.json, .mcp.json, and .lsp.json. Source can be a git repo (team-wide) or a local directory (personal, no git needed). Team and Enterprise plans.

<details>
<summary><b>What you can customize</b></summary>

| Target | How |
|--------|-----|
| Skills (built-in workflows like /spec, /prd) | Overlay ops in customization.json: insert_after, insert_before, replace, disable — or ship an entirely new skill folder |
| Rules | New rules are additive; same filename as a core rule overrides it |
| Hooks | Scripts copy to ~/.claude/pilot/hooks/; ship hooks.json to register them alongside Pilot's built-ins |
| Agents | Drop .md files to add review/helper agents into the spec workflow |
| MCP servers | Top-level .mcp.json replaces the auto-configured server list |
| LSP servers | Top-level .lsp.json replaces the auto-configured server list |
| Claude settings | Top-level settings.json and claude.json deep-merge into the user's files — model prefs, permissions, env vars, etc. User state (oauth, projects) is preserved |

Replaced skill fragments stay pinned to upstream by hash. pilot customize status surfaces drift when Pilot upgrades a replaced step; pilot customize diff <skill>/<step-id> shows what changed so you can port improvements. See the Customization guide for the full schema.

</details>

<details>
<summary><b>Repository / folder structure</b></summary>

The layout is the same whether you publish it as a git repo or keep it as a local folder. Directory names map 1:1 to ~/.claude/:

Only ship the files and directories you need. A repo with just rules/ is a valid customization; so is one with just .mcp.json.

</details>

Pilot Bot

Run Claude Code as a persistent 24/7 automation agent with scheduled tasks, background jobs and heartbeat monitoring:

Pilot Bot defines scheduled jobs, automates recurring tasks, and monitor system health around the clock. If the Telegram Channels plugin is installed, the bot auto-detects it and enables bidirectional messaging. Similar to OpenClaw, but without the added complexity and costs.

<details>
<summary><b>Bot skills</b></summary>

| Skill | Purpose |
|-------|---------|
| bot-boot | Boot sequence — health check, job registration, heartbeat setup |
| bot-heartbeat | Periodic health checks, notifies only when issues are detected |
| bot-jobs | Manage scheduled jobs — add, remove, pause, resume, edit, list |
| bot-channel-task | Channel task flow — acknowledge, execute, report (when Telegram is available) |
| bot-defaults | Standard bot behaviors (dedup, reporting, error handling) |

</details>

/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.

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.

/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.

<details>
<summary><b>What /setup-rules Does</b></summary>

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

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.

</details>

/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.

<details>
<summary><b>What /create-skill Does</b></summary>

6 phases that turn domain knowledge into a reusable skill:

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.

</details>

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.

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.

---