@aliou/pi-dev-kit 0.4.9 → 0.6.0

package/src/skills/pi-extension/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: pi-extension
+description: Create, update, and publish Pi extensions. Use when working on extensions in this repository.
+---
+
+# Pi Extension Development
+
+Guide for creating and maintaining Pi extensions. Read the relevant reference files before implementing.
+
+## Key Imports
+
+Pi injects these packages via jiti at runtime. Extensions do not need to install them — they are available as peer dependencies:
+
+- `@mariozechner/pi-coding-agent` — core types, utilities, `Type`/`Static` (re-exported from TypeBox)
+- `@mariozechner/pi-tui` — TUI components
+- `@mariozechner/pi-ai` — AI utilities (`StringEnum`, etc.)
+- `@sinclair/typebox` — schema definitions (also re-exported from `pi-coding-agent`, prefer the re-export)
+
+```typescript
+// Tool UI components (from @aliou/pi-utils-ui)
+import { ToolCallHeader, ToolBody, ToolFooter } from "@aliou/pi-utils-ui";
+
+// Core types
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+
+// Rendering utilities
+import { getMarkdownTheme, keyHint, truncateHead, formatSize } from "@mariozechner/pi-coding-agent";
+
+// TUI components
+import { Container, Markdown, Text } from "@mariozechner/pi-tui";
+```
+
+## Workflow
+
+### Creating a New Extension
+
+1. Read `references/structure.md` for the project layout and package.json template.
+2. Create the entry point (`src/index.ts`) with a default export function.
+3. Decide what the extension provides:
+   - **Tools** (LLM-callable): Read `references/tools.md`.
+   - **Commands** (user-invoked): Read `references/commands.md`.
+   - **Providers** (LLM backends): Read `references/providers.md`.
+   - **Hooks** (event handlers): Read `references/hooks.md`. Includes both `tool_call` blocking hooks and spawn hooks for transparent command rewriting via `createBashTool`.
+4. Read `references/modes.md` for mode-awareness guidelines. Every extension must handle Interactive, RPC, and Print modes.
+5. If the extension displays rich UI: Read `references/components.md` for TUI components and `references/messages.md` for message display patterns.
+6. If the extension tracks state: Read `references/state.md`.
+7. For less common APIs: Read `references/additional-apis.md`.
+8. If the extension has user-configurable settings: Use `registerSettingsCommand` from `@aliou/pi-utils-settings`. Read `references/structure.md` for settings command and auth wizard patterns.
+9. If the extension adds a tool that competes with a natural bash fallback: use `promptSnippet` and `promptGuidelines` on the tool definition for simple guidance. Use system prompt hooks only for complex cross-tool orchestration. Read the **Guidance** section in `references/additional-apis.md`.
+10. Before publishing: Read `references/publish.md` and `references/documentation.md`.
+
+### Modifying an Existing Extension
+
+1. Read the extension's `index.ts` to understand its structure.
+2. Read the relevant reference file for the area you are modifying.
+3. Check `references/modes.md` if adding any UI interaction.
+4. Run type checking after changes.
+
+## Reference Files
+
+| File | Content |
+|---|---|
+| `references/structure.md` | Project layout, package.json, tsconfig, biome.json, config.ts, entry point patterns (including acceptable exceptions), API key pattern, imports |
+| `references/tools.md` | Tool registration, execute signature, parameters, streaming, rendering, naming, renderCall/renderResult UI guidelines |
+| `references/hooks.md` | Events, blocking/cancelling, input transformation, system prompt modification, bash spawn hooks (command rewriting) |
+| `references/commands.md` | Command registration, three-tier pattern, component extraction |
+| `references/components.md` | TUI components (pi-tui + pi-coding-agent), custom(), theme styling, keyboard handling |
+| `references/providers.md` | Provider registration, model definition, compat field, API key gating |
+| `references/modes.md` | Mode behavior matrix, ctx.hasUI, dialog vs fire-and-forget, three-tier pattern |
+| `references/messages.md` | sendMessage, registerMessageRenderer, notify, when to use each |
+| `references/state.md` | appendEntry, state reconstruction, appendEntry vs sendMessage |
+| `references/additional-apis.md` | Shortcuts, flags, exec, sendUserMessage, session name, labels, model control, EventBus, theme, UI customization, system prompt guidance injection |
+| `references/publish.md` | npm publishing, changesets (manual file format + CI automation), GitHub Actions publish workflow, first-time setup, NPM_TOKEN, pre-publish checklist |
+| `references/testing.md` | Local development, type checking, manual testing, debugging |
+| `references/documentation.md` | README template, what to document, changelog |
+
+## Reference Extensions
+
+When implementing, look at these existing extensions for patterns:
+
+**Standalone repos (recommended structure):**
+- `pi-linkup` (`/Users/alioudiallo/code/src/pi.dev/pi-linkup/`): Tools wrapping a third-party API. Has tools with `promptSnippet`/`promptGuidelines`, custom rendering with `ToolCallHeader`/`ToolBody`/`ToolFooter`, output truncation with temp files, API key gating. Moved from system-prompt hooks to per-tool metadata.
+- `pi-synthetic` (`/Users/alioudiallo/code/src/pi.dev/pi-synthetic/`): Provider + tools. Has a provider with models, a command with `custom()` component, API key gating.
+- `pi-processes` (`/Users/alioudiallo/code/src/pi.dev/pi-processes/`): Multi-action tool with `promptSnippet`/`promptGuidelines` plus system prompt guidance hook for complex multi-tool orchestration, core `ProcessManager` class with unit tests, `ToolBody` with `showCollapsed` fields, conditional footers.
+- `pi-linear` (`/Users/alioudiallo/code/src/pi.dev/pi-linear/`): Multi-action tool with action modules, auth wizard using `Wizard` from `@aliou/pi-utils-settings`, settings command with `registerSettingsCommand`, config migrations, `ToolBody`/`ToolFooter` rendering, system prompt guidance for cross-tool orchestration.
+- `pi-obsidian` (`/Users/alioudiallo/code/src/pi.dev/pi-obsidian/`): Tools wrapping a CLI. Has a separate `obsidian-vault-core` package for domain logic. Uses `pi.exec()` for shell commands, `ToolCallHeader`/`ToolFooter` rendering, throws errors.
+
+## Critical Rules
+
+1. **Execute parameter order**: `(toolCallId, params, signal, onUpdate, ctx)`. Signal before onUpdate.
+2. **Always use `onUpdate?.()`**: Optional chaining. The parameter can be `undefined`.
+3. **No `.js` in imports**: Use bare module paths (`./tools/my-tool`, not `./tools/my-tool.js`).
+4. **Mode awareness**: Every `ctx.ui.custom()` call needs an RPC fallback (use `select`/`confirm`/`notify` -- they work in RPC). Do not use `done(undefined)` for normal interactive close paths when you detect fallback with `result === undefined`; use explicit sentinels (`null`, `"closed"`, boolean). Every `tool_call` hook with dialogs needs a `ctx.hasUI` check.
+5. **API key gating**: Check before registering tools that require the key. Providers handle missing keys internally via their `models()` function.
+6. **Tool naming**: Prefix with API name for third-party integrations (`linkup_web_search`). No prefix for internal tools (`get_current_time`).
+7. **Tool rendering uses `ToolCallHeader`**: First line `[Tool Name]: [Action] [Main arg] [Option args]`, long args on follow-up lines. Use display names, not raw tool IDs.
+8. **Deterministic call rendering**: Build `renderCall` with a stable extraction order (action → main arg → option args → long args), process-style. Same input should produce same header layout.
+9. **Long args placement**: Put long prompt/task/question/context strings on following lines. Keep first line scannable.
+10. **Result layout**: In `renderResult(result, options, theme)`, handle `isPartial` first with a stable tool-scoped message. Detect errors by checking for missing expected fields in `details` (framework sets `details: {}` on throw). Use `ToolBody` from `@aliou/pi-utils-ui` with `showCollapsed` fields. Use `ToolFooter` conditionally (omit when empty). Use `Container`/`Markdown` for rich content.
+11. **Typed param alias**: Define `type MyToolParams = Static<typeof parameters>` at the top of each tool file. Use it everywhere instead of repeating `Static<typeof parameters>`.
+12. **Tool metadata**: Every tool must have `label` (required). Add `promptSnippet` for system prompt tool listing. Add `promptGuidelines` for usage instructions. These replace system-prompt hooks for simple tools.
+13. **Output truncation**: For tools returning large text, use `truncateHead()` from `@mariozechner/pi-coding-agent`. Write full content to temp file. Append footer with line/byte counts and temp file path.
+14. **Core/lib pattern**: Extract domain logic into modules (`client.ts`, `manager.ts`) that don't import from Pi. Tools are thin wrappers. Core modules are unit-testable with vitest.
+15. **Humanize messages**: Show display names first, IDs in dim/parens. `"Started \"backend\" (proc_42)"` not `"Started proc_42"`.
+16. **peerDependencies**: Pi injects `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`, and `@sinclair/typebox` via jiti at runtime. Any of these that your extension imports must be listed in `peerDependencies` with `optional: true` in `peerDependenciesMeta`. Without `optional: true`, npm 7+ auto-installs peers, adding hundreds of packages on every install even though Pi already provides them. Keep them in `devDependencies` too for local type checking — `pnpm install` installs peers, so development is unaffected. Use `>=CURRENT_VERSION` range, not `*`. Prefer importing `Type`/`Static` from `@mariozechner/pi-coding-agent` rather than `@sinclair/typebox` directly.
+17. **Check existing components**: Before creating a new TUI component, check if `pi-tui` or `pi-coding-agent` already exports one that fits.
+18. **Forward abort signals**: Always pass `signal` through to `fetch()`, `pi.exec()`, and API client methods. A tool that ignores its signal prevents cancellation from reaching the underlying operation. Never prefix with `_signal` unless the tool truly has no async work to cancel.
+19. **Never use Node child_process APIs**: Do not use `child_process.exec`, `execSync`, `spawn`, `spawnSync`, `execFile`, or `execFileSync` to run binaries or shell scripts. Always use `pi.exec()`. `pi.exec` handles CWD, signal propagation, and output capture consistently. The only exception is if you need a long-lived streaming process with stdin/stdout piping that `pi.exec` cannot support — document the reason in code comments.
+20. **Never use `homedir()` for pi paths**: Use the SDK helpers from `@mariozechner/pi-coding-agent` instead. They respect the `PI_CODING_AGENT_DIR` env var which is used for testing and custom setups. Key functions: `getAgentDir()`, `getSettingsPath()`, `getSessionsDir()`, `getPromptsDir()`, `getToolsDir()`, `getCustomThemesDir()`, `getModelsPath()`, `getAuthPath()`, `getBinDir()`, `getDebugLogPath()`. All exported from the main package entry point.
+21. **Config uses the interface pattern**: `config.ts` defines two TypeScript interfaces (`RawConfig` with all fields optional, `ResolvedConfig` with all fields required) and a `ConfigLoader<Raw, Resolved>` instance. Do not use TypeBox schemas for config types. For config migrations, use `ConfigLoader` `migrations` option. For settings UI, use `registerSettingsCommand` from `@aliou/pi-utils-settings`.
+22. **Entry point deviations must be documented**: The standard entry point pattern is load config → check `enabled` → register. Deviations (no config, API-key-first ordering, no `enabled` toggle) are acceptable when justified, but must be noted in `AGENTS.md`.
+
+## Checklist
+
+Before considering an extension complete:
+
+- [ ] Entry point has correct default export signature.
+- [ ] All tools have correct execute parameter order.
+- [ ] All `onUpdate` calls use optional chaining.
+- [ ] No `.js` file extensions in imports.
+- [ ] `renderCall` uses `ToolCallHeader` with consistent first-line pattern (tool, action if any, main arg, options).
+- [ ] `renderCall` arg extraction is deterministic (action → main arg → option args → long args).
+- [ ] Long call arguments are moved to follow-up lines, not crammed into first line.
+- [ ] `renderResult` handles `isPartial` first with a stable tool-scoped message.
+- [ ] `renderResult` detects errors by checking for missing expected fields in `details` (framework sets `details: {}` on throw).
+- [ ] `renderResult` uses `ToolBody` with `showCollapsed` fields.
+- [ ] `renderResult` uses `ToolFooter` conditionally (omits when empty).
+- [ ] Every tool has `label` field.
+- [ ] Tools have `promptSnippet` and/or `promptGuidelines` when appropriate.
+- [ ] Large output tools use `truncateHead()` + temp file pattern.
+- [ ] Domain logic is extracted to testable core modules.
+- [ ] `ctx.ui.custom()` calls have RPC fallback, and interactive close/cancel paths do not rely on `done(undefined)` when fallback detection uses `result === undefined`.
+- [ ] `tool_call` hooks check `ctx.hasUI` before dialog methods.
+- [ ] Fire-and-forget methods (notify, setStatus, etc.) are used without hasUI guards.
+- [ ] If using custom message renderers: collapsed view is scannable, expanded view adds depth, and renderer has plain-text fallback when `details` is missing.
+- [ ] `signal` is forwarded to all async operations (fetch, `pi.exec`, API clients). No unused `_signal`.
+- [ ] Missing API keys produce a notification, not a crash.
+- [ ] If in a monorepo: package doesn't depend on private workspace packages (run `pnpm run check:public-deps` if available).
+- [ ] `pnpm typecheck` passes.
+- [ ] No `child_process` imports -- uses `pi.exec()` for shell commands.
+- [ ] No `homedir()` calls for pi paths -- uses SDK helpers (`getAgentDir()`, etc.).
+- [ ] README documents tools, commands, env vars.
+- [ ] `@mariozechner/pi-tui` (and any other Pi-provided package) is in `peerDependencies` with `optional: true` if imported at runtime, not just `devDependencies`.
+- [ ] `prepare` script is `"[ -d .git ] && husky || true"`, not bare `"husky"`.
+- [ ] `config.ts` uses `ConfigLoader<Raw, Resolved>` with TypeScript interfaces, not TypeBox schemas.
+- [ ] If deviating from the standard entry point pattern (load-config → check-enabled → register), the reason is documented in `AGENTS.md`.
+- [ ] Settings use `registerSettingsCommand` from `@aliou/pi-utils-settings` when the extension has user-configurable settings.

package/src/skills/pi-extension/references/additional-apis.md

@@ -0,0 +1,304 @@
+# Additional APIs
+
+These APIs are available on `ExtensionAPI` and `ExtensionContext` but are less commonly used. Each is shown with a minimal example.
+
+When you implement something using one of these APIs, update this skill reference with a fuller example based on your actual usage.
+
+## Shortcuts
+
+Register global keyboard shortcuts:
+
+```typescript
+pi.registerShortcut("ctrl+shift+p", {
+  description: "Toggle plan mode",
+  handler: async (ctx) => {
+    planModeEnabled = !planModeEnabled;
+    ctx.ui.setStatus("plan", planModeEnabled ? "Plan Mode" : "");
+  },
+});
+```
+
+Shortcuts work only in Interactive mode.
+
+## Flags
+
+Register boolean flags that persist across sessions:
+
+```typescript
+// Register
+pi.registerFlag("auto-commit", {
+  description: "Auto-commit after each turn",
+  default: false,
+});
+
+// Read (in any handler)
+const autoCommit = pi.getFlag("auto-commit");
+```
+
+Users toggle flags with `/flag auto-commit` in the input editor.
+
+## sendUserMessage
+
+Inject a user message into the conversation programmatically:
+
+```typescript
+pi.sendUserMessage("Please summarize what we just discussed");
+```
+
+This triggers a full agent turn as if the user typed the message. Useful for file watchers, timers, or other automated triggers.
+
+## Session Name
+
+Set or get a name for the current session (shown in the session selector):
+
+```typescript
+pi.setSessionName("Feature: Auth Refactor");
+const name = pi.getSessionName();
+```
+
+## Labels
+
+Set a label on a specific session entry (shown in `/tree` view):
+
+```typescript
+pi.setLabel(entryId, "checkpoint: before refactor");
+```
+
+## exec
+
+Run a shell command and get the result. This is the **only** way to run external binaries or shell scripts from an extension.
+
+```typescript
+const result = await pi.exec("git status --porcelain", { cwd: process.cwd() });
+// result: { stdout, stderr, exitCode }
+```
+
+Useful for git operations, environment checks, running CLI tools, etc.
+
+**Do not use Node `child_process` APIs** (`exec`, `execSync`, `spawn`, `spawnSync`, `execFile`, `execFileSync`). `pi.exec` handles CWD resolution, output capture, and integrates with the extension lifecycle. Using `child_process` directly bypasses these guarantees and creates inconsistent behavior across environments.
+
+The only exception is a long-lived streaming process that requires direct stdin/stdout piping — document the reason in code comments if this applies.
+
+## Active Tools
+
+Get or set which tools are currently active:
+
+```typescript
+const tools = pi.getActiveTools(); // string[]
+pi.setActiveTools(["bash", "read", "write", "my_custom_tool"]);
+```
+
+Setting active tools restricts which tools the LLM can use.
+
+## Model Control
+
+```typescript
+// Set the active model
+pi.setModel("anthropic/claude-sonnet-4-20250514");
+
+// Get/set thinking level
+const level = pi.getThinkingLevel(); // "none" | "low" | "medium" | "high"
+pi.setThinkingLevel("high");
+```
+
+## System Prompt
+
+Read or modify the system prompt (typically in `before_agent_start`):
+
+```typescript
+pi.on("before_agent_start", async (_event, ctx) => {
+  const prompt = ctx.getSystemPrompt();
+  ctx.setSystemPrompt(prompt + "\n\nExtra instructions.");
+});
+```
+
+The system prompt resets each turn, so modifications are not cumulative.
+
+### Guidance Injection Pattern
+
+Extensions that add tools or behavioral patterns the agent may not know how to use correctly should inject guidance into the system prompt. Without it, agents fall back to bash workarounds even when a better tool is available.
+
+**When to inject guidance:**
+- Your extension adds a tool that competes with a natural bash fallback (e.g. a process manager, a CI watcher, a search tool)
+- Correct usage depends on subtle conditions (alert flags, when-not-to-use, alert vs. poll)
+- You have observed agents ignoring the tool or reaching for `bash` instead
+
+**When not to:**
+- The tool description alone is self-explanatory
+- The tool has no plausible bash alternative
+
+---
+
+There are two ways to inject guidance, depending on complexity:
+
+#### Tier 1: Per-Tool Metadata (Preferred for Simple Tools)
+
+For most tools, use the SDK-level `promptSnippet` and `promptGuidelines` fields directly on the tool definition. No hook is needed.
+
+- **`promptSnippet`** — Injected into the "Available tools" system prompt section. Use for a concise (1–2 sentence) description of when to prefer this tool.
+- **`promptGuidelines`** — Appended to the "Guidelines" section. Use for a short list of usage rules.
+
+```typescript
+const myTool = {
+  name: "my_tool",
+  label: "My Tool",
+  description: "...",
+  promptSnippet: "Manage background processes without blocking the conversation.",
+  promptGuidelines: [
+    "Use this tool for long-running commands instead of bash.",
+    "After starting a process, continue other work instead of waiting.",
+  ],
+  parameters: ...,
+  execute: ...,
+};
+```
+
+This is the simplest approach and works well when guidance is specific to a single tool.
+
+#### Tier 2: System Prompt Hook (For Complex Cross-Tool Orchestration)
+
+Use the `before_agent_start` hook when:
+- Guidance involves **cross-tool workflow instructions** (e.g. "use tool A, then tool B, then tool C")
+- You need **dynamic context from config** (e.g. workspace names, team keys, feature flags)
+- The per-tool metadata fields aren't expressive enough
+
+**Structure: three files**
+
+`src/guidance.ts` — the guidance text as a named export:
+
+```typescript
+export const MY_EXTENSION_GUIDANCE = `
+## My Extension
+
+Use the \`my_tool\` tool for X. Don't use bash for X.
+
+**Use \`my_tool\` when:**
+- Situation A
+- Situation B
+
+**Use \`bash\` when:**
+- You need the result immediately to proceed (quick commands that finish in seconds)
+
+**Never do this:**
+\`\`\`bash
+workaround_command  # loses observability
+\`\`\`
+
+**Do this instead:**
+\`\`\`
+my_tool({ action: "start", ... })
+\`\`\`
+`;
+```
+
+`src/hooks/system-prompt.ts` — the hook:
+
+```typescript
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { configLoader } from "../config";
+import { MY_EXTENSION_GUIDANCE } from "../guidance";
+
+export function registerGuidance(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", async (event) => {
+    const config = configLoader.getConfig();
+    if (!config.systemPromptGuidance) return;
+
+    return {
+      systemPrompt: `${event.systemPrompt}\n${MY_EXTENSION_GUIDANCE}`,
+    };
+  });
+}
+```
+
+`src/config.ts` — add the toggle (default `true`):
+
+```typescript
+export interface MyExtensionConfig {
+  // ...
+  /** Inject tool guidance into the system prompt each turn. Default: true. */
+  systemPromptGuidance?: boolean;
+}
+```
+
+Call `registerGuidance(pi)` from your hooks setup function.
+
+---
+
+**What makes guidance effective:**
+
+- Lead with the decision rule: **when to use AND when not to use**. The when-not-to-use is as important — it gives the agent permission to keep using `bash` for quick tasks and prevents overcorrection.
+- Name anti-patterns explicitly by their exact form (`cmd &`, `nohup`, `sleep 30 &&`). Abstract descriptions ("don't use bash workarounds") are ignored.
+- Use 2–3 tight code examples. More than that dilutes attention; fewer leave the pattern underspecified.
+- Keep the guidance section header (`## My Extension`) so it reads as a named capability, not a restriction.
+- Avoid stacking emphasis markers (`NEVER`, `ALWAYS`, `IMPORTANT`). One or two land; more are ignored.
+
+**Reference implementations:**
+- `pi-linkup` — Uses per-tool `promptSnippet`/`promptGuidelines` (simple tools, no hook needed).
+- `pi-linear` — Uses `guidance.ts` + `before_agent_start` hook (cross-tool workflow instructions + dynamic workspace context).
+- `pi-processes` — Uses both: `promptSnippet`/`promptGuidelines` on tools for basic guidance, plus system prompt hook for complex multi-tool orchestration patterns.
+
+## Compaction
+
+Trigger compaction programmatically:
+
+```typescript
+await pi.compact();
+```
+
+## Shutdown
+
+Shut down pi gracefully:
+
+```typescript
+pi.shutdown();
+```
+
+## EventBus
+
+Inter-extension communication via a shared event bus:
+
+```typescript
+// Extension A: emit
+pi.events.emit("my-extension:data-ready", { items: [...] });
+
+// Extension B: listen
+pi.events.on("my-extension:data-ready", (data) => {
+  console.log("Received:", data.items.length, "items");
+});
+```
+
+Namespace event names with your extension name to avoid collisions. The event bus is supplementary -- most extensions do not need it. Use it when two extensions need to coordinate.
+
+## Theme Control
+
+```typescript
+// Get current and available themes
+const current = ctx.ui.getTheme();
+const all = ctx.ui.getAllThemes();
+
+// Set theme
+const result = ctx.ui.setTheme("catppuccin-mocha");
+// result: { success: boolean, error?: string }
+```
+
+## UI Customization
+
+```typescript
+// Replace the footer
+ctx.ui.setFooter((maxWidth, theme) => {
+  return theme.fg("muted", "Custom footer content");
+});
+
+// Replace the startup header
+ctx.ui.setHeader((maxWidth, theme) => {
+  return theme.fg("accent", "My Custom Header");
+});
+
+// Set the editor component
+ctx.ui.setEditorComponent((tui, theme, kb) => {
+  return new CustomEditor(tui, theme, kb);
+});
+
+// Prefill the editor
+ctx.ui.setEditorText("Prefilled content");
+```

package/src/skills/pi-extension/references/commands.md

@@ -0,0 +1,100 @@
+# Commands
+
+Commands are user-invoked actions triggered with `/command-name` in the input editor.
+
+## Registration
+
+```typescript
+pi.registerCommand("my-command", {
+  description: "What this command does",
+  handler: async (args, ctx) => {
+    // args: string (everything after the command name)
+    // ctx: ExtensionContext
+  },
+});
+```
+
+## Command Context
+
+The `ctx` parameter provides the same `ExtensionContext` as hooks, with access to `ctx.ui`, `ctx.hasUI`, `ctx.cwd`, etc.
+
+Commands are interactive by nature (the user typed them), so `ctx.hasUI` is usually `true`. However, commands can also be invoked programmatically (for example via RPC), so the three-tier pattern still applies.
+
+## Simple Command
+
+```typescript
+pi.registerCommand("balance", {
+  description: "Check API balance",
+  handler: async (_args, ctx) => {
+    const balance = await fetchBalance();
+    ctx.ui.notify(`Balance: $${balance.toFixed(2)}`, "info");
+  },
+});
+```
+
+## Command with Rich Display
+
+When a command needs a rich TUI display, use the three-tier pattern from `references/modes.md`:
+
+```typescript
+pi.registerCommand("quotas", {
+  description: "Show API quotas",
+  handler: async (_args, ctx) => {
+    const quotas = await fetchQuotas();
+
+    // Print mode
+    if (!ctx.hasUI) {
+      console.log(formatQuotasPlain(quotas));
+      return;
+    }
+
+    // Interactive mode: full TUI component.
+    // Use explicit sentinel value for close/cancel, not undefined.
+    const result = await ctx.ui.custom<"closed">((tui, theme, _kb, done) => {
+      return new QuotasDisplay(theme, quotas, () => done("closed"));
+    });
+
+    // RPC mode: custom() returns undefined by design.
+    if (result === undefined) {
+      ctx.ui.notify(formatQuotasPlain(quotas), "info");
+    }
+  },
+});
+```
+
+Do not use `done(undefined)` in normal interactive close paths if you rely on `result === undefined` to detect RPC fallback.
+
+## Extracting Components
+
+Keep command handlers thin. Extract the TUI component into a separate file:
+
+```
+src/
+  commands/
+    quotas.ts              # Handler + formatQuotasPlain
+  components/
+    quotas-display.ts      # QuotasDisplay component class
+```
+
+The component file should export the component class. The command file imports it and wires up the handler.
+
+## Arguments
+
+The `args` parameter is the raw string after the command name. Parse it yourself:
+
+```typescript
+handler: async (args, ctx) => {
+  const parts = args.trim().split(/\s+/);
+  const subcommand = parts[0];
+  // ...
+},
+```
+
+## Command vs Tool
+
+| Aspect | Command | Tool |
+|---|---|---|
+| Invoked by | User (typing `/name`) | LLM (during a turn) |
+| Purpose | User-facing actions, settings, displays | LLM capabilities |
+| UI access | Full (user is present) | Limited (LLM is driving) |
+| Return value | void | `AgentToolResult` (output for LLM) |