### Setup Hook Input Example

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/session-lifecycle-hooks.md

The Setup hook is used for one-time initialization tasks at the start of a session. It includes session details, the hook event name, the trigger for the setup, and the current working directory.

```json
{
  "session_id": "abc123",
  "hook_event_name": "Setup",
  "trigger": "init",
  "cwd": "/path/to/project"
}
```

--------------------------------

### Example Task Creation and Dependency Setup

Source: https://github.com/maxritter/claude-pilot/blob/main/pilot/commands/spec-implement.md

Provides a concrete example of creating multiple tasks and establishing blocking dependencies between them. This illustrates the practical application of TaskCreate and TaskUpdate for a sequence of tasks.

```claude-pilot-dsl
TaskCreate: "Task 1: Create user model"           → id=1
TaskCreate: "Task 2: Add API endpoints"            → id=2, addBlockedBy: [1]
TaskCreate: "Task 3: Write integration tests"      → id=3, addBlockedBy: [2]
TaskCreate: "Task 4: Add documentation"            → id=4, addBlockedBy: [2]
```

--------------------------------

### Initialize Claude with Setup Hooks

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-code-setup-hooks.md

This snippet shows how to initiate Claude with setup hooks. The `--init` flag triggers the setup hook before Claude boots up, allowing for automated dependency installation and environment configuration. Claude then analyzes the hook's execution results.

```bash
claude --init
```

--------------------------------

### Setup Configuration for npm install and Database Migrations

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/session-lifecycle-hooks.md

Configures the 'Setup' hook to run 'npm install' and 'npm run db:migrate' for the 'init' matcher. It also includes a 'maintenance' matcher to run 'npm prune', 'npm dedupe', and remove the '.cache' directory.

```json
{
  "hooks": {
    "Setup": [
      {
        "matcher": "init",
        "hooks": [
          {
            "type": "command",
            "command": "npm install && npm run db:migrate"
          }
        ]
      },
      {
        "matcher": "maintenance",
        "hooks": [
          {
            "type": "command",
            "command": "npm prune && npm dedupe && rm -rf .cache"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Claude Pilot Slash Command for Installation Results

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-code-setup-hooks.md

This markdown describes the '/install' slash command in Claude Pilot, which is used to run setup and report installation results. It outlines a workflow involving priming the agent, reading log files, analyzing successes and failures, and writing results to a markdown file.

```markdown
---
description: Run setup and report installation results
---

## Workflow

1. Run /prime to understand the codebase
2. Read the log file at .claude/hooks/setup.init.log
3. Analyze for successes and failures
4. Write results to app_docs/install_results.md
5. Report to user
```

--------------------------------

### General MCP Server Configuration Example

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/mcp-basics.md

This JSON snippet demonstrates the general structure for configuring any MCP server. It includes placeholders for the server name, the command to run (typically 'npx'), installation arguments, and necessary environment variables such as API keys. This pattern is used across different MCP server setups.

```json
// Claude Code CLI: ~/.claude.json or project-level .mcp.json
// Claude Desktop: claude_desktop_config.json
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### Python Script for Setup Hook Execution

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-code-setup-hooks.md

This Python script demonstrates the execution of setup tasks within a Claude Pilot hook. It includes installing backend and frontend dependencies, initializing the database, and logging the completion status and additional context.

```python
def main():
    # Install backend dependencies
    run(["uv", "sync"], cwd="apps/backend")
 
    # Install frontend dependencies
    run(["npm", "install"], cwd="apps/frontend")
 
    # Initialize database
    run(["uv", "run", "python", "init_db.py"], cwd="apps/backend")
 
    # Tell Claude what happened
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "Setup",
            "additionalContext": "Setup complete. Run 'just be' and 'just fe' to start."
        }
    }))
```

--------------------------------

### Documentation Writer Command Example

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/custom-agents.md

This command defines an agent responsible for writing documentation. It takes arguments to specify the content to document and includes sections for purpose, setup, usage, and troubleshooting, targeting developers new to the project.

```markdown
Write documentation for: $ARGUMENTS

Include:

- Purpose and overview
- Setup instructions
- Usage examples
- Common troubleshooting

Target audience: developers new to this project.
Write in clear, concise language.
```

--------------------------------

### JavaScript Jest Setup/Teardown Example

Source: https://github.com/maxritter/claude-pilot/blob/main/pilot/rules/testing-strategies-coverage.md

Illustrates basic setup and teardown functions in JavaScript using Jest, which are executed before and after each test to ensure isolated test environments.

```javascript
beforeEach(() => { /* Setup */ });
afterEach(() => { /* Cleanup */ });
```

--------------------------------

### Example User Question for MCP Documentation Updates

Source: https://github.com/maxritter/claude-pilot/blob/main/pilot/commands/sync.md

This example shows how to use `AskUserQuestion` to prompt the user about detected changes in MCP server configurations and whether to update the documentation. It provides options for updating all servers, reviewing changes individually, or skipping the update.

```text
Question: "Found MCP server changes. Update documentation?"
Header: "MCP Sync"
Options:
- "Update all" - Document all user MCP servers
- "Review each" - Walk through changes one by one
- "Skip" - Keep existing documentation
```

--------------------------------

### Configure MCP Server with Full npx Path

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/cursor-mcp-setup.md

Provides a fallback configuration for MCP servers when 'npx' is not found in the system's PATH. This example specifies the absolute path to the npx executable, ensuring the server can be launched correctly.

```json
{
  "mcpServers": {
    "server-name": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-name"]
    }
  }
}
```

--------------------------------

### Build a Custom MCP Server in TypeScript

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/mcp-servers-claude-code.md

A minimal example of a custom MCP server built using TypeScript and the Model Context Protocol SDK. It defines a server named 'my-server' with a single tool 'get_status' and connects using StdIO transport.

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.tool("get_status", "Check system status", {}, async () => ({
  content: [{ type: "text", text: "All systems operational" }]
}));

const transport = new StdioServerTransport();
await server.connect(transport);
```

--------------------------------

### MCP-CLI Command Examples

Source: https://github.com/maxritter/claude-pilot/blob/main/pilot/rules/mcp-cli.md

Demonstrates various MCP-CLI commands for interacting with MCP servers. Includes listing servers, viewing tools with parameters and descriptions, inspecting tool schemas, executing tools with JSON arguments, and searching for tools.

```bash
# List all servers and tool names
mcp-cli

# See all tools with parameters
mcp-cli filesystem

# With descriptions (more verbose)
mcp-cli filesystem -d

# Get JSON schema for specific tool
mcp-cli filesystem/read_file

# Call the tool
mcp-cli filesystem/read_file '{"path": "./README.md"}'

# Search for tools
mcp-cli grep "*file*"

# JSON output for parsing
mcp-cli filesystem/read_file '{"path": "./README.md"}' --json

# Complex JSON with quotes (use '-' for stdin input)
mcp-cli server/tool - <<EOF
{"content": "Text with 'quotes' inside"}
EOF

# Or pipe from a file/command
cat args.json | mcp-cli server/tool -

# Complex Command chaining with xargs and jq
mcp-cli filesystem/search_files '{"path": "src/", "pattern": "*.ts"}' --json | jq -r '.content[0].text' | head -1 | xargs -I {} sh -c 'mcp-cli filesystem/read_file "{\"path\": \"{}\"}"'
```

--------------------------------

### Example Backend API Skill Configuration

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-md-mastery.md

This example demonstrates how to structure a skill for backend API development, separating framework details, development commands, and patterns. It contrasts with embedding this information directly in CLAUDE.md.

```markdown
# Backend API Development Skill

## Framework

FastAPI with SQLAlchemy ORM, Pydantic validation.

## Development Commands

- `uvicorn app.main:app --reload` - Start dev server
- `pytest tests/ -v` - Run test suite
- `alembic upgrade head` - Apply migrations

## Patterns

[Detailed patterns, examples, conventions...]
```

--------------------------------

### Configure Brave Search MCP Server in Cursor

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/cursor-mcp-setup.md

This configuration enables web search capabilities within the Cursor IDE by setting up the Brave Search MCP server. It requires Node.js and npm to be installed, and an API key for Brave Search.

```json
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "your-api-key" }
    }
  }
}
```

--------------------------------

### Verify Claude Installation

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/installation-guide.md

These commands are used to verify that Claude Code has been installed correctly. `claude --version` displays the installed version, and `claude doctor` runs diagnostic checks.

```bash
claude --version
claude doctor
```

--------------------------------

### Example User Question for MCP Server Issues

Source: https://github.com/maxritter/claude-pilot/blob/main/pilot/commands/sync.md

This example demonstrates how to use an `AskUserQuestion` function to present MCP server health check findings to the user and gather their decision on how to proceed. It includes a question, header, and predefined options for the user to choose from.

```text
Question: "Found MCP server issues. How to proceed?"
Header: "MCP Issues"
Options:
- "Document working tools only" - Skip broken tools/servers
- "Document all with status notes" - Include broken tools with error notes
- "Skip MCP sync" - Don't document any MCP servers
```

--------------------------------

### Justfile for Claude Code Setup and Maintenance

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-code-setup-hooks.md

This Justfile defines commands for deterministic, agentic, and interactive setup and maintenance using Claude. It simplifies remembering complex flags by mapping short aliases to full Claude commands, enhancing team productivity.

```makefile
# Deterministic codebase setup
cldi:
  claude --init

# Agentic codebase setup
cldii:
  claude --init "/install"

# Interactive setup (asks questions)
cldit:
  claude --init "/install true"

# Deterministic maintenance
cldm:
  claude --maintenance

# Agentic maintenance (with reporting)
cldmm:
  claude --maintenance "/maintenance"

```

--------------------------------

### Install Sandbox Dependencies on Linux/WSL

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/troubleshooting.md

Installs the 'bubblewrap' and 'socat' packages required for sandboxing on Linux and WSL. This is necessary to resolve the 'bubblewrap not installed' error.

```shell
# Debian/Ubuntu
sudo apt install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat
```

--------------------------------

### Initialize Claude with Setup Hooks and Command Execution

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-code-setup-hooks.md

This command initializes Claude with setup hooks and then automatically executes a specified command, such as '/install'. After the hook runs, the agent processes the log files, analyzes the outcome, and reports the results.

```bash
claude --init "/install"
```

--------------------------------

### Test Hook Triggering with Python

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/hooks-guide.md

A command-line example to test if a Python hook is triggering correctly. It pipes a sample JSON payload representing a session start event to a Python script, allowing developers to verify hook execution and input handling.

```bash
echo '{"session_id":"test"}' | python your-hook.py
```

--------------------------------

### Install and Configure Claude Code Permission Hook

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/permission-hook-guide.md

Install the permission hook globally and configure it for use with Claude Code. This involves running installation and configuration commands.

```bash
npm install -g @abdo-el-mobayad/claude-code-fast-permission-hook
cf-approve install
cf-approve config
```

--------------------------------

### Initialize Claude with Setup Hooks and Interactive Command

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-code-setup-hooks.md

This command initializes Claude with setup hooks and then executes an interactive command like '/install true'. The agent supervises the script's execution, asks clarifying questions to adapt to the environment, and maintains context awareness.

```bash
claude --init "/install true"
```

--------------------------------

### Install Claude Code using Native Installers (Windows, macOS, Linux)

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/installation-guide.md

This snippet shows how to install Claude Code using the recommended native installers for different operating systems. For Windows, it uses PowerShell, while for macOS and Linux, it uses curl and bash. Ensure you have terminal access.

```powershell
irm https://claude.ai/install.ps1 | iex
```

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

--------------------------------

### Install Claude Code using npm (macOS/Linux)

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/installation-guide.md

This method installs Claude Code globally using npm, which requires Node.js version 18 or higher. It includes steps to configure the PATH environment variable if the 'claude' command is not found after installation.

```bash
npm install -g @anthropic-ai/claude-code

# If you see "command not found", fix PATH:
# For zsh (macOS default):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For bash (Linux default):
# mkdir ~/.npm-global
# npm config set prefix '~/.npm-global'
# echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

--------------------------------

### Troubleshoot 'Command Not Found' Error

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/installation-guide.md

This command helps diagnose the 'Command Not Found' error by checking if the 'claude' executable is installed and accessible in the system's PATH. It also lists globally installed npm packages.

```bash
which claude
npm list -g @anthropic-ai/claude-code
```

--------------------------------

### Claude Pilot Setup Commands and Modes

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-code-setup-hooks.md

This table outlines different scenarios and the corresponding Claude Pilot modes and commands. It helps users choose the appropriate command for tasks like CI/CD, local setup, troubleshooting, onboarding, and dependency updates.

```markdown
| Scenario | Mode | Command |
| --- | --- | --- |
| CI/CD pipeline | Deterministic | `claude --init-only` |
| Quick local setup | Deterministic | `just cldi` |
| Setup failed, need diagnosis | Agentic | `just cldii` |
| New engineer, unfamiliar codebase | Interactive | `just cldit` |
| Weekly dependency updates | Agentic | `just cldmm` |
```

--------------------------------

### Permission Hook Configuration File Example

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/permission-hook-guide.md

An example of the configuration file (`~/.claude-code-fast-permission-hook/config.json`) for the permission hook. It specifies LLM provider, model, API key, and cache settings.

```json
{
  "llm": {
    "provider": "openai",
    "model": "openai/gpt-4o-mini",
    "apiKey": "sk-or-v1-your-key",
    "baseUrl": "https://openrouter.ai/api/v1"
  },
  "cache": {
    "enabled": true,
    "ttlHours": 168
  }
}
```

--------------------------------

### MCP CLI Server Command Example

Source: https://github.com/maxritter/claude-pilot/blob/main/pilot/commands/sync.md

Demonstrates how to use the MCP CLI to interact with a server-specific tool. It requires the server name, tool name, and a JSON payload for parameters.

```bash
mcp-cli server-name/tool-name '{"param": "value"}'
```

--------------------------------

### Building and Running Artifacts

Source: https://github.com/maxritter/claude-pilot/blob/main/pilot/rules/execution-verification.md

Instructions for building software packages (e.g., npm, Python wheels) and then running the built artifact, not the source code. Covers both Node.js and Python examples.

```bash
# Build the package
npm run build
# Or
python -m build

# Run the built artifact, not source
node dist/index.js
# Or
pip install dist/*.whl && run-command
```

--------------------------------

### Set Up Different Session Contexts with --init

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/slash-commands-and-init.md

These bash commands show how to use the `--init` flag to load different context files for various development tasks. Examples include backend development, frontend work, and code review sessions, each loading a specific predefined context.

```bash
# Backend development
claude --init /commands/backend.md

# Frontend work
claude --init /commands/frontend.md

# Code review session
claude --init /commands/review-mode.md
```

--------------------------------

### Reinstall Claude Code with Native Installer

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/troubleshooting.md

Fix 'command not found: claude' errors by reinstalling Claude Code using the native installer script. This is recommended for macOS and Linux systems.

```shell
# Reinstall with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex

# Verify installation
which claude
```

--------------------------------

### Install jq Package Manager

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/statusline-guide.md

Provides commands to install the `jq` utility, a lightweight and flexible command-line JSON processor, on different operating systems. `jq` is essential for parsing JSON data in the status line scripts.

```bash
# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq

# Windows (via scoop)
scoop install jq
```

--------------------------------

### CLAUDE.md Skill Reference Example

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-md-mastery.md

This example shows how to reference skills within the CLAUDE.md file, indicating which skills are key for the project. This allows Claude to load relevant domain knowledge efficiently.

```markdown
### Key Skills

`backend-api`, `frontend-react`, `database-ops`, `deployment`

Load relevant skills before beginning domain-specific work.
```

--------------------------------

### Update Claude Code Installation

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-opus-4-5-guide.md

This command updates the Claude Code installation to the latest version, which is a recommended step to resolve issues like 'model not found' and ensure access to the newest features.

```bash
npm update -g @anthropic-ai/claude-code
```

--------------------------------

### Define a Launcher Shortcut for Context Initialization

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/claude-code-session-context.md

This configuration defines a shortcut command (e.g., 'blog') that, when executed, runs a specific Claude command with the `--init` flag. This allows for quick and easy launching of Claude sessions with pre-defined context.

```makefile
blog:
    claude --init "/blog"
```

--------------------------------

### Troubleshooting: Verify Hook Installation and Status

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/permission-hook-guide.md

Commands to check if the permission hook is installed correctly and currently running. Use `cf-approve doctor` for a diagnostic check and `cf-approve status` for current status.

```bash
cf-approve doctor
cf-approve status
```

--------------------------------

### Component Generation Framework Example

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/efficiency-patterns.md

A simple framework to guide Claude in generating new components by copying and adapting existing examples. It emphasizes maintaining structure, updating data, and reusing tests.

```markdown
# Component Generation Framework

When creating new [cards/forms/modals], follow the pattern in /components/examples/:

1. Copy the closest existing example
2. Replace data fields (keep structure identical)
3. Update types to match new data model
4. Run existing tests as template for new tests

```

--------------------------------

### Manual Foundation Building for Patterns

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/efficiency-patterns.md

Instructions for setting up a directory to manually build and document initial components, establishing a pattern library for Claude.

```shell
mkdir /patterns/user-interfaces
# Build:LoginForm, SignupForm, ProfileForm, etc.
# Document decisions in each component

```

--------------------------------

### Perform Complete Claude Code Reset

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/troubleshooting.md

Provides a sequence of commands to completely reset Claude Code by uninstalling it, removing configuration files, and performing a fresh install using the native installer. This is a last resort for persistent issues.

```shell
# 1. Uninstall any existing installation
npm uninstall -g @anthropic-ai/claude-code  # if installed via npm

# 2. Remove config files
rm ~/.claude.json
rm -rf ~/.claude/

# 3. Fresh install with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex

# 4. Reconfigure
claude config
```

--------------------------------

### Nuclear Reset for Claude Code

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/installation-guide.md

Performs a complete reset of the Claude Code installation by uninstalling it, removing configuration and cache directories, cleaning the npm cache, and then reinstalling the package. This is a last resort for fixing persistent issues. It concludes with a version check.

```shell
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude ~/.npm/_cacache
npm cache clean --force
npm install -g @anthropic-ai/claude-code
claude --version
```

--------------------------------

### MCP Server Builder Instructions Example

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/mcp-tool-search.md

Provides an example of the `serverInstructions` field within the `mcpServers` configuration. This field is crucial for MCP Tool Search as it helps Claude Code understand the capabilities of a server and when to search for its tools.

```json
{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "serverInstructions": "Database operations for PostgreSQL including queries, schema management, and data migrations. Use for any database-related tasks."
    }
  }
}
```

--------------------------------

### Example: Debugging with DevTools and Tracing using Playwright CLI

Source: https://github.com/maxritter/claude-pilot/blob/main/pilot/rules/playwright-cli.md

An example showcasing debugging capabilities by combining DevTools and tracing. Open a page, start tracing, perform actions like clicking and filling, then open console and network inspectors, and finally stop the trace.

```bash
playwright-cli open https://example.com
playwright-cli tracing-start
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli console
playwright-cli network
playwright-cli tracing-stop
playwright-cli close
```

--------------------------------

### Define an Onboarding Context Slash Command

Source: https://github.com/maxritter/claude-pilot/blob/main/docs/site/src/content/blog/slash-commands-and-init.md

This markdown file defines a slash command to provide onboarding context for a project. It outlines the project's key architecture components, including backend, frontend, database, and testing frameworks, along with commands to run tests for each.

```markdown
<!-- .claude/commands/onboard.md -->
You're working on [Project Name]. Key architecture:
- Backend: Python/FastAPI in src/api/
- Frontend: React/TypeScript in src/web/
- Database: PostgreSQL with SQLAlchemy ORM
- Tests: pytest (backend), vitest (frontend)

Always run `uv run pytest -q` after backend changes.
Always run `npm test` after frontend changes.
```