Personal Pi package that bundles:
- Pi built-in MCP configuration (no
pi-mcp-adapter; usesbuiltin:mcp) @narumitw/pi-file-context(/file-contextin-TUI file browser; Tab inserts@path)pi-claude-bridge(Claude Code subscription asclaude-bridge/*models via Agent SDK — no separatepi installneeded)pi-emphasis(colored[[Done]]/[[Failed]]status pills, icons and bold in TUI replies, plus thereply_styleprompt rules that teach the agent to write them; git-pinned inpackage.json, not on npm — needs Pi ≥1.5 and a Nerd Font terminal, or setPI_EMPHASIS_PILL_ICONS=0/PI_EMPHASIS_ROUND_CAPS=0)usage-footer.tsfooter/status extension showing model and context usagesubagents.tsin-process subagent tool withexplore,shell, andcustommodes
The portable Herdr layout, PR dashboard, and Git History mods live in
herdr-app/. Install or update them with
node herdr-app/install.mjs --activate. Personal credentials and dismissal state
stay on each computer; this installer is separate from Pi setup.
cd F:/MyWork/my-pi
npm install
pi install F:/MyWork/my-piRestart Pi or run /reload.
The postinstall script handles Accordion build automatically.
Claude subscriptions are numbered accounts managed in /account, like Codex. Each one has its own login folder (CLAUDE_CONFIG_DIR) and its own provider: Claude 1 = claude-bridge (~/.claude), Claude 2 = claude-bridge-2 (~/.claude-personal), Claude 3 = claude-bridge-3, and so on. Pick one in /account (Enter) or with /model. Keep every folder different so logging in one account never overwrites another. Details: docs/claude-code-profiles.md.
-
In Pi, open
/account, select the Claude row and presslto see its folder and login command (aadds a new account first)./account statuslists every folder. -
Open a separate terminal outside Pi and log in with that exact folder.
PowerShell (use a fresh terminal and close it afterward, so these environment changes do not persist in your working shell):
$env:CLAUDE_CONFIG_DIR = Join-Path $HOME '.claude-personal' Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue claude auth login claude auth status
Git Bash (environment changes apply only to each command):
env -u ANTHROPIC_API_KEY CLAUDE_CONFIG_DIR="$HOME/.claude-personal" claude auth login env -u ANTHROPIC_API_KEY CLAUDE_CONFIG_DIR="$HOME/.claude-personal" claude auth status
-
In the browser, explicitly choose the account meant for that folder, not one that may already be signed in. Check
claude auth statusreports the intended account before continuing. -
Restart Pi. Run
/provider-usage, then pressrto refresh usage.
Avoid: running login/logout without an explicit CLAUDE_CONFIG_DIR, pointing two accounts at one folder, copying credentials between folders, or using setx to change the global config directory. Pi's /login is separate from the Claude Code login used by claude-bridge. /account checks for login files, not token validity, so an account marked ready can still need OAuth renewal.
Muse usage refreshes through muse usage --json on the existing five-minute schedule and when you press r in /provider-usage. Install Muse Code and sign in to the intended account with muse login. Usage follows the Muse CLI account, which may differ from Pi's Meta login. The command fetches subscription allowance without a model turn; Muse documents that fresh usage reads mint a key and are rate-bounded to once per host per minute. The old Pi key-mint snapshot is no longer read.
The footer stays three lines tall: session totals on the left, model on the top right, Codex/Antigravity on the second right row, and Copilot/Cursor on the third. Connected accounts are shown independently of the selected Pi model. Summary labels: wk = weekly, AG-G = Antigravity Gemini, AG-C/G = Antigravity Claude/GPT, Copilot dollars = credits ÷ 100 rounded to whole dollars (user-requested equivalent, not a verified bill; raw credits remain in details), Cursor M = overall monthly included usage and A = Auto. Percentages are rounded; * marks stale data. Narrow terminals truncate summaries instead of adding rows. Use /provider-usage for reset dates, errors and manual refresh. Automatic refresh runs every five minutes while the footer is enabled. Cross-process cache refreshes use Windows named-pipe locks (avoiding reserved TCP-port failures) and loopback TCP locks on other platforms. When updating from TCP-based locks on Windows, restart all Pi sessions together so they use the same locking mechanism.
Codex uses Pi's openai-codex OAuth login for personal and Team/Business usage. It sends the selected account ID with the usage request and isolates cached results by credential. Failed Pi authentication or usage reads never switch to another account. Without a Pi Codex credential, it uses the existing Codex CLI login instead.\n\nCursor is experimental: it uses the internal Cursor usage API. With a Cursor provider such as cursor-to-pi, it resolves the Cursor API key through Pi's model registry (including /login) and exchanges it for a short-lived bearer, held only in memory. CURSOR_API_KEY is also supported. It never applies an unrelated CLI's active team to SDK-key usage; shared observations are scoped by a hash of the effective credential. If a selected key is rejected, it reports unavailable rather than silently showing another account. Without an SDK key, it can use the existing Cursor Agent CLI file-store login (Windows/Linux; macOS requires the CLI's file store). That fallback never refreshes CLI tokens or starts a login; renew an expired CLI login in Cursor Agent. IDE-only/Keychain logins are not supported. Cursor shows monthly included-plan percentage, plus separate Auto and API percentages when reported. These categories are not additive; missing categories are omitted, not assumed zero. Billing-cycle end is shown in details, without inventing per-category reset schedules. These are not session tokens or on-demand spending. Missing usage is omitted from the footer; failed refreshes retain the last successful value marked stale.
cursor-to-pi registers zero dollar rates. The footer therefore adds standard-speed list-price estimates for Grok 4.5/4.6/4.7, Composer 2.5, and exact supported Claude IDs when reported dollars are nonpositive. Cursor estimates are marked est; cache reads are priced separately, unpublished cache-write rates are estimated at input rates, and Grok 4.7's >256k prompt tier is respected. Auto and unknown model aliases remain unpriced Cursor. These are not invoices, additional charges, or inferred quota percentages. SDK multi-call usage may be apportioned or unavailable until the run finishes, so the footer cannot recover exact per-request consumption from those messages. Use /provider-usage, then r, for account refresh and errors.
This repo owns First-Party Accordion under extensions/accordion/ and registers its stable Pi entry automatically.
Setup is automatic via postinstall. Manual steps only if needed:
npm run accordion:install
npm run accordion:buildThen in Pi:
/accordion
The Global Accordion Dashboard lets you watch multiple Pi sessions in one browser tab, without the Tauri desktop app.
Run /accordion in any Pi session to add it to the dashboard and focus its entry in the sidebar:
/accordion = watch + focus current Pi session in the global browser dashboard
Multiple sessions. Every Pi session gets its own sidebar entry. Two sessions open in the same repo are still separate entries, not one. Session identity is the Pi session ID, not the working directory.
Browser refresh. Refreshing the browser reconnects to all currently live watched sessions. Sessions that have already exited are not shown.
Quitting Pi. When a Pi session exits, its sidebar entry is removed automatically.
MVP limitation. Direct single-session Accordion links (opened outside the broker dashboard) remain independent. Opening a direct link for a session that is already watched in the broker dashboard can conflict with it, because Accordion supports only one active GUI client per session at a time.
The Accordion Browser Broker (extensions/accordion/extension/broker/) is a singleton local HTTP/WebSocket service that backs the Global Accordion Dashboard. Run it manually for debugging or development:
npm run accordion:brokerThis starts the broker on a loopback port, prints the dashboard URL, and writes ~/.accordion/browser-broker.json. The broker stays alive until you press Ctrl+C.
In normal use, /accordion starts the broker automatically, adds the current Pi session to the watched list, and opens the dashboard in your browser.
This package no longer ships pi-mcp-adapter. Pi's built-in MCP (builtin:mcp)
reads:
| Scope | Path |
|---|---|
| Global (preferred) | ~/.pi/agent/mcp.json |
| Project (optional) | .pi/mcp.json (trusted projects only) |
Use the global file for personal servers (playwright, cua, azure-devops, …).
Project .pi/mcp.json is optional; when present, entries
with the same name replace the global ones. This repo does not require a
project MCP file — servers live in the global agent config.
Pi does not read ~/.config/mcp/mcp.json or project-root .mcp.json.
Keep project .mcp.json only if other hosts (Cursor/Claude/Codex) need it.
Tools are named mcp__<server>__<tool>. Manage servers with:
pi mcp list
pi mcp add <name> -- <command> [args...] # writes ~/.pi/agent/mcp.json
pi mcp add -l <name> -- <command> [args...] # writes .pi/mcp.json
pi mcp remove <name>Exposure: direct, codemode, deferred, hidden, plus per-tool
toolExposure. See Pi's docs/mcp.md.
Important: an extension that registers /mcp (such as pi-mcp-adapter)
replaces built-in MCP. Keep that package uninstalled for this setup.
Playwright + the local recorder are configured globally in
~/.pi/agent/mcp.json (Edge via --browser msedge). The recorder uses an
absolute path into this repo:
{
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@latest", "--browser", "msedge"],
"exposure": "direct"
},
"playwright-recorder": {
"command": "node",
"args": ["C:/my-pi/scripts/playwright-record-mcp.mjs"],
"exposure": "direct"
}
}Cross-host copy (optional): project .mcp.json for Claude/Cursor/Codex — those
hosts do not read Pi's mcp.json files.
After changing MCP config, run /reload (or a new session). Verify with /mcp
or pi mcp list.
Playwright MCP does not expose video recording. For a small standalone Edge
recording, use the helper in scripts/playwright-record.mjs:
npm run playwright:record -- https://example.com --duration 30Use --duration 0 to record until Ctrl+C. Videos are saved as WebM files
under ./.playwright-mcp/videos/:
npm run playwright:record -- https://localhost:5050 --duration 0This launches a separate headed Edge context with Playwright's native
recordVideo support; it does not attach to the browser session owned by the
MCP server.
The same recorder is exposed as a second MCP server named
playwright-recorder, with the record_video tool. After restarting the
clients, an agent can call it with a URL and duration, for example:
{
"url": "https://example.com",
"duration": 30
}It returns the saved .webm path. The tool requires a bounded duration from
1 to 3600 seconds and launches a separate headed Edge context.
bg_runuses a detached supervisor: commands, logs, stdin, and timeout enforcement survive Pi exit/reload. Reopen the same Pi session to recover status and completion notifications. Stop persistent jobs explicitly withbg_killor/jobs kill <id>; quitting Pi no longer stops them.- Background subagents persist results, checkpoints, launch configuration, usage, and child audit transcripts. Their in-process execution cannot survive host exit: unfinished runs become
interrupted, never automatically replayed. subagent_resume({ jobId: "sa-1" })explicitly starts a new run with a checkpoint handoff. Inspect uncertain side effects first. This is not exact tool/model replay; each interrupted run can have only one recovery child.- Storage:
~/.pi/agent/jobs/, isolated by Pi session ID. Override withPI_DURABLE_JOBS_DIR. IDs remain session-local and monotonic across reloads; logs/transcripts are retained. One host per session is supported. - Completion delivery is at-least-once across crashes. Confirmed results stay queryable; unconfirmed notifications are recovered. Supervisor loss or host reboot yields an unknown/interrupted command outcome, not an automatic retry.
See ADR 0006 for the recovery contract.
On Pi 1.3.0+ (stable), background commands and subagents cooperate through one native cache_warming_decision hook. Running joined/detached children, and running commands with notifyOnFinish: true, imply an expected parent continuation. Completed, cancelled, failed, interrupted, or silent command jobs do not. Eligibility is scoped to the current session ID, not the working directory, and is cleared on session replacement/shutdown.
To allow warming between turns, explicitly set "cacheWarming": "idle" in your global Pi settings.json (normally ~/.pi/agent/settings.json). Pi defaults to "streaming"; this package never changes that setting or bypasses consent. Use PI_BACKGROUND_CACHE_WARMING=0 to disable this package's continuation hint (also accepts false, no, off). This does not disable Pi's own native warming policy.
The hint assumes continuation probability 1, but still requires at least $0.05 savings (missCost - warmCost); unknown/nonfinite economics and expensive refreshes defer to Pi. Pi alone schedules, replays and bills refreshes, including its retention/replay checks, deadlines and idle safety window. No extension refresh timer or direct paid request is added. Native scheduling is at 90% of TTL (with at least ten seconds of margin): 4m30s for a five-minute TTL, not an exact four-minute interval. /session shows native warming status, decisions and extension overrides; refresh usage stays in native accounting.
On warming-capable hosts the automatic Anthropic one-hour TTL upgrade is disabled, even if warming is off; explicit provider/user TTLs remain untouched. Older/unknown hosts keep the previous running-subagent TTL fallback (PI_SUBAGENT_LONG_CACHE=0 opts out). The repository's 0.84.x SDK lacks the new event types, so a narrow public-event adapter and conservative host-version gate provide compatibility without private Pi imports. Both extensions use a synchronous pi.events owner/collection protocol to avoid competing overrides; unrelated third-party decision hooks still follow Pi's normal last-defined-override semantics.
This package registers a subagent tool. It runs child Pi AgentSessions in-process (SDK-style, no subprocess) with isolated context.
Execution is joined by default: the launching tool stays pending until the child finishes and cleans up, then returns its report. Batch independent calls in the same assistant message to run children concurrently. /subagent on/off changes prompting only, not execution mode.
Fresh agents automatically receive a capability-selection guide through tool metadata and the startup system prompt while workflow mode is on (the default). The guide explains required joined work vs optional detached work, true parallel batches, saved-context follow-ups using the latest job ID, self-contained tasks, limited child tools, shared-filesystem ownership, evidence packets, context/slot limits, and explicit recovery. It warns against batching dependent edits with prerequisite research or duplicating a child's owned work. Workflow off removes coaching, not the joined runtime safeguards. The guide is shared between both instruction surfaces to avoid drift.
subagent({ type: "explore", task: "Find the route" })returns the required joined result.subagent({ type: "shell", task: "Investigate optional logs", mode: "detached" })returns an immediate job ID with an optional result delivered later.- Legacy
background: truemeans detached;falsemeans joined. Conflictingmode/backgroundis rejected. - Capacity is 6 running children across both modes. Excess admission fails explicitly; there is no queue or silent mode switch. Repeated tool-call request IDs reuse the admitted job before the capacity check.
- Evidence packets honor either mode. Structured verification, packet diagnostics, limits, usage, and audit transcripts are retained for retrieval; packet children cannot be followed up. Result
modeis joined/detached; packet/prose-fallback telemetry usesevidenceMode. subagent_wait({ jobIds: ["sa-1"], waitFor: "any", timeoutSeconds: 120 })retrieves outcomes.waitFordefaults toall;anyreturns after one targeted terminal outcome. Omitted IDs target running and undelivered finished jobs. Timeout defaults to 120 seconds (max 240); timeout or abort stops waiting, not children. Explicit IDs can retrieve already acknowledged outcomes.- Joined cancellation aborts the child and awaits cleanup. Detached children are cancelled explicitly with
subagent_cancel. Cancelling a wait never cancels its children. - Completion saves the outcome/report atomically. If that save fails, the finished child remains terminal in memory, releases capacity, and returns an explicit
persistenceErrorwarning instead of losing its report or pretending to keep running. Detached automatic delivery waits for a confirmed registry write; explicit retrieval still works. A later successful snapshot confirms the in-memory outcomes. After a crash during persistent disk failure, inspect recorded tool results/transcripts before explicit recovery. - Joined results are acknowledged only after the launching tool receipt (or a wait receipt) is recorded. Normal joined results are not automatically delivered again. After a crash, unacknowledged joined outcomes remain discoverable with
subagent_statusand retrievable withsubagent_wait; there is no automatic restart. Legacy saved jobs remain detached and keep their outbox.
subagent_followup({ jobId: "sa-1", task: "Check a related detail" }) explicitly reopens a successful normal child's disk transcript using its saved resolved model, cwd, tools, and prompt. It also defaults to joined and accepts the same legacy mode alias. Unknown, failed, cancelled, interrupted, packet, and legacy jobs without reusable configuration/transcripts are rejected. The transcript lineage has exclusive ownership during execution/cleanup, including requests through ancestor IDs. Use the latest successful job ID only if there has been no later failed/cancelled/interrupted assignment. A failed lineage stays closed even when an older assignment succeeded: start an explicit new child with a reviewed handoff, or explicitly recover interrupted work after checking side effects. Ancestor receipts retain their original per-segment reports but their transcript pointer names mutable shared history. Unavailable saved models fail rather than silently switching.
Child-only in-memory settings enable native SDK compaction independently of the parent's Accordion/global settings, without loading extensions or writing settings to disk. The target context budget is 50k tokens, reduced for smaller model windows with response reserve and a recent-tail target no larger than 12k. Native estimates and indivisible messages mean this is a compaction target, not a hard per-request token ceiling. Status/report context usage is known tokens/window or explicitly unknown (especially immediately after compaction).
At an idle follow-up boundary, over-budget reusable context is compacted before prompting. After 3 assignments, 1 MiB raw transcript, or unknown/unsafe context, the next explicit follow-up uses a new session with a bounded handoff: original goal, previous report up to 8k characters, and the full audit transcript pointer. This is marked fresh handoff, not full memory, with reset reason and generation in the result. Oversized goals that cannot fit the bounded handoff fail visibly. Full old transcripts remain for audit. Compaction failures are visible errors requiring a reviewed new child/handoff, not infinite retries or replay of uncertain side effects. Usage, turns, tools, tokens, and costs are per assignment; historical usage is not billed again.
Types:
explore- read-only codebase investigation usingread,grep,find,lsshell- command-oriented investigation usingread,grep,find,ls,bashcustom- load a markdown agent from~/.pi/agent/agents/*.mdor nearest.pi/agents/*.md
Custom agent example:
---
name: reviewer
description: Review code for correctness and maintainability
tools: read, grep, find, ls
---
You are a focused review subagent. Return actionable findings with evidence.Optional model config lives in models.json in the same directory as those markdown files.
Project .pi/agents files still override user ~/.pi/agent/agents files when names match.
Agent keys in models.json must exactly match the custom agent name value.
models.json must be valid JSON. Comments are not allowed.
Example models.json:
{
"defaultModel": "github-copilot/claude-sonnet-4.6"
}Model resolution order for custom agents is params.model, then models.json, then markdown frontmatter, then the inherited session model.
Subagent workflow mode is on by default. Future prompts in the session tell the main agent when and how to use explore, shell, and custom subagents automatically. Manage it with:
/subagent status
/subagent off
/subagent on
List custom agents in Pi:
/subagents
Edit per-agent model choices in a TUI and save them back to models.json:
/subagents-model
Push this package to git, then:
pi install git:github.com/<you>/my-piThe postinstall script runs automatically and handles:
npm run accordion:installnpm run accordion:build(if not already built)