@pikaa-ai/pikaa 0.2.5 → 0.3.0

package/skills/pi-agent/references/sdk.md

@@ -0,0 +1,151 @@
+# SDK
+
+Source: https://pi.dev/docs/latest/sdk
+
+The SDK ships in the main package:
+
+```bash
+npm install @earendil-works/pi-coding-agent
+```
+
+Use it to embed Pi, build custom UIs, automate workflows, spawn sub-agents, test behavior, or customize tools/resources in process.
+
+## Quick Start
+
+```ts
+import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
+
+const modelRuntime = await ModelRuntime.create();
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  modelRuntime,
+});
+
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await session.prompt("What files are in the current directory?");
+```
+
+`createAgentSession()` returns `{ session, extensionsResult, modelFallbackMessage? }` and uses `DefaultResourceLoader` when no `resourceLoader` is passed.
+
+## `AgentSession`
+
+Methods: `prompt(text, options?)`, `steer(text)`, `followUp(text)`, `subscribe(listener)` (returns unsubscribe), `setModel`, `setThinkingLevel`, `cycleModel`, `cycleThinkingLevel`, `navigateTree(targetId, { summarize, customInstructions, replaceInstructions, label })`, `compact(customInstructions?)`, `abortCompaction()`, `abort()`, `dispose()`.
+
+State: `sessionFile`, `sessionId`, `agent`, `model`, `thinkingLevel`, `messages`, `isStreaming`.
+
+`session.agent.state` exposes `messages`, `model`, `thinkingLevel`, `systemPrompt`, `tools`, `streamingMessage`, `errorMessage`; `state.messages` and `state.tools` can be replaced (top-level array is copied) and `session.agent.waitForIdle()` waits for completion.
+
+Session replacement (new/resume/fork/clone/import) lives on `AgentSessionRuntime`, not `AgentSession`.
+
+## Runtime API
+
+```ts
+const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
+  const services = await createAgentSessionServices({ cwd });
+  return {
+    ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
+    services,
+    diagnostics: services.diagnostics,
+  };
+};
+
+const runtime = await createAgentSessionRuntime(createRuntime, {
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  sessionManager: SessionManager.create(process.cwd()),
+});
+```
+
+`AgentSessionRuntime` owns `newSession()`, `switchSession(path)`, `fork(entryId)`, clone via `fork(entryId, { position: "at" })`, and `importFromJsonl()`. `runtime.session` changes after each, so re-subscribe to events and call `runtime.session.bindExtensions(...)` again if you manage extensions manually. Creation returns `runtime.diagnostics`; failures throw.
+
+## Prompting and Queueing
+
+```ts
+interface PromptOptions {
+  expandPromptTemplates?: boolean;
+  images?: ImageContent[];
+  streamingBehavior?: "steer" | "followUp";
+  source?: InputSource;
+  preflightResult?: (success: boolean) => void;
+}
+```
+
+`preflightResult` fires once before `prompt()` resolves: `true` when accepted, queued, or handled immediately; `false` when preflight rejected before acceptance. Failures after acceptance surface through events and messages, not `preflightResult(false)`. `prompt()` resolves only after the full accepted run finishes, including retries.
+
+Extension commands execute immediately even during streaming. File-based prompt templates expand before sending or queueing. Calling `prompt()` while streaming without `streamingBehavior` throws — use `session.steer()` (delivered after the current assistant turn's tool calls) or `session.followUp()` (after all work finishes). Both expand templates but error on extension commands.
+
+## Events
+
+`message_update` (with `assistantMessageEvent` deltas such as `text_delta`, `thinking_delta`), `tool_execution_start` / `_update` / `_end`, `message_start` / `message_end`, `agent_start` / `agent_end`, `turn_start` / `turn_end`, `queue_update`, `compaction_start` / `compaction_end`, `auto_retry_start` / `auto_retry_end`, `summarization_retry_scheduled` / `summarization_retry_attempt_start` / `summarization_retry_finished`.
+
+## Models and Auth
+
+`ModelRuntime` replaces the older `AuthStorage` + `ModelRegistry` pair (a synchronous `ModelRegistry` facade remains exported for extension compatibility).
+
+```ts
+const modelRuntime = await ModelRuntime.create({ authPath, modelsPath, credentials });
+modelRuntime.getModel(provider, id);        // built-ins + models.json, no auth check
+await modelRuntime.getAvailable();          // only models with valid auth
+await modelRuntime.checkAuth(providerId);
+modelRuntime.getProviders();                // provider.auth methods and status
+await modelRuntime.setRuntimeApiKey(provider, key); // not persisted
+```
+
+Credential priority: runtime overrides → `auth.json` → environment variables → custom fallback from `models.json`. `getModel(provider, id)` from `@earendil-works/pi-ai` looks up built-ins only. Inject any pi-ai `CredentialStore` (for example `InMemoryCredentialStore`) via `credentials`.
+
+### Catalog Refresh and Deadlines
+
+`create()` restores cached catalogs but does not refresh them from `pi.dev` by default. Opt in with `ModelRuntime.create({ allowModelNetwork: true, modelRefreshTimeoutMs: 15_000 })`. Remote catalogs persist to `~/.pi/agent/models-store.json` (override with `modelsStorePath`, or inject `modelsStore`); refreshes are throttled to once per provider every four hours unless forced, and `PI_OFFLINE` disables model network access entirely.
+
+Public model/auth operations and `ModelRuntime.create({ signal })` accept optional abort signals and are unbounded when omitted — SDK applications own deadline policy:
+
+```ts
+const result = await modelRuntime.refresh({ providers: ["anthropic"], signal: AbortSignal.timeout(15_000) });
+if (result.aborted) console.warn("Catalog refresh timed out; using cached models");
+for (const [providerId, error] of result.errors) console.warn(providerId, error);
+```
+
+Force an immediate refresh with `await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. Each `refresh()` starts a new provider generation, so it does not queue behind a stalled refresh and stale generations cannot publish afterward. A failed or timed-out refresh never undoes a successful credential operation.
+
+`login()`, `logout()`, `setRuntimeApiKey()`, and `removeRuntimeApiKey()` are async and resolve once the affected provider's cached/built-in catalog, composition, and availability snapshot are locally consistent; they do not wait for remote freshness. If credentials committed but local synchronization failed, they reject with the exported `CredentialSynchronizationError` — inspect `providerId`, `operation`, `credential`, and `cause` rather than blindly retrying the credential mutation.
+
+To match CLI parsing, use `resolveCliModel({ cliModel, modelRuntime })` (uses all registered models so `--api-key` first-run flows resolve before stored auth exists) and `resolveModelScopeWithDiagnostics(patterns, modelRuntime)` (matches `--models`/`enabledModels` semantics and returns warnings instead of printing).
+
+Session options also accept `model`, `thinkingLevel` (`off`…`max`), and `scopedModels: [{ model, thinkingLevel }]` for Ctrl+P cycling. With no model: restore from session, then settings default, then first available.
+
+## Tools
+
+Built-ins: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`. Defaults: `read`, `bash`, `edit`, `write`. `tools` allowlists, `excludeTools` disables specific names after the allowlist, `noTools: "all"` disables everything, `noTools: "builtin"` keeps extension/custom tools. The `edit` tool returns `details.diff` for the TUI and `details.patch` as a standard unified patch for SDK consumers.
+
+Define custom tools with `defineTool()` and pass them as `customTools`; include their names in `tools` if you use an allowlist. Tool factories are exported too: `createCodingTools`, `createReadOnlyTools`, `createReadTool`, `createBashTool`, `createEditTool`, `createWriteTool`, `createGrepTool`, `createFindTool`, `createLsTool`.
+
+Passing a custom `cwd` makes `createAgentSession()` build the selected built-in tools for that directory.
+
+## Resource Loading
+
+`DefaultResourceLoader` discovers extensions, skills, prompts, themes, and context files. Options: `cwd`, `agentDir`, `additionalExtensionPaths`, `extensionFactories` (bare functions or `InlineExtension { name, factory }` so the startup list shows `<inline:my-provider>` instead of `<inline:1>`), `settingsManager`, `systemPromptOverride`, `skillsOverride`, `promptsOverride`, `agentsFilesOverride`, `eventBus` (from `createEventBus()`). Call `await loader.reload()`, then read `getExtensions()`, `getSkills()`, `getPrompts()`, `getThemes()`, `getAgentsFiles().agentsFiles`.
+
+`cwd` drives project discovery (`.pi/extensions`, `.pi/skills`, `.agents/skills` up to the git root, `.pi/prompts`, `AGENTS.md` walk-up, session naming); `agentDir` drives global resources (`extensions/`, `skills/`, `~/.agents/skills/`, `prompts/`, `AGENTS.md`, `settings.json`, `models.json`, `auth.json`, `sessions/`). With a custom `ResourceLoader`, `cwd`/`agentDir` still influence session naming and tool path resolution but no longer control discovery.
+
+## Sessions and Settings
+
+`SessionManager.inMemory(cwd?)`, `create(cwd)`, `continueRecent(cwd)`, `open(path)`, `list(cwd)`, `listAll(cwd)`. Tree API: `getEntries`, `getTree`, `getPath`, `getLeafEntry`, `getEntry`, `getChildren`, `getLabel`, `appendLabelChange`, `branch`, `branchWithSummary`, `createBranchedSession`. Full API in `references/session-format.md`.
+
+`SettingsManager.create(cwd?, agentDir?)` merges global plus project settings; `SettingsManager.inMemory(settings?)` avoids file I/O for tests. `applyOverrides({ compaction, retry, ... })` layers overrides. Getters/setters are synchronous for in-memory state and enqueue writes asynchronously — call `await flush()` for a durability boundary and `drainErrors()` to report write errors yourself (the manager never prints them).
+
+## Run Modes
+
+`InteractiveMode` (full TUI), `runPrintMode(runtime, { mode: "text", initialMessage, initialImages, messages })`, `runRpcMode(runtime)`. All take an `AgentSessionRuntime`. `InteractiveMode` options include `migratedProviders`, `modelFallbackMessage`, `initialMessage`, `initialImages`, `initialMessages`.
+
+## SDK vs RPC
+
+Prefer the SDK for type safety, same-process integration, direct state access, or programmatic tools/extensions. Prefer RPC for other languages, process isolation, or language-agnostic clients.
+
+## Important Exports
+
+`createAgentSession`, `createAgentSessionRuntime`, `AgentSessionRuntime`, `createAgentSessionServices`, `createAgentSessionFromServices`, `ModelRuntime`, `ModelRegistry`, `CredentialSynchronizationError`, `resolveCliModel`, `resolveModelScopeWithDiagnostics`, `DefaultResourceLoader`, `ResourceLoader` type, `createEventBus`, `CONFIG_DIR_NAME`, `defineTool`, `getAgentDir`, `getPackageDir`, `getReadmePath`, `getDocsPath`, `getExamplesPath`, `SessionManager`, `SettingsManager`, the tool factories above, `InteractiveMode`, `runPrintMode`, `runRpcMode`, and types for options, results, extensions (`ExtensionAPI`, `ExtensionFactory`, `InlineExtension`), tools, skills, and prompt templates.

package/skills/pi-agent/references/security.md

@@ -0,0 +1,52 @@
+# Security
+
+Source: https://pi.dev/docs/latest/security
+
+Pi is a local coding agent. It runs with the permissions of the user account that starts it and treats files writable by that user as inside the same local trust boundary.
+
+## Project Trust
+
+Project trust controls whether Pi loads project-local settings, resources, packages, and extensions. It is not a sandbox and does not restrict what the model can ask tools to do once you are working in a directory.
+
+Pi considers a project to require trust when it finds any of these from the current working directory:
+
+- `.pi/settings.json`
+- `.pi/extensions`, `.pi/skills`, `.pi/prompts`, or `.pi/themes`
+- `.pi/SYSTEM.md` or `.pi/APPEND_SYSTEM.md`
+- project `.agents/skills` in the current directory or an ancestor
+
+A bare `.pi` directory does not count.
+
+When an interactive session starts in such a project with no saved decision for the current or a parent directory, Pi follows `defaultProjectTrust` (default `"ask"`). Saved decisions are stored by canonical directory in `~/.pi/agent/trust.json`, and the closest saved decision on the current or parent path applies before the global default.
+
+Trusting a project allows Pi to load `.pi/settings.json`, `.pi` resources (extensions, skills, prompt templates, themes, system prompt files), install missing project packages configured through project settings, and execute project-local and project package-managed extensions.
+
+Declining skips protected resources. Context files — `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md` — load regardless of trust unless context loading is disabled. Before trust resolves, Pi loads only context files, user/global extensions, and CLI `-e` extensions — those can handle the `project_trust` event, and the first extension returning a yes/no decision owns it.
+
+Non-interactive modes (`-p`, `--mode json`, `--mode rpc`) never prompt. Without an applicable saved decision, `"ask"` and `"never"` ignore trust-gated resources while `"always"` trusts them. `--approve`/`-a` and `--no-approve`/`-na` override for one run.
+
+## No Built-in Sandbox
+
+Built-in tools read, write, edit, and run shell commands with the permissions of the Pi process. Extensions are TypeScript modules with the same permissions. Package installs, shell commands, language servers, and test commands behave as ordinary local processes.
+
+This is intentional: Pi is designed to operate on local source trees, invoke project toolchains, and integrate with an existing development environment. A partial in-process sandbox would be easy to mistake for a security boundary while still depending on the host shell, filesystem, package managers, credentials, and extension code. Real isolation must come from the OS or a virtualization/container boundary.
+
+Project trust is only an input-loading guard. It prevents a repository from silently changing Pi's settings or extensions before you approve it. It does not make untrusted code, prompts, or model output safe. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented.
+
+## Running Untrusted or Unmonitored Work
+
+For untrusted repositories, generated code you will not monitor closely, or unattended automation, run Pi in a contained environment — container, VM, micro-VM, remote sandbox, or policy-controlled sandbox — with only the files and credentials the task needs. Patterns are documented in `references/containerization.md`:
+
+- run the whole `pi` process inside a container/sandbox
+- run host Pi while routing built-in tool execution into a Gondolin micro-VM
+- mount only the workspace paths the agent should access
+- avoid mounting host `~/.pi/agent` unless the container should reach host sessions, settings, and credentials
+- pass the minimum required API keys or use short-lived credentials
+- restrict network access when the task does not need it
+- review diffs and outputs before copying results back to trusted systems
+
+Bind-mounting a host workspace read/write means writes from inside the container or VM still modify host files. Use read-only mounts or copy files in and out when you need stronger protection.
+
+## Reporting Security Issues
+
+Follow the repository [Security Policy](https://github.com/earendil-works/pi/blob/main/SECURITY.md); do not open a public issue. Expected local-agent behavior, the absence of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report shows a real privilege-boundary bypass or access the local user did not already have.

package/skills/pi-agent/references/session-format.md

@@ -0,0 +1,90 @@
+# Session File Format
+
+Source: https://pi.dev/docs/latest/session-format
+
+Sessions are JSONL files. Each line is a JSON object with a `type`. Entries form a tree through `id` / `parentId`, enabling in-place branching without new files.
+
+## Location
+
+```text
+~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
+```
+
+`<path>` is the working directory with `/` replaced by `-`. Delete sessions by removing the `.jsonl` file, or from `/resume` with Ctrl+D (Pi uses the `trash` CLI when available).
+
+## Versions
+
+- v1: linear entry sequence (legacy, auto-migrated on load)
+- v2: tree structure with `id`/`parentId`
+- v3: renamed the `hookMessage` role to `custom` (extensions unification)
+
+Existing sessions auto-migrate to v3 when loaded.
+
+## Content Blocks
+
+`TextContent { type: "text", text }`, `ImageContent { type: "image", data (base64), mimeType }`, `ThinkingContent { type: "thinking", thinking }`, `ToolCall { type: "toolCall", id, name, arguments }`.
+
+## Message Types
+
+Base (from `pi-ai`):
+
+- `UserMessage` — `role: "user"`, `content` string or `(Text|Image)[]`, `timestamp` (Unix ms)
+- `AssistantMessage` — `content: (Text|Thinking|ToolCall)[]`, `api`, `provider`, `model`, `usage`, `stopReason` ∈ `stop`/`length`/`toolUse`/`error`/`aborted`, optional `errorMessage`, `timestamp`
+- `ToolResultMessage` — `toolCallId`, `toolName`, `content: (Text|Image)[]`, optional `details`, optional `usage` (nested LLM work performed by the tool), `isError`, `timestamp`
+- `Usage` — `input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, and `cost` with the same four fields plus `total`
+
+The exported pi-ai `StopReason` type also includes `"pending"`, but that value is reserved for partial messages in streaming events. Terminal `done`/`error` messages replace it with a completion reason before Pi persists the assistant message, so `"pending"` should never appear in session JSONL.
+
+Extended (from `pi-coding-agent`):
+
+- `BashExecutionMessage` — `command`, `output`, `exitCode`, `cancelled`, `truncated`, optional `fullOutputPath`, optional `excludeFromContext` (true for `!!`)
+- `CustomMessage` — `customType`, `content`, `display`, optional `details`
+- `BranchSummaryMessage` — `summary`, `fromId`
+- `CompactionSummaryMessage` — `summary`, `tokensBefore`
+
+`AgentMessage` is the union of all seven.
+
+## Entry Types
+
+All entries except the header extend `SessionEntryBase { type, id (8-char hex), parentId (null for the first entry), timestamp (ISO string) }`.
+
+- `session` — header, first line, metadata only (no `id`/`parentId`): `version`, `id`, `timestamp`, `cwd`, plus `parentSession` for sessions created via `/fork`, `/clone`, or `newSession({ parentSession })`
+- `message` — wraps an `AgentMessage` in `message`
+- `model_change` — `provider`, `modelId`
+- `thinking_level_change` — `thinkingLevel`
+- `compaction` — `summary`, `tokensBefore`, plus optional `usage`, `details`, `fromHook`, `firstKeptEntryId` (old format), and `retainedTail`
+- `branch_summary` — `summary`, `fromId`, plus optional `usage`, `details`, `fromHook`
+- `custom` — `customType`, `data`; extension state, **not** in LLM context. Renderable in the transcript via `pi.registerEntryRenderer(customType, renderer)`
+- `custom_message` — `customType`, `content`, `display`, optional `details`; extension-injected and **in** LLM context
+- `label` — `targetId`, `label` (set `label` to `undefined` to clear)
+- `session_info` — `name`; set via `/name`, `--name`/`-n`, or `pi.setSessionName()`. Shown in `/resume` instead of the first message
+
+`retainedTail` is a materialized `AgentMessage[]` kept after compaction. Newer harness-generated compactions include it so context rebuilds from that checkpoint without walking entries before the compaction. It is optional only for backward compatibility with sessions that store only `firstKeptEntryId`.
+
+## Context Building
+
+`buildContextEntries()` walks from the current leaf to the root and produces the active entry list honoring compaction:
+
+1. Collect all entries on the path.
+2. If a `CompactionEntry` is on the path: include the compaction entry first; if `retainedTail` is present it acts as a self-contained checkpoint and entries after the compaction are included; otherwise include entries from `firstKeptEntryId` to the compaction, then entries after it.
+3. Preserve non-message entries in the selected range so interactive mode can render them.
+
+`buildSessionContext()` builds the LLM message list on top of that: it extracts the current model and thinking level from the full path, then converts entries — `message` → stored `AgentMessage`, `compaction` → `compactionSummary` plus `retainedTail` when present, `branch_summary` → `branchSummary`, `custom_message` → `CustomMessage`, `custom` → no context message.
+
+## SessionManager API
+
+Static creation: `create(cwd, sessionDir?)`, `open(path, sessionDir?)`, `continueRecent(cwd, sessionDir?)`, `inMemory(cwd?)`, `forkFrom(sourcePath, targetCwd, sessionDir?)`.
+
+Static listing: `list(cwd, sessionDir?, onProgress?)`, `listAll(onProgress?)`.
+
+Session management: `newSession({ parentSession? })`, `setSessionFile(path)`, `createBranchedSession(leafId)`.
+
+Appending (each returns an entry ID): `appendMessage`, `appendThinkingLevelChange`, `appendModelChange`, `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)`, `appendCustomEntry(customType, data?)`, `appendSessionInfo(name)`, `appendCustomMessageEntry(customType, content, display, details?)`, `appendLabelChange(targetId, label)`.
+
+Tree navigation: `getLeafId`, `getLeafEntry`, `getEntry`, `getBranch(fromId?)`, `getTree`, `getChildren`, `getLabel`, `branch(entryId)`, `resetLeaf()`, `branchWithSummary(entryId, summary, details?, fromHook?)`.
+
+Context and info: `buildContextEntries`, `buildSessionContext`, `getEntries`, `getHeader`, `getSessionName`, `getCwd`, `getSessionDir`, `getSessionId`, `getSessionFile` (undefined in memory), `isPersisted`.
+
+## Parsing
+
+Read the file line by line and switch on `entry.type`; treat `entry.version ?? 1` on the header, and ignore unknown types for forward compatibility. For TypeScript definitions inspect `node_modules/@earendil-works/pi-coding-agent/dist/` and `node_modules/@earendil-works/pi-ai/dist/`.

package/skills/pi-agent/references/sessions.md

@@ -0,0 +1,56 @@
+# Sessions
+
+Source: https://pi.dev/docs/latest/sessions
+
+Pi auto-saves conversations to `~/.pi/agent/sessions/`, organized by working directory. Each session is a JSONL tree.
+
+## Session Commands
+
+```bash
+pi -c                  # continue most recent
+pi -r                  # browse and select
+pi --no-session        # ephemeral, do not save
+pi --name "my task"    # display name at startup
+pi --session <path|id> # specific file or partial session ID
+pi --fork <path|id>    # fork into a new session file
+```
+
+Interactive: `/resume`, `/new`, `/name <name>`, `/session` (file, ID, message count, tokens, cost), `/tree`, `/fork`, `/clone`, `/compact [prompt]`, `/export [file]`, `/share`.
+
+## Resuming and Deleting
+
+`/resume` (and `pi -r`) opens a picker for the current project. Search by typing; Ctrl+P toggles path display, Ctrl+S cycles sort mode, Ctrl+N filters to named sessions, Ctrl+R renames, Ctrl+D deletes with confirmation. Pi uses the `trash` CLI when available instead of permanently removing files.
+
+## Branching with `/tree`
+
+Sessions are trees: every entry has `id` and `parentId`, and the current position is the active leaf. `/tree` jumps to any previous point and continues from there without creating a new file.
+
+| Key | Action |
+|---|---|
+| ↑/↓ | Navigate visible entries |
+| ←/→ | Page up/down |
+| Ctrl+←/→ or Alt+←/→ | Fold/unfold or jump between branch segments |
+| Shift+L | Set or clear a label on the selected entry |
+| Shift+T | Toggle label timestamps |
+| Enter | Select entry |
+| Escape / Ctrl+C | Cancel |
+| Ctrl+O | Cycle filter mode |
+
+Filter modes: default, no-tools, user-only, labeled-only, all. Set the default with `treeFilterMode`.
+
+### Selection Behavior
+
+Selecting a **user or custom** message moves the leaf to that message's parent, puts the message text in the editor, and lets you edit and resubmit — creating a new branch. Selecting an **assistant, tool, compaction, or other non-user** entry moves the leaf there with an empty editor so you continue from that point. Selecting the root user message resets the leaf to an empty conversation with the original prompt in the editor.
+
+## Tree vs Fork vs Clone
+
+| | `/tree` | `/fork` | `/clone` |
+|---|---|---|---|
+| Output | Same session file | New session file | New session file |
+| View | Full tree | User-message selector | Current active branch |
+| Typical use | Explore alternatives in place | Start a new session from an earlier prompt | Duplicate current work before continuing |
+| Summary | Optional branch summary | None | None |
+
+## Branch Summaries
+
+When `/tree` switches away from one branch, Pi can summarize the abandoned branch and attach the summary at the new position, preserving context without replaying the branch. When prompted, choose no summary, the default prompt, or custom focus instructions. Internals and extension hooks: `references/compaction.md`. File format and `SessionManager` API: `references/session-format.md`.

package/skills/pi-agent/references/settings.md

@@ -0,0 +1,102 @@
+# Settings
+
+Source: https://pi.dev/docs/latest/settings
+
+Pi uses JSON settings files. Project settings override global settings; nested objects merge key by key. Edit directly or use `/settings` for common options.
+
+| Location | Scope |
+|---|---|
+| `~/.pi/agent/settings.json` | Global |
+| `.pi/settings.json` | Project |
+
+Resource paths in the global file resolve relative to `~/.pi/agent`; in the project file relative to `.pi`. Absolute paths and `~` work.
+
+## Project Trust
+
+Interactive startup asks before trusting a project folder that has project-local settings, resources, or project `.agents/skills` and no saved decision for that folder or a parent in `~/.pi/agent/trust.json`. Non-interactive modes never prompt and use `defaultProjectTrust` (`"ask"` default, `"never"`, `"always"`); `--approve`/`-a` and `--no-approve`/`-na` override for one run. `/trust` saves a decision (including for the immediate parent folder) but does not reload the current session. `pi config` and package commands follow the same flow; `pi update` never prompts.
+
+## Model and Thinking
+
+| Setting | Default | Notes |
+|---|---|---|
+| `defaultProvider` | – | Provider id |
+| `defaultModel` | – | Model id |
+| `defaultThinkingLevel` | – | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `hideThinkingBlock` | `false` | Hide thinking blocks in output |
+| `showCacheMissNotices` | `false` | Transcript notices for significant prompt-cache misses |
+| `thinkingBudgets` | – | Custom token budgets per thinking level |
+
+## UI and Display
+
+`theme` (`"dark"`), `externalEditor` (Ctrl+G command; takes precedence over `$VISUAL`/`$EDITOR` — use `"code --wait"` for VS Code), `quietStartup` (`false`), `defaultProjectTrust` (`"ask"`, global only), `collapseChangelog` (`false`), `enableInstallTelemetry` (`true`), `enableAnalytics` (`false`, only asked during experimental first-time setup with `PI_EXPERIMENTAL=1`), `trackingId`, `doubleEscapeAction` (`"tree"` | `"fork"` | `"none"`), `treeFilterMode` (`"default"` | `"no-tools"` | `"user-only"` | `"labeled-only"` | `"all"`), `editorPaddingX` (`0`, range 0–3), `outputPad` (`1`, 0 or 1), `autocompleteMaxVisible` (`5`, range 3–20), `showHardwareCursor` (`false`).
+
+Fullscreen TUI: `tuiMode` (`"regular"` default, or experimental `"fullscreen"`; `/settings` changes apply immediately and `--tui-mode` overrides at startup), `fullscreenExitOutput` (`"transcript"` prints the final transcript plus resume hint, `"resume-hint"` restores the previous screen and prints only the hint), `fullscreenScrollbar` (`"auto"` shows it while scrolling, `"always"` reserves the rightmost column, `"hidden"`). The last two have no effect in regular mode.
+
+## Network, Warnings, Markdown
+
+`httpProxy` (applied as `HTTP_PROXY`/`HTTPS_PROXY`, global only). `warnings.anthropicExtraUsage` (`true`) warns when Anthropic subscription auth may use paid extra usage. `markdown.codeBlockIndent` (`"  "`), `markdown.mermaid` (`"streaming"`, or `"final"` / `"off"`).
+
+## Compaction and Branch Summary
+
+`compaction.enabled` (`true`), `compaction.reserveTokens` (`16384`), `compaction.keepRecentTokens` (`20000`). `branchSummary.reserveTokens` (`16384`), `branchSummary.skipPrompt` (`false`, defaults to no summary).
+
+## Retry
+
+`retry.enabled` (`true`), `retry.maxRetries` (`3`), `retry.baseDelayMs` (`2000`, so 2s/4s/8s), `retry.provider.timeoutMs` (SDK default), `retry.provider.maxRetries` (`0`), `retry.provider.maxRetryDelayMs` (`60000`; `0` disables the limit).
+
+Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explicitly needed — above `0`, SDK retries can swallow out-of-usage-limit errors before Pi sees them and block the agent until quota resets. When a provider requests a delay longer than `maxRetryDelayMs`, the request fails immediately with an informative error instead of waiting silently.
+
+## Message Delivery
+
+`steeringMode` / `followUpMode` (`"one-at-a-time"` or `"all"`), `transport` (`"auto"`, `"sse"`, `"websocket"`, `"websocket-cached"`), `httpIdleTimeoutMs` (`300000`, `0` disables), `websocketConnectTimeoutMs` (`15000`, `0` disables).
+
+## Terminal and Images
+
+`terminal.showImages` (`true`), `terminal.imageWidthCells` (`60`), `terminal.clearOnShrink` (`false`), `images.autoResize` (`true`, 2000×2000 max; applies to `@file` attachments, `read`, and images returned by tools), `images.blockImages` (`false`).
+
+## Tools
+
+`defaultTools` is a string array of built-in tools enabled at startup; omitting it uses Pi's standard defaults. Extension and SDK custom tools stay enabled, and an empty array starts with no built-ins while preserving them. `--tools` replaces this with a strict allowlist for all tools, `--no-tools` disables everything, `--no-builtin-tools` disables the built-in defaults, and `--exclude-tools` filters the result. A project `defaultTools` array replaces the global array.
+
+## Shell
+
+`shellPath` (supports leading `~`; Windows paths in JSON need forward slashes or escaped backslashes, e.g. `"C:/Program Files/Git/bin/bash.exe"`), `shellCommandPrefix` (prefix for every bash command), `npmCommand` (argv array, e.g. `["mise", "exec", "node@20", "--", "npm"]`). `npmCommand` covers all npm package-manager operations; user npm packages install under `~/.pi/agent/npm/`, project ones under `.pi/npm/`. When `npmCommand` is configured, git package dependency installs use plain `install` for wrapper compatibility.
+
+## Sessions and Model Cycling
+
+`sessionDir` (absolute, relative, or `~`); precedence is `--session-dir`, then `PI_CODING_AGENT_SESSION_DIR`, then this setting. `enabledModels` is an array of patterns for Ctrl+P cycling, same format as `--models`.
+
+## Resources
+
+`packages` (`[]`), `extensions` (`[]`), `skills` (`[]`), `prompts` (`[]`), `themes` (`[]`), `enableSkillCommands` (`true`, registers `/skill:name`).
+
+Arrays support glob patterns, `!pattern` to exclude, `+path` to force-include an exact path, and `-path` to force-exclude. `packages` accepts strings or objects that filter which resource types load:
+
+```json
+{
+  "packages": [
+    "pi-skills",
+    { "source": "npm:my-package", "skills": ["brave-search"], "extensions": [] }
+  ]
+}
+```
+
+## Telemetry and Update Checks
+
+`enableInstallTelemetry` only controls the anonymous install/update ping to `https://pi.dev/api/report-install`. Opting out does not disable update checks, which fetch `https://pi.dev/api/latest-version`. `PI_SKIP_VERSION_CHECK=1` disables the version check; `--offline` or `PI_OFFLINE=1` disables all startup network operations including package update checks and telemetry.
+
+## Example
+
+```json
+{
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-20250514",
+  "defaultThinkingLevel": "medium",
+  "theme": "dark",
+  "compaction": { "enabled": true, "reserveTokens": 16384, "keepRecentTokens": 20000 },
+  "retry": { "enabled": true, "maxRetries": 3 },
+  "enabledModels": ["claude-*", "gpt-4o"],
+  "warnings": { "anthropicExtraUsage": true },
+  "packages": ["pi-skills"]
+}
+```

package/skills/pi-agent/references/shell-aliases.md

@@ -0,0 +1,15 @@
+# Shell Aliases
+
+Source: https://pi.dev/docs/latest/shell-aliases
+
+Pi runs bash in non-interactive mode (`bash -c`), which does not expand aliases by default.
+
+To enable your shell aliases, set `shellCommandPrefix` in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
+}
+```
+
+The value is a JSON string: `\n` is an escaped newline inside the prefix and the inner double quotes are backslash-escaped. Adjust the path (`~/.zshrc`, `~/.bashrc`, …) to match your shell config. The prefix is prepended to every bash command Pi runs.

package/skills/pi-agent/references/skills.md

@@ -0,0 +1,83 @@
+# Skills
+
+Source: https://pi.dev/docs/latest/skills
+
+Pi implements the [Agent Skills standard](https://agentskills.io/specification). Skills are self-contained capability packages loaded on demand, providing workflows, setup instructions, helper scripts, and reference documentation. Pi warns about most spec violations but stays lenient — notably it allows a skill name that differs from its parent directory, because the standard's matching rule is awkward for skill directories shared across harnesses.
+
+## Locations
+
+Global:
+
+- `~/.pi/agent/skills/`
+- `~/.agents/skills/`
+
+Project, only after project trust:
+
+- `.pi/skills/`
+- `.agents/skills/` in cwd and ancestors, up to the git repo root (or filesystem root outside a repo)
+
+Also: packages (`skills/` directories or `pi.skills` entries in `package.json`), the `skills` settings array, and CLI `--skill <path>` (repeatable, additive even with `--no-skills`).
+
+Discovery rules:
+
+- In `~/.pi/agent/skills/` and `.pi/skills/`, direct root `.md` files are discovered as individual skills.
+- In all locations, directories containing `SKILL.md` are discovered recursively.
+- In `~/.agents/skills/` and project `.agents/skills/`, root `.md` files are ignored.
+
+To reuse skills from other harnesses, add their directories to settings:
+
+```json
+{ "skills": ["~/.claude/skills", "~/.codex/skills"] }
+```
+
+## How Skills Work
+
+At startup Pi scans skill locations and extracts names and descriptions. The system prompt includes available skills in XML format per the specification. When a task matches, the agent uses `read` to load the full `SKILL.md` (models do not always do this — prompt explicitly or force with `/skill:name`) and follows the instructions using relative paths. Only descriptions stay in context; full instructions load on demand.
+
+## Skill Commands
+
+Skills register as `/skill:name`; arguments after the command are appended as `User: <args>`. Toggle via `/settings` or `"enableSkillCommands": true`.
+
+```bash
+/skill:brave-search
+/skill:pdf-tools extract
+```
+
+## Structure
+
+```text
+my-skill/
+  SKILL.md          # required: frontmatter + instructions
+  scripts/process.sh
+  references/api-reference.md
+  assets/template.json
+```
+
+Use relative paths from the skill directory.
+
+## Frontmatter
+
+| Field | Required | Constraints |
+|---|---|---|
+| `name` | Yes | Max 64 chars, lowercase a–z, 0–9, hyphens. Pi does not require it to match the parent directory. |
+| `description` | Yes | Max 1024 chars — what the skill does and when to use it. |
+| `license` | No | License name or reference to a bundled file. |
+| `compatibility` | No | Max 500 chars; environment requirements. |
+| `metadata` | No | Arbitrary key-value mapping. |
+| `allowed-tools` | No | Space-delimited pre-approved tools (experimental). |
+| `disable-model-invocation` | No | `true` hides the skill from the system prompt; users must call `/skill:name`. |
+
+Name rules: 1–64 characters, lowercase letters/numbers/hyphens, no leading or trailing hyphen, no consecutive hyphens. Valid: `pdf-processing`. Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`.
+
+## Validation
+
+Most violations warn but still load: over-length or invalid names, leading/trailing/consecutive hyphens, description over 1024 chars. Unknown frontmatter fields are ignored. **Exception:** a missing description prevents loading. Name collisions across locations warn and keep the first skill found.
+
+## Security
+
+Skills can instruct the model to perform any action and may include executable code the model invokes. Review skill content before use.
+
+## Skill Repositories
+
+- [Anthropic Skills](https://github.com/anthropics/skills) — document processing, web development
+- [Pi Skills](https://github.com/badlogic/pi-skills) — web search, browser automation, Google APIs, transcription

package/skills/pi-agent/references/terminal-setup.md

@@ -0,0 +1,87 @@
+# Terminal Setup
+
+Source: https://pi.dev/docs/latest/terminal-setup
+
+Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier detection. Most modern terminals support it; some need configuration.
+
+## Works Out of the Box
+
+Kitty and iTerm2 (regular TUI mode). Apple Terminal enables enhanced key reporting when available; if it still sends plain Return for `Shift+Enter`, Pi uses a local macOS modifier fallback — which only works when Pi runs on the same Mac, not over SSH. VS Code 1.109.5+ also works by default.
+
+### iTerm2 in fullscreen TUI mode
+
+Pi owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling its native scrollback. With iTerm2's default fast-trackpad behavior those reports can lose most of an accelerated wheel delta. If fast gestures move only ~one line at a time, open **iTerm2 → Settings → Advanced**, find **Trackpad scrolls fast?** and set it to **No**. This is an iTerm2-wide workaround (tracked in iTerm2 issue 9619). Inline images also render as text placeholders in fullscreen mode because iTerm2's inline-image protocol cannot delete or crop placements during application-owned scrolling.
+
+## Ghostty
+
+Config at `~/Library/Application Support/com.mitchellh.ghostty/config` (macOS) or `~/.config/ghostty/config` (Linux):
+
+```text
+keybind = alt+backspace=text:\x1b\x7f
+```
+
+Older Claude Code versions may have added `keybind = shift+enter=text:\n`. That sends a raw linefeed, which inside Pi is indistinguishable from `Ctrl+J`, so tmux and Pi no longer see a real `shift+enter` event. Remove it unless you still need it for Claude Code in tmux. Pi binds `Ctrl+J` as a default newline alias, so `Shift+Enter` keeps working through that remap without extra Pi configuration.
+
+In fullscreen TUI mode links stay clickable, but Ghostty hides its hover underline and lower-left URL preview while Pi captures mouse input. Hold `Shift+Command` (macOS) or `Shift+Ctrl` (Linux) for Ghostty's native link handling.
+
+## WezTerm
+
+Usually works via xterm `modifyOtherKeys`. To force the Kitty protocol, in `~/.wezterm.lua`:
+
+```lua
+local wezterm = require 'wezterm'
+local config = wezterm.config_builder()
+config.enable_kitty_keyboard = true
+return config
+```
+
+On macOS `Option+Enter` is bound to fullscreen; to use it for follow-up queueing add to `config.keys`:
+
+```lua
+{ key = 'Enter', mods = 'ALT', action = wezterm.action.SendString('\x1b[13;3u') }
+```
+
+On WSL, WezTerm may need a visible hardware cursor for IME candidate positioning — set `PI_HARDWARE_CURSOR=1` or `showHardwareCursor: true`.
+
+## Alacritty
+
+Usually works for `Shift+Enter`. On macOS `Option+Enter` may arrive as plain `Enter`; add to `~/.config/alacritty/alacritty.toml` and restart:
+
+```toml
+[[keyboard.bindings]]
+key = "Enter"
+mods = "Alt"
+chars = "\u001b[13;3u"
+```
+
+## VS Code Integrated Terminal
+
+1.109.5+ enables the Kitty protocol by default. Older versions need an explicit `keybindings.json` entry (macOS `~/Library/Application Support/Code/User/keybindings.json`, Linux `~/.config/Code/User/keybindings.json`, Windows `%APPDATA%\Code\User\keybindings.json`):
+
+```json
+{
+  "key": "shift+enter",
+  "command": "workbench.action.terminal.sendSequence",
+  "args": { "text": "\u001b[13;2u" },
+  "when": "terminalFocus"
+}
+```
+
+## Windows Terminal
+
+Add to `settings.json` (Ctrl+Shift+, then Open JSON file) so the modified Enter keys reach Pi:
+
+```json
+{
+  "actions": [
+    { "command": { "action": "sendInput", "input": "\u001b[13;2u" }, "keys": "shift+enter" },
+    { "command": { "action": "sendInput", "input": "\u001b[13;3u" }, "keys": "alt+enter" }
+  ]
+}
+```
+
+Windows Terminal binds `Alt+Enter` to fullscreen by default, which blocks follow-up queueing; remapping it to `sendInput` forwards the real chord. Fully close and reopen Windows Terminal if the old fullscreen behavior persists.
+
+## Limited Terminals
+
+xfce4-terminal, terminator, and IntelliJ IDEA's integrated terminal cannot distinguish modified Enter keys from plain Enter, so bindings such as `submit: ["ctrl+enter"]` will not work. Prefer a terminal with Kitty keyboard support: Kitty, Ghostty, WezTerm, iTerm2, or Alacritty compiled with Kitty protocol support. In IntelliJ, set `PI_HARDWARE_CURSOR=1` if you want the hardware cursor visible (off by default for compatibility).