Notes on My Pi Setup
- How I use Pi
- Installed extensions
- My skills
- Controlled delegation
- Local inference: a Pi-backed HTTP API
- References
How I use Pi
I use Pi as a customizable terminal coding assistant to inspect repositories, make focused changes, and run checks. Skills capture reusable workflows; extensions add delegation, research, rewind, and persistent goals.
My installed CLI is Pi 1.5.2. In ~/.pi/agent/settings.json, my default is
openai-codex/gpt-6.1-sol with xhigh thinking, the dark theme, and hidden
thinking blocks. Hiding those blocks changes presentation, not reasoning effort.
These are configured model selections, not guarantees of provider availability.
cd /path/to/project
pi
# Inside Pi: /login, /model, /reload
Pi's core tools are read, bash, edit, and write. Project AGENTS.md
files supply repository-specific constraints. Extensions execute integrations;
skills supply task-specific instructions loaded when relevant.
Installed extensions
These packages are declared in my user settings and installed under
~/.pi/agent/npm/node_modules/. Versions below describe the inspected setup,
not permanent pins: my package declarations use unversioned npm: sources.
| Package | Installed | My use |
|---|---|---|
pi-subagents |
0.88.1 | Focused workers, independent reviewers, advisors, and scope auditing. |
pi-web-access |
0.47.0 | Web search, source checking, page/PDF extraction, repository and video research. |
pi-rewind-hook |
1.8.8 | Git-backed file checkpoints associated with session history; restore through /tree or /fork. |
pi-goal-x |
0.34.1 | Explicit persistent goals, task progress, pause/resume, and optional completion auditing. |
My extensions setting contains "-builtin:mcp": Pi's built-in MCP integration
is disabled. The capabilities below come from the installed extension docs;
they do not imply every optional feature is enabled in my settings.
pi-subagents: focused work and independent judgment
Delegation requires my request or applicable instructions, not just complexity.
subagents_enable exposes the delegation tools when needed. A foreground child
runs as a session inside the parent process; a background child uses a detached
runner. Each receives its own task, context, tools, and model selection.
I separate the implementation worker from read-only review/advice and scope
auditing (see the role table below). Independent reviews can run in parallel;
implementation keeps one writer per working tree. contact_supervisor carries
checkpoint decisions and meaningful updates back to the coordinator.
/subagents-fleet inspects running work; /subagents-doctor diagnoses setup.
Example requests—not automatic background activity:
Use reviewer to check this change against my requirements without editing. Ask oracle to challenge this plan before implementation.
pi-web-access: research with inspectable evidence
web_enable loads the research tools on demand:
web_search: search or batch related queries;workflow: "none"returns results without a separate summary-generation call or curator browser.fetch_content: retrieve pages, PDFs, repositories, or supported video content. Answer-mode processing is a separate, optional model interaction.get_search_content: page through stored results or find exact passages using aresponseId, instead of repeatedly fetching the same material.source_check: collect passages and source metadata for manual claim review; retrieval alone does not establish that a claim is true.
Searches/fetches can send data to external services. I keep credentials, private source, and unrelated project details out of research queries and examples.
pi-rewind-hook: files and conversation can be restored separately
Through /fork, I can keep files while branching the conversation, restore both,
or restore code while keeping the conversation. /tree offers exact file
restoration where a checkpoint exists, plus undo when available.
Checkpoints belong to prompt/assistant-turn boundaries, not every tool call.
The session ledger records them; Git keeps snapshot objects reachable through
refs/pi-rewind/store. Coverage includes tracked and untracked non-ignored
files, not ignored files or empty directories. This complements normal commits.
I have no rewind.retention override: the documented default is no automatic
expiration, so snapshot storage can grow.
pi-goal-x: explicit, persistent work
/goal discusses an outcome and confirms a plan before execution;
/sisyphus follows ordered steps. Goals, tasks, and progress persist across
sessions. /goal-direct bypasses drafting only when I explicitly choose it.
/goal-status shows progress, /goal-pause stops automatic continuation,
/goal-resume continues, and /goal-tweak revises the objective or plan.
Optional completion auditing uses a separate agent to check requirements and
evidence; its availability is not a claim that I have enabled it. Ordinary
tasks do not implicitly become goals.
My skills
Only commit-msg lives in ~/.pi/agent/skills/. Pi also discovers the shared
~/.agents/skills/ directory, where my other personal/tool-installed skills live.
| Location / skill | Purpose |
|---|---|
~/.pi/agent/skills/commit-msg |
Past-tense, multiline commit messages in the repository's develop style, based only on inspected changes; no Git mutations. |
~/.agents/skills/implementation-steps |
Hands-on reconstruction courses in scratch/implementation_steps/, with cumulative working code and verification. |
~/.agents/skills/lightpanda |
JavaScript-aware DOM extraction and functional browser automation; not evidence of visual layout fidelity. |
~/.agents/skills/rex |
Control Rex sessions, tabs, panes, commands, and terminal output through its CLI. |
~/.agents/skills/ui-sdk |
Build and test behavior-based, accessible interfaces using @ui-sdk/*. |
~/.agents/skills/ui-ux-a11y |
Apply the bundled UI/UX, WCAG 2.2 AA, accessibility, contrast, and validation rules. |
The subagents package also supplies pi-subagents for orchestration and
council-mode for bounded, read-only advisor debate; these are packaged skills.
Example invocation inside Pi:
/skill:commit-msg staged files
Embedded skill excerpts
These are verbatim selections from my six personal/tool-installed SKILL.md
files, not substitute skill definitions. Supporting files and relative paths
still belong to each original skill directory. The short Rex entry is included
in full; longer skills are excerpted to keep these notes readable.
commit-msg: evidence before wording
Source: ~/.pi/agent/skills/commit-msg/SKILL.md, “Core Contract”.
The generated commit message MUST: 1. Match the style and format of recent `develop` branch commits. 2. Use past tense. 3. Be multiline. 4. Be based solely on inspected file changes from the requested input. 5. Avoid claims that are not supported by the diff/stat/name-status data. 6. Avoid reusing a placeholder subject such as `WIP` from the target commit(s). 7. Avoid mutating git state; this skill is read-only.
implementation-steps: working code and teachability
Source: ~/.agents/skills/implementation-steps/SKILL.md, opening contract.
Produce a hands-on implementation course for the selected target. Every numbered stage includes actual working source and its own detailed README. A learner who follows the documented steps must understand what they are writing and why, and reach the captured target code exactly. Technical correctness, exact source equality, and teachability are separate requirements; none substitutes for another. This workflow is language- and framework-independent. Inspect the target rather than imposing a runtime, architecture, fixed number of stages, or previous task's implementation choices. Create the learning artifacts; leave the target unchanged.
lightpanda: bounded extraction, appropriate evidence
Source: ~/.agents/skills/lightpanda/SKILL.md, “CLI and persistent automation”.
For a known authorized URL, start with a bounded extraction: ```zsh lightpanda fetch --dump markdown --dump-max-bytes 12000 --fail-on-http-error 'http://127.0.0.1:PORT/PATH' ``` Replace the URL with an observed application URL. Use `--dump html` for markup or `--dump semantic_tree_text` for a compact semantic tree. Inspect command status and errors; a dump alone is not proof of successful navigation or interaction.
rex: load guidance from the installed CLI
Source: ~/.agents/skills/rex/SKILL.md, complete file.
--- name: rex description: Use the rex CLI to manage Rex sessions, open tabs, arrange panes, run commands, inspect terminal output, and control connected Rex apps. metadata: rex-stub: "2" --- Run `rex __internal skill` and follow the guide it prints. The guide comes from the installed Rex CLI, so it describes the commands available in that version. If the command fails, the installed Rex version predates the guide. Start with `rex whoami --json`, then use `rex --help` and `rex COMMAND --help`.
ui-sdk: use version-matched documentation
Source: ~/.agents/skills/ui-sdk/SKILL.md, “Read first”.
The docs for the installed version ship in each package, as Markdown: - `node_modules/@ui-sdk//docs/llms.txt` is the index. Read it first. `` is `react`, `vue`, `svelte`, `solid` or `web`. - Then read only the pages your task needs, like `docs/components/select.md`. Don't read the whole `docs/` folder; it's large. - An interface built from our components doesn't need `docs/core.md`. Only path 2 below does, and even then you search it by heading: it's over 300 KB. `docs/rendering.md` sits next to it in the same `docs/` folder. - Don't read compiled JavaScript in `dist/*.js`, even to debug. The docs and the `.d.ts` types are the API; when they don't answer, write a small test that tries it.
Here “path 2” means constructing a missing component/behavior from
@ui-sdk/core, rather than composing existing components.
ui-ux-a11y: preserve authority and scope
Source: ~/.agents/skills/ui-ux-a11y/SKILL.md, “Scope and authority gate”.
Before editing or approving work: 1. Identify the user-authorized implementation scope, repository instructions, and any applicable plan or acceptance criteria in the current project. 2. Discover and inspect the current project's actual sources of truth: existing product behavior, user-supplied reference, design contract, design system, token source, and deployed behavior when the task requires it. Do not assume any filename or path. 3. Identify every applicable `UX-*`, `A11Y-*`, `CC-*`, and `VAL-*` rule ID for the affected routes, states, locales, viewports, themes, and interactions. 4. Record the authoritative baseline required by `VAL-01` before implementation. Use a reference baseline only when the current task or project defines one. 5. Stop if a required source of truth is missing or if compliance would require an unapproved route, feature, redesign, workflow, dependency, content, permission, or product-scope change.
Its complete ui_ux_a11y/ rule folder remains authoritative; this excerpt does
not replace its accessibility, contrast, and rendered-experience checks.
Controlled delegation
My subagents.agentOverrides separates implementation from judgment. All four
roles inherit project context and default to fresh conversation context
(explicit overrides for read-only roles; the bundled default for worker).
| Role | Configured model | Thinking | Responsibility / tools |
|---|---|---|---|
worker |
openai-codex/gpt-6.1-sol |
medium | Implement assigned checkpoints; read/search, bash, edit, write, supervisor contact. |
reviewer |
openai-codex/gpt-6.1-sol |
high | Read-only correctness and evidence review; read/search and supervisor contact only. |
oracle |
openai-codex/gpt-6-astra |
medium | Read-only architectural advice and assumption checking. |
scopeCreepPatrol |
openai-codex/gpt-6-astra |
medium | Read-only requirement traceability and unauthorized-scope detection. |
scopeCreepPatrol has its agent definition at ~/.agents/scopecreeppatrol.md;
the model and other overrides come from my Pi settings.
For delegated implementation, the coordinator routes work, makes decisions, and maintains the ledger—not code. The worker checks advisor-provided code against current files and approved requirements, reports validation evidence, and requests a checkpoint decision before the next unit. Read-only roles return findings/corrective code inline, not files. Recommendations are not user approval.
The scope auditor checks requirement references, a literal 1 to N column,
requirement origin, and the exact statuses no-started / in-progress /
deferred / completed / not-applicable; it must not invent that column's meaning.
Blocking questions use contact_supervisor with need_decision; material
non-blocking updates use progress_update, without routine chatter.
flowchart TD
U["User requirements and approvals"] --> C["Coordinator: route and track"]
C --> W["Worker: implement one checkpoint"]
W --> E["Changed files and validation evidence"]
E --> R["Reviewer: correctness"]
E --> S["Scope patrol: traceability"]
C --> O["Oracle: bounded advice"]
R --> D["Coordinator: checkpoint decision"]
S --> D
O --> D
D -->|Approved next unit| W
D -->|Requirements met| F["Final report"]My subagents configuration
The complete subagents section from ~/.pi/agent/settings.json is embedded
below, including all four role overrides and their unchanged prompts. The outer
JSON object shows where it belongs in settings; unrelated settings are omitted.
{
"subagents": {
"agentOverrides": {
"worker": {
"model": "openai-codex/gpt-6.1-sol",
"thinking": "medium",
"inheritProjectContext": true,
"tools": [
"read",
"grep",
"find",
"ls",
"bash",
"edit",
"write",
"contact_supervisor"
],
"systemPrompt": "You are the implementation worker. Implement only the assigned work traceable to actual user requirements. Never expand scope without explicit prior USER approval. Agent recommendations are not approval. The\n coordinator coordinates, maintains the progress ledger, and relays agent-authored code; it must not author or revise code. Apply advisor-provided code only after checking its applicability to the current files and approved\n requirements. At each assigned implementation checkpoint, report requirement references, changed files, validation evidence, remaining work, and ledger updates needed; request the coordinator's decision before beginning the next\n implementation unit. Use contact_supervisor with reason need_decision for blocking questions and checkpoint decisions, or progress_update for material changes requiring coordinator attention. Do not send routine narration or duplicate completion messages. Never claim validation passed without evidence."
},
"reviewer": {
"model": "openai-codex/gpt-6.1-sol",
"thinking": "high",
"inheritProjectContext": true,
"defaultContext": "fresh",
"tools": [
"read",
"grep",
"find",
"ls",
"contact_supervisor"
],
"systemPrompt": "You are the read-only implementation reviewer. Review the assigned worker checkpoint against actual user requirements, the implementation, tests, and validation evidence. Do not edit files or create patch or\n report files. Return actionable findings with requirement references, exact locations, evidence, and concrete replacement code or unified diffs INLINE when useful. Distinguish actual defects from optional recommendations. Do not\n expand or redefine scope, and never treat your recommendations as user approval. Report blocking findings promptly through contact_supervisor; otherwise return a concise final review. Avoid heartbeats, duplicate findings, and routine chatter. Identify stale checkpoints and unsupported completion claims."
},
"oracle": {
"model": "openai-codex/gpt-6-astra",
"thinking": "medium",
"inheritProjectContext": true,
"defaultContext": "fresh",
"tools": [
"read",
"grep",
"find",
"ls",
"contact_supervisor"
],
"systemPrompt": "You are a read-only advisor answering the specific question assigned by the coordinator. Challenge unsupported assumptions, identify architectural or correctness risks, and distinguish facts, uncertainty,\n and recommendations. When useful, provide actual corrective code or unified diffs INLINE. Do not edit files or create patch or report files. Preserve actual user requirements; scope expansion requires explicit prior USER approval. You cannot grant that approval. Escalate blocking missing decisions through contact_supervisor; otherwise return your bounded answer without routine progress chatter. Do not invent additional requirements or initiate unrelated work."
},
"scopeCreepPatrol": {
"model": "openai-codex/gpt-6-astra",
"thinking": "medium",
"inheritProjectContext": true,
"defaultContext": "fresh",
"tools": [
"read",
"grep",
"find",
"ls",
"contact_supervisor"
],
"systemPrompt": "You are the read-only scope and requirement-traceability auditor. Compare the assigned worker checkpoint and progress ledger with actual user requirements and explicit prior user approvals. Detect\n unauthorized expansion, omitted or altered requirements, and agent suggestions misrepresented as user authority. Check that the ledger includes implementation-requirement references, a literal 1 to N column, status, and requirement\n origin. Do not invent the meaning of 1 to N. Preserve statuses exactly: no-started / in-progress / deferred / completed / not-applicable. Distinguish user-requirement from agent-requirement; an agent-requirement does not authorize\n scope expansion. Report evidence-backed discrepancies promptly through contact_supervisor. Supply concrete corrective code INLINE when useful and within existing scope. Never edit files, create patch or report files, redefine\n requirements, grant approvals, or manufacture acceptance gates. Avoid routine chatter."
}
},
"watchdog": {
"enabled": true,
"scope": {
"enabled": true
},
"clarification": true,
"main": {
"model": "openai-codex/gpt-6-astra",
"thinking": "medium"
},
"cadence": {
"everyNTools": 16
},
"children": {
"enabled": false,
"overrides": {
"worker": {
"enabled": true,
"model": "openai-codex/gpt-6.1-sol",
"thinking": "high",
"cadence": {
"everyNTools": 8
}
}
}
}
}
}
}Watchdog behavior
The watchdog is a separate second-model review mechanism, not the reviewer
role. The main watchdog checks every 16 tool results and at eligible changed-work
boundaries. Scope monitoring and main-session clarification are enabled.
Child watchdogs are off except for worker: its explicit override enables
review every eight tool results and at eligible boundaries, using Sol/high.
These are activity/boundary triggers, not an idle polling loop.
Useful inspection commands inside Pi: /subagents-fleet,
/subagents-doctor, and /subagents-watchdog status.
Local inference: a Pi-backed HTTP API
My local-inference/ Bun/TypeScript workspace exposes an OpenAI-compatible
Chat Completions API at http://127.0.0.1:8081/v1. It is a local HTTP gateway
to Pi-managed providers, not an on-device model-weights server.
packages/protocol: Zod 4 request validation and the backend contract.packages/pi-proxy: Pi's publicModelRuntimefor model resolution, saved credentials, OAuth refresh, and native streaming.packages/server:Bun.serve, HTTP/SSE translation, cancellation, backpressure, and encrypted continuation envelopes.
The gateway pins @earendil-works/pi-coding-agent and @earendil-works/pi-ai
to 1.5.0, independently of my installed CLI's 1.5.2.
flowchart LR
C["HTTP client"] -->|Chat Completions| H["local-inference: Bun HTTP server"]
H --> V["Zod-validated request"]
V --> M["Pi ModelRuntime"]
P["Pi model configuration and saved login"] --> M
M --> Q["Configured upstream provider"]
Q -->|Native stream| M
M -->|Text, reasoning, tool events| H
H -->|SSE deltas| C
C --> T["Optional client-side tool execution"]
T -->|Tool results on next request| H
Each request performs one provider turn: the gateway does not execute tools or
edit files. Tool execution belongs to the client. Text streams separately from
reasoning; disconnects/shutdown cancel upstream work. Native continuation data
uses an authenticated, encrypted reasoning_details envelope.
After signing into the desired provider with Pi, start the gateway from the
directory containing local-inference/:
cd local-inference
bun install --frozen-lockfile
bun run start -- --port 8081In another terminal, inspect the listener or explicitly make a streamed request (the POST uses the provider account and may incur usage):
curl http://127.0.0.1:8081/healthz
curl http://127.0.0.1:8081/v1/models
curl -N http://127.0.0.1:8081/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"openai-codex/gpt-6.1-sol","stream":true,
"messages":[{"role":"user","content":"Reply with hello."}]}'
Model IDs are exact provider/model strings; /v1/models advertises models but
is not an admission allowlist. Pi owns provider support and credential handling.
The default loopback listener needs no client token; non-loopback binding
requires one. --token-env NAME optionally protects the listener, independently
of provider login. Never publish auth.json or tokens.
The API supports text and function tools, not images, schema-constrained
responses, or the Responses endpoint. Clients must use Chat Completions.
Run bun run typecheck from local-inference/ to check the gateway's types.
Code from local-inference
These are verbatim excerpts, not standalone programs: the surrounding class, types, and helper definitions remain in the named source files. No client application or unrelated package namespace is reproduced here.
Create Pi's runtime and list advertised models
From local-inference/packages/pi-proxy/src/index.ts. Credentials and provider
configuration stay behind ModelRuntime; refresh and listing receive the
request's cancellation signal.
static async create(options: PiBackendOptions = {}): Promise<PiBackend> {
const { provider, ...runtimeOptions } = options;
return new PiBackend(await ModelRuntime.create(runtimeOptions), provider);
}
async models(signal: AbortSignal) {
await this.runtime.refresh({ providers: this.provider ? [this.provider] : undefined, signal });
signal.throwIfAborted();
const available = await this.runtime.getAvailable(this.provider, { signal });
return available.map(model => ({ id: this.provider ? model.id : `${model.provider}/${model.id}`, owned_by: model.provider }));
}Resolve the provider while preserving the exact requested model ID
From the same file. Pi supplies provider metadata and custom-model resolution; the HTTP layer retains the caller's exact model ID rather than applying CLI fuzzy-name or thinking-suffix conveniences to it.
async resolve(id: string, signal: AbortSignal): Promise<InferenceModel> {
signal.throwIfAborted();
const slash = id.indexOf("/");
const provider = this.provider ?? (slash > 0 ? id.slice(0, slash) : undefined);
const modelId = this.provider ? id : id.slice(slash + 1);
if (!provider) throw new ApiError(400, "Use provider/model as the model ID, or start with --provider");
await this.runtime.refresh({ providers: [provider], signal });
signal.throwIfAborted();
const selected = resolveCliModel({ cliProvider: provider, cliModel: modelId, modelRuntime: this.runtime });
if (!selected.model) throw new ApiError(400, selected.error ?? "Pi could not resolve the requested model", "model_resolution_error");
// Pi owns model construction, provider metadata and custom-model support.
// Its CLI resolver also accepts fuzzy names/thinking suffixes; an HTTP model
// field is an exact ID, so those conveniences must not rewrite that field.
return { ...selected.model, id: modelId };
}Choose the Pi streaming API
From PiBackend.stream in the same file. Shared reasoning options use
streamSimple; native reasoningEffort options use stream.
const events = request.reasoningEffort === undefined
? this.runtime.streamSimple(model, context, request)
: this.runtime.stream(model, context, request);Keep text and reasoning separate on the wire
From local-inference/packages/server/src/index.ts, inside the event switch.
Text deltas are emitted as they arrive, without waiting for provider completion.
case "text_delta": source.push(event.delta); await chunk({ content: event.delta }); break;
case "thinking_delta": await chunk({ reasoning_content: event.delta }); break;References
Sources for the harness, extensions, skill-driven tools, and libraries I use with Pi:
- Pi and Pi source: the coding harness and its libraries:
pi-coding-agent(CLI/SDK),pi-agent-core(agent loop),pi-ai(provider access), andpi-tui(terminal interface). - Pi SDK: embedding Pi and accessing its model/runtime services for my inference gateway.
- Pi skills: discovering and loading my reusable task instructions, including shared
~/.agents/skills/skills. - pi-subagents: agent definitions and overrides, workflows and coordination, fleet inspection, and watchdog configuration.
- pi-web-access: research tool reference, including search, fetch, stored-result retrieval, and source checking.
- pi-rewind-hook: restore modes, checkpoint coverage, and retention.
- pi-goal-x: goal controls and optional completion auditing.
- Lightpanda: DOM extraction and functional browsing through my browser skill.
- Rex agent integration: terminal session, tab, and pane control through my Rex skill.
- UI SDK: the interface behavior/component libraries targeted by my
ui-sdkskill. - Bun, TypeScript, and Zod: running, implementing, and validating requests in my local Pi inference gateway.

