Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 14 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.
- **`/prd`** — brainstorm ideas into clear requirements through with optional deep research
- **Quality hooks** — enforce linting, formatting, type checking, and tests as quality gates
- **Context engineering** — preserves decisions and knowledge across sessions
- **Code intelligence** — semantic search (Probe) + code knowledge graph (CodeGraph)
- **Code intelligence** — semantic search (Semble) + code knowledge graph (CodeGraph)
- **Token optimization** — 60–90% cost reduction via RTK and context-mode
- **Extensions** — reusable rules, skills, and MCP servers with team sharing and [customization](https://pilot-shell.com/docs/features/customization)
- **Console** — local web dashboard with real-time notifications and session management
Expand Down Expand Up @@ -118,9 +118,9 @@ For tighter isolation when working with untrusted code, combine the dev containe
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
2. **Claude files** — Installs into `~/.claude/` (native layout) — rules, commands, hooks, MCP servers, agents
3. **Config files** — Creates `.nvmrc` and project config
4. **Dependencies** — Installs Probe, RTK, CodeGraph, context-mode (better-sqlite3), [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp), [playwright-cli](https://github.com/microsoft/playwright-cli), [agent-browser](https://agent-browser.dev/), language servers
4. **Dependencies** — Installs Semble, RTK, CodeGraph, context-mode (better-sqlite3), [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp), [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
Expand Down Expand Up @@ -257,7 +257,7 @@ pilot
1. **Read existing rules** — inventory all `.claude/rules/` files, detect structure and path-scoping. Also detects `CLAUDE.md` and `AGENTS.md` (the cross-framework agent context file used by Codex, Cursor, etc.)
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
4. **Explore codebase** — hybrid semantic+lexical search with Semble, 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. Migrates `CLAUDE.md` / `AGENTS.md` content into modular rules
7. **Sync MCP docs** — smoke-test user MCP servers, document working tools
Expand Down Expand Up @@ -490,7 +490,7 @@ APM-compatible frontmatter is injected automatically. An `apm.yml` manifest is g

### 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.
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`, and `.mcp.json`. Source can be a **git repo** (team-wide) or a **local directory** (personal, no git needed). Team and Enterprise plans.

```bash
pilot customize install <git-url-or-path> # Install and apply
Expand All @@ -507,9 +507,8 @@ pilot customize remove # Restore Pilot defaults
| **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 |
| **Agents** | Drop `.md` files to add review/helper agents into `~/.claude/agents/` (native Claude location) |
| **MCP servers** | Top-level `.mcp.json` deep-merges into `~/.claude.json` `mcpServers` (adds team servers alongside Pilot's; pack values win on conflict) |
| **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](https://pilot-shell.com/docs/features/customization) for the full schema.
Expand All @@ -526,8 +525,7 @@ my-customization/
├── customization.json # Required: metadata + optional skill overlays
├── settings.json # Optional: deep-merges into ~/.claude/settings.json
├── claude.json # Optional: deep-merges into ~/.claude.json
├── .mcp.json # Optional: replaces ~/.claude/pilot/.mcp.json
├── .lsp.json # Optional: replaces ~/.claude/pilot/.lsp.json
├── .mcp.json # Optional: deep-merges into ~/.claude.json `mcpServers`
├── skills/ # → ~/.claude/skills/
│ ├── spec-plan/steps/
│ │ └── security-review.md # New step injected into spec-plan
Expand All @@ -541,7 +539,7 @@ my-customization/
├── hooks/ # → ~/.claude/pilot/hooks/
│ ├── team-lint-check.sh
│ └── hooks.json # Registers team-lint-check.sh alongside Pilot's hooks
└── agents/ # → ~/.claude/pilot/agents/
└── agents/ # → ~/.claude/agents/
└── team-reviewer.md
```

Expand Down Expand Up @@ -615,11 +613,11 @@ For full details on every component, see the **[Documentation](https://pilot-she
| [**Remote Control**](https://pilot-shell.com/docs/features/remote-control) | Control Pilot sessions from your phone, tablet, or any browser — send prompts, monitor progress, and receive notifications remotely |
| [**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), session continuity, memory capture, and session lifecycle management |
| [**Extensions**](https://pilot-shell.com/docs/features/extensions) | Unified view of skills, rules, commands, and agents across global, project, plugin, and remote scopes. Team sharing via git with push, pull, diff, and APM-compatible export |
| [**Customization**](https://pilot-shell.com/docs/features/customization) | Customize what Pilot auto-installs — tweak built-in skills (spec, prd, etc.), modify rules, register additional hooks, add agents, and adjust auto-applied MCP / LSP / Claude settings. Source is a git repo (team-wide) or local directory (personal). Skill overlays (`insert_after` / `insert_before` / `replace` / `disable`) modify core workflows without full-file forks; fragments stay pinned to upstream by hash with drift detection. Team and Enterprise plans |
| [**Customization**](https://pilot-shell.com/docs/features/customization) | Customize what Pilot auto-installs — tweak built-in skills (spec, prd, etc.), modify rules, register additional hooks, add agents, and adjust auto-applied MCP / Claude settings. Source is a git repo (team-wide) or local directory (personal). Skill overlays (`insert_after` / `insert_before` / `replace` / `disable`) modify core workflows without full-file forks; fragments stay pinned to upstream by hash with drift detection. Team and Enterprise plans |
| [**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 |
| [**MCP Servers**](https://pilot-shell.com/docs/features/mcp-servers) | 6 preconfigured MCP servers for library docs, persistent memory, web search, GitHub code search, web page fetching, and code knowledge graphs, plus the context-mode plugin for sandboxed execution |
| [**MCP Servers**](https://pilot-shell.com/docs/features/mcp-servers) | 7 preconfigured MCP servers for library docs, persistent memory, web search, GitHub code search, web page fetching, code knowledge graphs, and hybrid code search (Semble), plus the context-mode plugin for sandboxed execution |
| [**Language Servers**](https://pilot-shell.com/docs/features/language-servers) | Real-time diagnostics for Python (basedpyright), TypeScript (vtsls), Go (gopls). Auto-installed, auto-configured |
| [**Open Source Tools**](https://pilot-shell.com/docs/features/open-source-tools) | 20+ open-source tools installed alongside Pilot — Probe (semantic search), CodeGraph (code intelligence), RTK (token optimization), context-mode, language servers, and system prerequisites |
| [**Open Source Tools**](https://pilot-shell.com/docs/features/open-source-tools) | 20+ open-source tools installed alongside Pilot — Semble (hybrid code search), CodeGraph (code intelligence), RTK (token optimization), context-mode, language servers, and system prerequisites |

---

Expand Down Expand Up @@ -650,7 +648,7 @@ Pilot Shell is source-available under a commercial license. See the [LICENSE](LI
<details>
<summary><b>Does Pilot Shell send my code or data to external services?</b></summary>

**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.
**No code, files, prompts, project data, or personal information ever leaves your machine through Pilot Shell.** All development tools — code search (Semble), 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:

Expand Down Expand Up @@ -735,7 +733,7 @@ For monorepos, organize rules in nested subdirectories by product and team (e.g.
<details>
<summary><b>Can I customize Pilot's built-in workflows and defaults?</b></summary>

Yes — the **Customization** feature on Team and Enterprise plans lets you modify what Pilot Shell auto-installs, not just add alongside it. Tweak the built-in `/spec` workflow (insert a security-review step, replace the planning template, disable a step you don't need), adjust existing rules, register additional hooks, add review agents, change which MCP or LSP servers get configured, and override the auto-applied `settings.json` and `claude.json`. Source is either a **git repo** for your team or a **local directory** for personal use — no git needed for a one-off tweak.
Yes — the **Customization** feature on Team and Enterprise plans lets you modify what Pilot Shell auto-installs, not just add alongside it. Tweak the built-in `/spec` workflow (insert a security-review step, replace the planning template, disable a step you don't need), adjust existing rules, register additional hooks, add review agents, change which MCP servers get configured, and override the auto-applied `settings.json` and `claude.json`. Source is either a **git repo** for your team or a **local directory** for personal use — no git needed for a one-off tweak.

On **Team**, every developer runs `pilot customize install <source>` once and stays in sync via `pilot customize update`. Skill overlays stay pinned to Pilot's upstream by hash, so when Pilot ships an improvement to a step you replaced, `pilot customize status` flags the drift and `pilot customize diff` shows you what changed.

Expand Down
3 changes: 3 additions & 0 deletions console/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -64,5 +64,8 @@
"tailwindcss": "^4.1.18",
"typescript": "^5.3.0",
"vite": "^6.0.0"
},
"overrides": {
"fast-uri": "^3.1.2"
}
}
Binary file modified console/src/services/worker/http/routes/ToolSavingsRoutes.ts
Binary file not shown.
Binary file modified console/src/ui/viewer/views/Usage/ToolSavingsCards.tsx
Binary file not shown.
Binary file modified console/src/ui/viewer/views/Usage/index.tsx
Binary file not shown.
2 changes: 1 addition & 1 deletion docs/docusaurus/blog/2026-02-18-fast-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,6 @@ Speed Optimization

## About Pilot Shell

**Pilot Shell** keeps long Claude Code sessions usable: persistent memory carries decisions across compaction, and CodeGraph + Probe search the codebase by structure and meaning instead of by string.
**Pilot Shell** keeps long Claude Code sessions usable: persistent memory carries decisions across compaction, and CodeGraph + Semble search the codebase by structure and meaning instead of by string.

[See Pilot Shell on GitHub →](https://github.com/maxritter/pilot-shell)
1 change: 1 addition & 0 deletions docs/docusaurus/docs/features/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Run `pilot` or `ccp` with no arguments to start Claude with Pilot enhancements.
| `pilot [claude-flags...]` | Start Claude with any Claude CLI flags passed through |
| `pilot -p "prompt" [flags...]` | Headless mode — non-interactive for CI/CD, scripts |
| `pilot run [flags...]` | Explicit alias for starting Claude |
| `pilot agents` | Open Claude's agent view (`claude agents`) to manage multiple background sessions |
| `ccp` | Alias for `pilot` |
| `pilot update [--yes] [--json]` | Download and install the latest Pilot Shell release (replaces the startup banner) |
| `pilot check-context --json` | Get current context usage percentage |
Expand Down
14 changes: 6 additions & 8 deletions docs/docusaurus/docs/features/customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Customize everything Pilot Shell auto-installs on your machine. Tweak the built-
| **Rules** | `rules/*.md` | New rules are additive; same filename as a core rule → modifies the built-in rule |
| **Hooks** | `hooks/*.sh` + `hooks/hooks.json` | Scripts copied as-is; `hooks.json` registers additional hooks alongside Pilot's core hooks |
| **Agents** | `agents/*.md` | Add new agents alongside Pilot's built-ins (e.g. plug extra reviewers into the spec workflow) |
| **Top-level config** | `settings.json`, `claude.json`, `.mcp.json`, `.lsp.json` in the repo root | Modify the auto-applied Claude settings, app config, MCP server list, and LSP server list — see [Overriding top-level config](#overriding-top-level-config) below |
| **Top-level config** | `settings.json`, `claude.json`, `.mcp.json` in the repo root | Modify the auto-applied Claude settings, app config, and MCP server list — see [Overriding top-level config](#overriding-top-level-config) below |

## File structure

Expand All @@ -30,8 +30,7 @@ my-customization/
├── customization.json # Required: metadata + optional skill overlays
├── settings.json # Optional: deep-merges into ~/.claude/settings.json
├── claude.json # Optional: deep-merges into ~/.claude.json
├── .mcp.json # Optional: replaces ~/.claude/pilot/.mcp.json
├── .lsp.json # Optional: replaces ~/.claude/pilot/.lsp.json
├── .mcp.json # Optional: deep-merges into ~/.claude.json `mcpServers`
├── skills/ # → ~/.claude/skills/
│ ├── spec-plan/steps/
│ │ └── security-review.md # New step injected into spec-plan
Expand All @@ -45,7 +44,7 @@ my-customization/
├── hooks/ # → ~/.claude/pilot/hooks/
│ ├── team-lint-check.sh
│ └── hooks.json # Registers team-lint-check.sh (see below)
└── agents/ # → ~/.claude/pilot/agents/
└── agents/ # → ~/.claude/agents/ (native Claude location)
└── team-reviewer.md
```

Expand Down Expand Up @@ -168,20 +167,19 @@ Your step now appears in `~/.claude/skills/<skill>/SKILL.md` right after the anc

## Overriding top-level config

Four Pilot config files can be overridden from your repo root. They use different strategies based on what each file contains:
Three Pilot config files can be overridden from your repo root. All three use deep-merge — Pilot is no longer registered as a Claude Code plugin, so MCP servers live at the native user-scope location (`~/.claude.json` `mcpServers` key) instead of a plugin-local file. LSP servers are now installed via Anthropic's [`Piebald-AI/claude-code-lsps`](https://github.com/Piebald-AI/claude-code-lsps) marketplace and are no longer Pilot-managed; teams that need additional LSPs ship them as separate Claude Code plugins.

| File in repo | Destination | Strategy | Notes |
|--------------|-------------|----------|-------|
| `settings.json` | `~/.claude/settings.json` | Deep-merge | Pack keys win; the launcher still re-injects the `model` field and env vars on every startup. |
| `claude.json` | `~/.claude.json` | Deep-merge | Preserves oauth account, project history, and caches — pack only overrides the keys it sets. |
| `.mcp.json` | `~/.claude/pilot/.mcp.json` | Full copy | Pilot-owned; safe to replace. |
| `.lsp.json` | `~/.claude/pilot/.lsp.json` | Full copy | Pilot-owned; safe to replace. |
| `.mcp.json` | `~/.claude.json` `mcpServers` | Deep-merge | Pack's `mcpServers` entries are added to (or override by key) the user-scope MCP server list. Installer-merged Pilot servers (`context7`, `codegraph`, etc.) and any user-added entries are preserved. |

**Deep-merge semantics:** nested objects merge recursively (pack values replace specific keys), arrays replace wholesale. If you want to add an entry to an array, your pack's file must include every item you want the final array to contain.

**When Pilot updates itself** (installer re-runs on version change, or you re-run `install.sh`): Pilot's baseline is re-applied, then your pack overlay re-applies on top. Pack values survive as "user customizations" through the three-way merge.

**On `pilot customize remove`:** `.mcp.json` and `.lsp.json` are deleted — re-run `install.sh` or the installer to restore Pilot defaults. `settings.json` and `claude.json` are left in place because they contain user state (oauth session, project history) — merged pack values stay until you edit them out manually. This is intentional safety — removing a pack should never wipe user data.
**On `pilot customize remove`:** all three are merge targets and left in place because they contain user state (oauth session, project history, MCP server config) — merged pack values stay until you edit them out manually. This is intentional safety — removing a pack should never wipe user data.

## See Also

Expand Down
Loading
Loading