developer-mode

A pi coding agent extension that gives Claude deep access to pi's own documentation, examples, and development tools — making it dramatically better at building pi extensions and working in complex multi-session setups.

What it does

• Docs in context — Embedded pi documentation corpus searchable via tools, injected into the system prompt on demand
• Learnings — Persistent project-specific knowledge base that survives /reload and /new
• Subprocess spawning — Delegate tasks to headless pi subprocesses and get structured output
• Tmux management — Spawn, control, and watch tmux sessions directly from Claude
• Fresh-context review — One-command code review in an isolated pi session with real-time observation
• Debug & introspection — Inspect extension health, system prompt budget, and conversation history

Installation

pi install git:github.com/dkmaker/pi-extension-developer-mode

Requires pi coding agent to be installed.

Prerequisites

• tmux — Required for tmux session management tools (pi_dev_tmux_*) and /dev-review. Install via your package manager (brew install tmux, apt install tmux, etc.)

Features

Documentation tools

pi_dev_search — Search documentation

Search the embedded pi docs corpus by keyword.

query: "register tool"          → matching sections with titles, categories, slugs
query: "TUI components"         → UI-related docs
query: "custom provider"        → provider setup docs

Parameters:

• query (string) — search terms
• limit (number, optional) — max results (default: 10)

pi_dev_get — Get documentation section

Retrieve a specific documentation section by slug.

slug: "extensions/register-tool"
slug: "cli/overview"
slug: "tui/components"

Parameters:

• slug (string) — documentation section slug

pi_dev_examples — Browse extension examples

Browse code examples by category or fetch a specific example.

(no args)          → list all categories with counts
category: "tools"  → list examples in the tools category
slug: "examples/minimal-tool"  → fetch full example source

Parameters:

• category (string, optional) — filter by category (e.g. tools, events, tui)
• slug (string, optional) — fetch a specific example by full slug

Knowledge & learning

pi_dev_learn — Store a learning

Persist a project-specific learning to the knowledge base. Learnings are injected into the system prompt automatically.

Parameters:

• title (string) — short title (e.g. "Never use JSX in pi extensions")
• keywords (string) — comma-separated keywords for search
• context (string) — when this learning applies
• content (string) — the full lesson in markdown

Introspection tools

pi_dev_debug — Extension health check

Inspect extension state.

check: "context"     → system prompt content, token count, model
check: "tools"       → registered tools with schema sizes
check: "extensions"  → loaded extension files
check: "staleness"   → doc corpus freshness vs installed pi version

Parameters:

• check (string) — one of context, tools, extensions, staleness

pi_dev_transcript — Session transcript

Inspect current (or past) session conversation history with visibility annotations showing what the AI saw vs what the user saw.

(defaults)                 → last 10 turns, summary format
format: "summary"          → compact overview to orient
format: "full"             → full content
turn: 5                    → deep dive on specific turn
filter: "tools_only"       → show only tool calls
filter: "user_only"        → show only user messages
filter: "hidden_only"      → show only hidden context
session: "list"            → list all sessions for this project
session: "abc123"          → read a specific past session

Parameters:

• last_n (number, optional) — recent turns to show (default: 10)
• turn (number, optional) — specific turn for deep dive
• max_tokens (number, optional) — output token budget (default: 3000)
• format (string, optional) — summary or full
• filter (string, optional) — tools_only, user_only, or hidden_only
• session (string, optional) — list or a session ID prefix

pi_dev_prompt_dismiss — Dismiss prompt section

Remove a context-triggered system prompt section that is no longer relevant. The section can re-activate on future relevant prompts.

Parameters:

• section_id (string) — section ID to dismiss (e.g. pm-awareness, tmux-setup)

Subprocess spawning

pi_dev_spawn — Spawn pi subprocess

Run a headless pi instance with a prompt and get structured output. Useful for delegating tasks, running isolated operations, or testing.

prompt: "List all TypeScript files in src/"
timeout: 120
args: "--no-session --no-extensions --no-skills"

Parameters:

• prompt (string) — prompt to send to the subprocess
• timeout (number, optional) — timeout in seconds (default: 60)
• args (string, optional) — extra CLI args (default: --no-session --no-extensions --no-skills)

Tmux session management

pi_dev_tmux_spawn — Spawn tmux session

Create a new managed tmux session.

Parameters:

• command (string, optional) — command to run (default: $SHELL)
• name (string, optional) — session name (default: auto-generated)
• relay (boolean, optional) — inject relay extension for live status feedback (use when spawning a child pi session you plan to watch)

pi_dev_tmux_send — Send keys to tmux

Send keystrokes to a managed session (tmux send-keys format).

Parameters:

• id (string) — session ID
• keys (string) — keystrokes (e.g. ls -la or Enter)

pi_dev_tmux_inject — Inject content into tmux

Paste multi-line content into a tmux pane.

Parameters:

• id (string) — session ID
• content (string) — content to inject
• submit (boolean, optional) — send Enter after pasting (default: false)

pi_dev_tmux_capture — Capture tmux pane

Read the current pane output.

Parameters:

• id (string, optional) — session ID (omit to capture current tmux session)
• lines (number, optional) — lines from scrollback (default: visible pane)
• file (string, optional) — save capture to file

pi_dev_tmux_attach — Attach to tmux session

Open the session in a new terminal window.

Parameters:

• id (string) — session ID

pi_dev_tmux_close — Close tmux session

Kill a managed session and clean up.

Parameters:

• id (string) — session ID

pi_dev_tmux_list — List tmux sessions

List all managed sessions with status (alive/dead).

pi_dev_tmux_reload — Self-reload via tmux

Trigger a pi self-reload (equivalent to /reload) and optionally inject a follow-up prompt.

Parameters:

• prompt (string, optional) — follow-up prompt to inject after reload

pi_dev_tmux_watch — Watch tmux session

Monitor a child pi session for turn-end events. When the child completes a turn (working → idle), a notification with pane capture is injected into the parent session.

Parameters:

• id (string) — session ID to watch

pi_dev_tmux_unwatch — Unwatch tmux session

Stop watching a session for turn-end events.

Parameters:

• id (string) — session ID

pi_dev_tmux_new — Fresh session via tmux

Inject /new into the current tmux pane to start a fresh pi session, then inject a follow-up prompt. Only works when pi is running inside tmux. This is a terminal operation — the current agent turn ends and a new session begins.

Parameters:

• prompt (string) — prompt to inject into the fresh session
• delay (number, optional) — seconds to wait after /new before injecting prompt (default: 2)

Commands

/dev-index — Interactive documentation browser

Opens a TUI for browsing and searching the pi documentation corpus. Select a section to have it read aloud to the AI.

/dev-review [instructions] — Fresh-context review

Spawns a clean pi session in tmux (no extensions, no skills, fresh context) and injects a review plan. Opens an observer terminal window for real-time monitoring.

/dev-review
/dev-review Focus on error handling and edge cases

/dev-status — Status dashboard

Overview of extension state: loaded config, managed sessions, learnings count, staleness status.

/dev-attach <id> — Attach to session

Open a managed tmux session in a new terminal window.

/dev-sessions — List sessions

List all managed tmux sessions.

/dev-cleanup — Clean up sessions

Stop all managed tmux sessions.

/dev-prompt-reset — Reset prompt sections

Flush all sticky context-triggered prompt section activations. Useful when the system prompt has accumulated sections that are no longer relevant and pi_dev_prompt_dismiss isn't enough.

Configuration

Configuration is stored at ~/.pi/developer-mode.json and is created automatically with defaults on first run.

{
  "terminal": "auto",
  "tmux": {
    "socketPrefix": "/tmp/pi-dev",
    "embeddedConfig": true,
    "defaultPiArgs": "--no-session"
  },
  "spawn": {
    "defaultArgs": "--mode json --print --no-session --no-extensions --no-skills",
    "timeout": 60,
    "maxConcurrent": 5
  },
  "staleness": {
    "checkIntervalHours": 24
  }
}

Key	Default	Description
terminal	"auto"	Terminal emulator for pi_dev_tmux_attach and /dev-attach. "auto" detects from environment. Other values: "kitty", "alacritty", "wezterm", etc.
tmux.socketPrefix	"/tmp/pi-dev"	Socket path prefix for managed tmux sessions
tmux.embeddedConfig	true	Use embedded tmux config optimized for pi sessions
tmux.defaultPiArgs	"--no-session"	Default CLI args for pi instances spawned in tmux
spawn.defaultArgs	"--mode json --print --no-session --no-extensions --no-skills"	Default CLI args for pi_dev_spawn subprocesses
spawn.timeout	60	Default subprocess timeout in seconds
spawn.maxConcurrent	5	Maximum concurrent subprocesses
staleness.checkIntervalHours	24	How often to check if the docs corpus is stale

Migration

If you were previously using any of these extensions, developer-mode replaces them:

• dump-ctx — use pi_dev_debug check="context" instead
• ext-dev-guard — conflict detection is now built-in and automatic
• pi-docs — use pi_dev_search, pi_dev_get, and pi_dev_examples instead

License

MIT — see LICENSE