pi-extensions

Personal extensions for the pi coding agent. Built from an analysis of my own Claude Code and Codex session history: each one automates something I was demonstrably doing by hand, over and over.

Extension	One-liner	Use it when
swarm	Codex review swarms + parallel worktree fix lanes	Before shipping meaningful changes; when fixing a list of independent issues
probe	Headless-browser screenshots, console errors, failed-request bodies	Verifying UI changes, local-vs-staging parity, debugging 4xx/5xx
jira	Jira via REST API token, including card attachment images	Any card-shaped work: start, review, verify against acceptance criteria
scope-guard	Blocks out-of-scope edits and junk commits	Always on; declare a scope for tightly-bounded tasks
ci	Pull GitHub Actions failures for the current branch	A check fails and you'd otherwise paste the log
devwatch	Dev servers with captured logs + port management	Running dev servers the agent should be able to read
shot	Attach recent screenshots to a message	Quickly showing the agent what you see

Install

Copy (or run ./install.sh, which does the same) into pi's user extension directory:

cp extensions/*.ts ~/.pi/agent/extensions/

Pi loads them on next start; /reload picks them up in a running session.

Requirements:

pi >= 0.82 (the ImageContent shape changed in 0.82 to {type, data, mimeType}; these extensions target the new shape)
macOS (uses sips for image downscaling and lsof in devwatch)
Codex CLI authenticated (codex on PATH) for swarm
GitHub CLI authenticated for ci
Chrome, Chromium, Arc, or a Playwright browser cache for probe (it auto-discovers ~/Library/Caches/ms-playwright builds)

No npm installs. Everything runs on Node builtins plus the packages pi already ships (typebox, @earendil-works/pi-ai).

swarm

My own take on pi-subagents + pi-worktree, merged into one pipeline and shaped around a workflow I used to run by hand: fan out independent read-only reviewers over a diff, verify every candidate finding, then fix the confirmed ones in parallel worktrees.

What it does

swarm review spawns one read-only codex exec lane per review angle. Eight angle presets: correctness, removed-behavior, cross-file, conventions, efficiency, reuse, simplification, altitude. Each lane reports up to 6 candidates in a strict line format. Candidates are deduped by file:line, then one verifier lane per candidate re-reads the code and returns CONFIRMED, PLAUSIBLE, or REFUTED with a reason. The aggregated report (confirmed first, ranked by severity) comes back as the tool result and is saved to ~/.pi/swarm/<run-id>/report.md.
swarm fix takes a list of independent items and creates one git worktree per item in a sibling directory <repo>-swarm/<slug> (branch swarm/<slug>), then runs a workspace-write codex lane in each. Lanes are instructed to stay in scope, commit nothing, and end with STATUS: done|partial|blocked — summary. The report shows each lane's status and git diff --stat; you review the worktree diffs and merge what you like.
swarm status / swarm kill / swarm clean inspect the run, kill every lane (including orphans from a crashed session, tracked in ~/.pi/swarm/running.json), and remove all swarm worktrees + branches.

How it works

Lanes are codex exec --json child processes in their own process groups, capped at 4 concurrent (PI_SWARM_CONCURRENCY), logging to ~/.pi/swarm/<run-id>/*.log. A widget above the editor shows lane progress, flags any lane silent for 3+ minutes as stalled, and a 30-minute hard timeout kills runaways. Default model is gpt-5.6-sol (PI_SWARM_MODEL or the model param to override). Reviewers and verifiers run with -s read-only; fix lanes get -s workspace-write scoped to their worktree. No coordination files ever land in the repo.

When to use it

/swarm review (optionally with notes) before committing or opening a PR on anything non-trivial. Add scope:'branch' to review the whole branch instead of the uncommitted diff, and pass both repo paths for paired-repo work.
/swarm fix after you've agreed on a list of independent fixes; the model derives the items from the conversation. One item per independent concern.
Not for single small fixes: the orchestration overhead isn't worth it, just fix it inline.

Commands:/swarm review [notes], /swarm fix [notes], /swarm status, /swarm kill, /swarm clean

probe

Lets the agent look at the running app itself instead of asking me to screenshot, open devtools, or paste network responses. This replaces the highest-volume manual loop in my history: screenshot local, screenshot staging, paste both, repeat.

What it does

snap navigates to a route, screenshots it, and returns the image plus console errors and failed requests (with response bodies) from the load.
parity captures the same route on local and staging and attaches both screenshots, first local then staging, for direct visual comparison.
errors skips the screenshot and just reports console exceptions/errors and failed request bodies, for "why is this 500ing" debugging.
config prints the resolved project config with the password redacted.

How it works

Zero dependencies: it launches an installed Chrome/Chromium with --headless=new --remote-debugging-port=0 and speaks the Chrome DevTools Protocol over Node's built-in WebSocket. If no system browser exists it falls back to the newest "Chrome for Testing" build in the Playwright cache. Base URLs, login credentials, and default routes live per project in ~/.pi/probe.json (created chmod 600 by /probe); projects are matched by cwd prefix. Each project gets a persistent Chrome profile under ~/.pi/probe/profiles/, so a login survives between calls, and when a page redirects to the login form the extension fills the configured selectors (with the native-setter trick so React controlled inputs register) and retries. Screenshots over ~1.5MB are downscaled via sips. A full http(s):// URL as route works without any project config.

When to use it

After UI changes: probe snap the affected route instead of asking "does it look right?".
Local-vs-staging drift: probe parity on the routes that differ.
Any browser-side failure (blank page, ChunkLoadError, failing fetch): probe errors reads the console and response bodies directly.

Setup: run /probe once to scaffold ~/.pi/probe.json, fill in URLs + test credentials. Keep real user credentials out of it; use dedicated test accounts.

jira

Jira over the plain REST API with an API token. Exists because the Atlassian MCP kept breaking OAuth and, worse, cannot see images attached to cards; this downloads attachments and hands them to the model as real images.

What it does

get pulls a card into context: summary, status, assignee, description (ADF converted to readable text), comments, and attachment images (downloaded with auth, downscaled, attached to the tool result so the model can read screenshots and mockups).
search runs a JQL query, comment adds a comment, create makes a new card (optionally under a parent/epic).
/jira SXCL-1234 pulls a card into the conversation. /jira start SXCL-1234 also has the agent create the branch off latest main (both repos in a paired-repo workspace). /jira verify [KEY] audits the current branch against the card's acceptance criteria and reports covered / partial / missing; the key defaults to the ticket id in the branch name.

How it works

Config in ~/.pi/jira.json (chmod 600): site URL, account email, API token from https://id.atlassian.com/manage-profile/security/api-tokens. /jira auth prompts for the three values and validates them against /myself before saving. Descriptions and comments arrive as Atlassian Document Format and are converted to markdown-ish text (headings, lists, code blocks, tables, mentions, task lists).

When to use it

Any time a ticket id comes up: the model is prompted to fetch cards itself rather than asking for a paste.
Start-of-work ritual: /jira start KEY = branch + requirements checklist in one step.
Before opening the PR: /jira verify catches the "card asked for three things, branch does two" gap.

scope-guard

Structural enforcement of "only touch what the task is about". Exists because agents (especially delegated workers) kept editing files outside scope and staging junk like .pnpm-store/ into PRs.

What it does

Always on: edit/write into node_modules/, .pnpm-store/, or .git/ is blocked outright.
After every git add / git commit the staged file list is checked; junk paths (dist/, build/, .next/, .turbo/, coverage/, .DS_Store, *.log, plus the hard list) and out-of-scope files produce a warning appended to the bash tool result, so the model sees it and unstages before committing. You also get a UI notification.
With a declared scope, any edit/write outside it is blocked with a reason the model can read, so it has to ask instead of wandering.

How it works

A tool_call handler (blocking) and a tool_result handler (annotating). Scope is session-local state set by the /scope command: either explicit globs (/scope src/pages/** packages/api/**) or /scope branch, which snapshots the files already changed on the branch (vs merge-base with main) plus current dirty files. /scope off clears it; bare /scope shows it. A footer status chip shows when a scope is active.

When to use it

Junk protection needs nothing; it's on.
Declare a scope at the start of tightly-bounded work ("only the help docs", "only IssuesTracking"), the exact situations where scope creep bit before.

ci

GitHub Actions results for the current branch, in-context. Exists because CI failure logs kept getting copy-pasted by hand.

What it does

ci status lists recent workflow runs on the current branch with conclusions and run ids.
ci logs fetches the failed-step logs of the latest failed run (or a specific runId), truncated to the last 30KB.
/ci asks the model to check the branch, pull failing logs, and identify the root cause before touching anything.

How it works

Thin wrapper over gh run list / gh run view --log-failed executed in the repo cwd. Auth and repo resolution are whatever gh already has.

When to use it

After a push, or the moment anyone says "the check is failing". The model is prompted to reach for it instead of asking for a paste.

devwatch

Dev servers the agent can read, plus port management.

What it does

dev tool: start/stop/restart/list/logs for named dev servers. Servers spawn detached with output teed to ~/.pi/dev-logs/<name>.log, so they survive pi exiting and any session (or another tool) can read the same logs. logs supports errorsOnly (error lines plus stack context) and grep, so the agent pulls fresh errors itself instead of me copy-pasting stack traces.
ports tool: list TCP listeners with pid, command, and project cwd; kill by port or pid. /ports shows a quick toast.

When to use it

Have the agent start dev servers through dev rather than raw bash, then after changes it checks dev logs errorsOnly:true on its own. ports kill replaces "kill whatever is on 3003".

shot

/shot [n] [message] attaches the n most recent screenshots from the macOS screenshot folder (override with PI_SHOT_DIR) to your message, downscaling anything over ~1.5MB. For the times you want to show the agent something faster than describing it. With probe in place, prefer letting the agent take its own screenshots; /shot covers everything probe can't see (native apps, other windows, your phone photo synced to Desktop).

Notes

Secrets: all credentials live outside this repo in ~/.pi/probe.json and ~/.pi/jira.json (0600). Nothing in extensions/ contains a secret.
pi 0.82 image gotcha: tool results and user messages take images as {type:"image", data, mimeType}. Older extensions using the Anthropic-style source wrapper fail silently.
Verification recipe used for these: typecheck with a tsconfig whose paths map the pi package's dist/*.d.ts (moduleResolution bundler, allowImportingTsExtensions), a harness that loads each extension with a fake ExtensionAPI via node --experimental-strip-types, and a real pi -p load.

pi-extensions

Personal extensions for the pi coding agent. Built from an analysis of my own Claude Code and Codex session history: each one automates something I was demonstrably doing by hand, over and over.

Extension	One-liner	Use it when
swarm	Codex review swarms + parallel worktree fix lanes	Before shipping meaningful changes; when fixing a list of independent issues
probe	Headless-browser screenshots, console errors, failed-request bodies	Verifying UI changes, local-vs-staging parity, debugging 4xx/5xx
jira	Jira via REST API token, including card attachment images	Any card-shaped work: start, review, verify against acceptance criteria
scope-guard	Blocks out-of-scope edits and junk commits	Always on; declare a scope for tightly-bounded tasks
ci	Pull GitHub Actions failures for the current branch	A check fails and you'd otherwise paste the log
devwatch	Dev servers with captured logs + port management	Running dev servers the agent should be able to read
shot	Attach recent screenshots to a message	Quickly showing the agent what you see

Install

Copy (or run ./install.sh, which does the same) into pi's user extension directory:

cp extensions/*.ts ~/.pi/agent/extensions/

Pi loads them on next start; /reload picks them up in a running session.

Requirements:

pi >= 0.82 (the ImageContent shape changed in 0.82 to {type, data, mimeType}; these extensions target the new shape)
macOS (uses sips for image downscaling and lsof in devwatch)
Codex CLI authenticated (codex on PATH) for swarm
GitHub CLI authenticated for ci
Chrome, Chromium, Arc, or a Playwright browser cache for probe (it auto-discovers ~/Library/Caches/ms-playwright builds)

No npm installs. Everything runs on Node builtins plus the packages pi already ships (typebox, @earendil-works/pi-ai).

swarm

My own take on pi-subagents + pi-worktree, merged into one pipeline and shaped around a workflow I used to run by hand: fan out independent read-only reviewers over a diff, verify every candidate finding, then fix the confirmed ones in parallel worktrees.

What it does

swarm review spawns one read-only codex exec lane per review angle. Eight angle presets: correctness, removed-behavior, cross-file, conventions, efficiency, reuse, simplification, altitude. Each lane reports up to 6 candidates in a strict line format. Candidates are deduped by file:line, then one verifier lane per candidate re-reads the code and returns CONFIRMED, PLAUSIBLE, or REFUTED with a reason. The aggregated report (confirmed first, ranked by severity) comes back as the tool result and is saved to ~/.pi/swarm/<run-id>/report.md.
swarm fix takes a list of independent items and creates one git worktree per item in a sibling directory <repo>-swarm/<slug> (branch swarm/<slug>), then runs a workspace-write codex lane in each. Lanes are instructed to stay in scope, commit nothing, and end with STATUS: done|partial|blocked — summary. The report shows each lane's status and git diff --stat; you review the worktree diffs and merge what you like.
swarm status / swarm kill / swarm clean inspect the run, kill every lane (including orphans from a crashed session, tracked in ~/.pi/swarm/running.json), and remove all swarm worktrees + branches.

How it works

Lanes are codex exec --json child processes in their own process groups, capped at 4 concurrent (PI_SWARM_CONCURRENCY), logging to ~/.pi/swarm/<run-id>/*.log. A widget above the editor shows lane progress, flags any lane silent for 3+ minutes as stalled, and a 30-minute hard timeout kills runaways. Default model is gpt-5.6-sol (PI_SWARM_MODEL or the model param to override). Reviewers and verifiers run with -s read-only; fix lanes get -s workspace-write scoped to their worktree. No coordination files ever land in the repo.

When to use it

/swarm review (optionally with notes) before committing or opening a PR on anything non-trivial. Add scope:'branch' to review the whole branch instead of the uncommitted diff, and pass both repo paths for paired-repo work.
/swarm fix after you've agreed on a list of independent fixes; the model derives the items from the conversation. One item per independent concern.
Not for single small fixes: the orchestration overhead isn't worth it, just fix it inline.

Commands:/swarm review [notes], /swarm fix [notes], /swarm status, /swarm kill, /swarm clean

probe

Lets the agent look at the running app itself instead of asking me to screenshot, open devtools, or paste network responses. This replaces the highest-volume manual loop in my history: screenshot local, screenshot staging, paste both, repeat.

What it does

snap navigates to a route, screenshots it, and returns the image plus console errors and failed requests (with response bodies) from the load.
parity captures the same route on local and staging and attaches both screenshots, first local then staging, for direct visual comparison.
errors skips the screenshot and just reports console exceptions/errors and failed request bodies, for "why is this 500ing" debugging.
config prints the resolved project config with the password redacted.

How it works

Zero dependencies: it launches an installed Chrome/Chromium with --headless=new --remote-debugging-port=0 and speaks the Chrome DevTools Protocol over Node's built-in WebSocket. If no system browser exists it falls back to the newest "Chrome for Testing" build in the Playwright cache. Base URLs, login credentials, and default routes live per project in ~/.pi/probe.json (created chmod 600 by /probe); projects are matched by cwd prefix. Each project gets a persistent Chrome profile under ~/.pi/probe/profiles/, so a login survives between calls, and when a page redirects to the login form the extension fills the configured selectors (with the native-setter trick so React controlled inputs register) and retries. Screenshots over ~1.5MB are downscaled via sips. A full http(s):// URL as route works without any project config.

When to use it

After UI changes: probe snap the affected route instead of asking "does it look right?".
Local-vs-staging drift: probe parity on the routes that differ.
Any browser-side failure (blank page, ChunkLoadError, failing fetch): probe errors reads the console and response bodies directly.

Setup: run /probe once to scaffold ~/.pi/probe.json, fill in URLs + test credentials. Keep real user credentials out of it; use dedicated test accounts.

jira

Jira over the plain REST API with an API token. Exists because the Atlassian MCP kept breaking OAuth and, worse, cannot see images attached to cards; this downloads attachments and hands them to the model as real images.

What it does

get pulls a card into context: summary, status, assignee, description (ADF converted to readable text), comments, and attachment images (downloaded with auth, downscaled, attached to the tool result so the model can read screenshots and mockups).
search runs a JQL query, comment adds a comment, create makes a new card (optionally under a parent/epic).
/jira SXCL-1234 pulls a card into the conversation. /jira start SXCL-1234 also has the agent create the branch off latest main (both repos in a paired-repo workspace). /jira verify [KEY] audits the current branch against the card's acceptance criteria and reports covered / partial / missing; the key defaults to the ticket id in the branch name.

How it works

Config in ~/.pi/jira.json (chmod 600): site URL, account email, API token from https://id.atlassian.com/manage-profile/security/api-tokens. /jira auth prompts for the three values and validates them against /myself before saving. Descriptions and comments arrive as Atlassian Document Format and are converted to markdown-ish text (headings, lists, code blocks, tables, mentions, task lists).

When to use it

Any time a ticket id comes up: the model is prompted to fetch cards itself rather than asking for a paste.
Start-of-work ritual: /jira start KEY = branch + requirements checklist in one step.
Before opening the PR: /jira verify catches the "card asked for three things, branch does two" gap.

scope-guard

Structural enforcement of "only touch what the task is about". Exists because agents (especially delegated workers) kept editing files outside scope and staging junk like .pnpm-store/ into PRs.

What it does

Always on: edit/write into node_modules/, .pnpm-store/, or .git/ is blocked outright.
After every git add / git commit the staged file list is checked; junk paths (dist/, build/, .next/, .turbo/, coverage/, .DS_Store, *.log, plus the hard list) and out-of-scope files produce a warning appended to the bash tool result, so the model sees it and unstages before committing. You also get a UI notification.
With a declared scope, any edit/write outside it is blocked with a reason the model can read, so it has to ask instead of wandering.

How it works

A tool_call handler (blocking) and a tool_result handler (annotating). Scope is session-local state set by the /scope command: either explicit globs (/scope src/pages/** packages/api/**) or /scope branch, which snapshots the files already changed on the branch (vs merge-base with main) plus current dirty files. /scope off clears it; bare /scope shows it. A footer status chip shows when a scope is active.

When to use it

Junk protection needs nothing; it's on.
Declare a scope at the start of tightly-bounded work ("only the help docs", "only IssuesTracking"), the exact situations where scope creep bit before.

ci

GitHub Actions results for the current branch, in-context. Exists because CI failure logs kept getting copy-pasted by hand.

What it does

ci status lists recent workflow runs on the current branch with conclusions and run ids.
ci logs fetches the failed-step logs of the latest failed run (or a specific runId), truncated to the last 30KB.
/ci asks the model to check the branch, pull failing logs, and identify the root cause before touching anything.

How it works

Thin wrapper over gh run list / gh run view --log-failed executed in the repo cwd. Auth and repo resolution are whatever gh already has.

When to use it

After a push, or the moment anyone says "the check is failing". The model is prompted to reach for it instead of asking for a paste.

devwatch

Dev servers the agent can read, plus port management.

What it does

dev tool: start/stop/restart/list/logs for named dev servers. Servers spawn detached with output teed to ~/.pi/dev-logs/<name>.log, so they survive pi exiting and any session (or another tool) can read the same logs. logs supports errorsOnly (error lines plus stack context) and grep, so the agent pulls fresh errors itself instead of me copy-pasting stack traces.
ports tool: list TCP listeners with pid, command, and project cwd; kill by port or pid. /ports shows a quick toast.

When to use it

Have the agent start dev servers through dev rather than raw bash, then after changes it checks dev logs errorsOnly:true on its own. ports kill replaces "kill whatever is on 3003".

shot

/shot [n] [message] attaches the n most recent screenshots from the macOS screenshot folder (override with PI_SHOT_DIR) to your message, downscaling anything over ~1.5MB. For the times you want to show the agent something faster than describing it. With probe in place, prefer letting the agent take its own screenshots; /shot covers everything probe can't see (native apps, other windows, your phone photo synced to Desktop).

Notes

Secrets: all credentials live outside this repo in ~/.pi/probe.json and ~/.pi/jira.json (0600). Nothing in extensions/ contains a secret.
pi 0.82 image gotcha: tool results and user messages take images as {type:"image", data, mimeType}. Older extensions using the Anthropic-style source wrapper fail silently.
Verification recipe used for these: typecheck with a tsconfig whose paths map the pi package's dist/*.d.ts (moduleResolution bundler, allowImportingTsExtensions), a harness that loads each extension with a fake ExtensionAPI via node --experimental-strip-types, and a real pi -p load.

pi-extensions

Personal extensions for the pi coding agent. Built from an analysis of my own Claude Code and Codex session history: each one automates something I was demonstrably doing by hand, over and over.

Extension	One-liner	Use it when
swarm	Codex review swarms + parallel worktree fix lanes	Before shipping meaningful changes; when fixing a list of independent issues
probe	Headless-browser screenshots, console errors, failed-request bodies	Verifying UI changes, local-vs-staging parity, debugging 4xx/5xx
jira	Jira via REST API token, including card attachment images	Any card-shaped work: start, review, verify against acceptance criteria
scope-guard	Blocks out-of-scope edits and junk commits	Always on; declare a scope for tightly-bounded tasks
ci	Pull GitHub Actions failures for the current branch	A check fails and you'd otherwise paste the log
devwatch	Dev servers with captured logs + port management	Running dev servers the agent should be able to read
shot	Attach recent screenshots to a message	Quickly showing the agent what you see

Install

Copy (or run ./install.sh, which does the same) into pi's user extension directory:

cp extensions/*.ts ~/.pi/agent/extensions/

Pi loads them on next start; /reload picks them up in a running session.

Requirements:

pi >= 0.82 (the ImageContent shape changed in 0.82 to {type, data, mimeType}; these extensions target the new shape)
macOS (uses sips for image downscaling and lsof in devwatch)
Codex CLI authenticated (codex on PATH) for swarm
GitHub CLI authenticated for ci
Chrome, Chromium, Arc, or a Playwright browser cache for probe (it auto-discovers ~/Library/Caches/ms-playwright builds)

No npm installs. Everything runs on Node builtins plus the packages pi already ships (typebox, @earendil-works/pi-ai).

swarm

My own take on pi-subagents + pi-worktree, merged into one pipeline and shaped around a workflow I used to run by hand: fan out independent read-only reviewers over a diff, verify every candidate finding, then fix the confirmed ones in parallel worktrees.

What it does

swarm review spawns one read-only codex exec lane per review angle. Eight angle presets: correctness, removed-behavior, cross-file, conventions, efficiency, reuse, simplification, altitude. Each lane reports up to 6 candidates in a strict line format. Candidates are deduped by file:line, then one verifier lane per candidate re-reads the code and returns CONFIRMED, PLAUSIBLE, or REFUTED with a reason. The aggregated report (confirmed first, ranked by severity) comes back as the tool result and is saved to ~/.pi/swarm/<run-id>/report.md.
swarm fix takes a list of independent items and creates one git worktree per item in a sibling directory <repo>-swarm/<slug> (branch swarm/<slug>), then runs a workspace-write codex lane in each. Lanes are instructed to stay in scope, commit nothing, and end with STATUS: done|partial|blocked — summary. The report shows each lane's status and git diff --stat; you review the worktree diffs and merge what you like.
swarm status / swarm kill / swarm clean inspect the run, kill every lane (including orphans from a crashed session, tracked in ~/.pi/swarm/running.json), and remove all swarm worktrees + branches.

How it works

Lanes are codex exec --json child processes in their own process groups, capped at 4 concurrent (PI_SWARM_CONCURRENCY), logging to ~/.pi/swarm/<run-id>/*.log. A widget above the editor shows lane progress, flags any lane silent for 3+ minutes as stalled, and a 30-minute hard timeout kills runaways. Default model is gpt-5.6-sol (PI_SWARM_MODEL or the model param to override). Reviewers and verifiers run with -s read-only; fix lanes get -s workspace-write scoped to their worktree. No coordination files ever land in the repo.

When to use it

/swarm review (optionally with notes) before committing or opening a PR on anything non-trivial. Add scope:'branch' to review the whole branch instead of the uncommitted diff, and pass both repo paths for paired-repo work.
/swarm fix after you've agreed on a list of independent fixes; the model derives the items from the conversation. One item per independent concern.
Not for single small fixes: the orchestration overhead isn't worth it, just fix it inline.

Commands:/swarm review [notes], /swarm fix [notes], /swarm status, /swarm kill, /swarm clean

probe

Lets the agent look at the running app itself instead of asking me to screenshot, open devtools, or paste network responses. This replaces the highest-volume manual loop in my history: screenshot local, screenshot staging, paste both, repeat.

What it does

snap navigates to a route, screenshots it, and returns the image plus console errors and failed requests (with response bodies) from the load.
parity captures the same route on local and staging and attaches both screenshots, first local then staging, for direct visual comparison.
errors skips the screenshot and just reports console exceptions/errors and failed request bodies, for "why is this 500ing" debugging.
config prints the resolved project config with the password redacted.

How it works

Zero dependencies: it launches an installed Chrome/Chromium with --headless=new --remote-debugging-port=0 and speaks the Chrome DevTools Protocol over Node's built-in WebSocket. If no system browser exists it falls back to the newest "Chrome for Testing" build in the Playwright cache. Base URLs, login credentials, and default routes live per project in ~/.pi/probe.json (created chmod 600 by /probe); projects are matched by cwd prefix. Each project gets a persistent Chrome profile under ~/.pi/probe/profiles/, so a login survives between calls, and when a page redirects to the login form the extension fills the configured selectors (with the native-setter trick so React controlled inputs register) and retries. Screenshots over ~1.5MB are downscaled via sips. A full http(s):// URL as route works without any project config.

When to use it

After UI changes: probe snap the affected route instead of asking "does it look right?".
Local-vs-staging drift: probe parity on the routes that differ.
Any browser-side failure (blank page, ChunkLoadError, failing fetch): probe errors reads the console and response bodies directly.

Setup: run /probe once to scaffold ~/.pi/probe.json, fill in URLs + test credentials. Keep real user credentials out of it; use dedicated test accounts.

jira

Jira over the plain REST API with an API token. Exists because the Atlassian MCP kept breaking OAuth and, worse, cannot see images attached to cards; this downloads attachments and hands them to the model as real images.

What it does

get pulls a card into context: summary, status, assignee, description (ADF converted to readable text), comments, and attachment images (downloaded with auth, downscaled, attached to the tool result so the model can read screenshots and mockups).
search runs a JQL query, comment adds a comment, create makes a new card (optionally under a parent/epic).
/jira SXCL-1234 pulls a card into the conversation. /jira start SXCL-1234 also has the agent create the branch off latest main (both repos in a paired-repo workspace). /jira verify [KEY] audits the current branch against the card's acceptance criteria and reports covered / partial / missing; the key defaults to the ticket id in the branch name.

How it works

Config in ~/.pi/jira.json (chmod 600): site URL, account email, API token from https://id.atlassian.com/manage-profile/security/api-tokens. /jira auth prompts for the three values and validates them against /myself before saving. Descriptions and comments arrive as Atlassian Document Format and are converted to markdown-ish text (headings, lists, code blocks, tables, mentions, task lists).

When to use it

Any time a ticket id comes up: the model is prompted to fetch cards itself rather than asking for a paste.
Start-of-work ritual: /jira start KEY = branch + requirements checklist in one step.
Before opening the PR: /jira verify catches the "card asked for three things, branch does two" gap.

scope-guard

Structural enforcement of "only touch what the task is about". Exists because agents (especially delegated workers) kept editing files outside scope and staging junk like .pnpm-store/ into PRs.

What it does

Always on: edit/write into node_modules/, .pnpm-store/, or .git/ is blocked outright.
After every git add / git commit the staged file list is checked; junk paths (dist/, build/, .next/, .turbo/, coverage/, .DS_Store, *.log, plus the hard list) and out-of-scope files produce a warning appended to the bash tool result, so the model sees it and unstages before committing. You also get a UI notification.
With a declared scope, any edit/write outside it is blocked with a reason the model can read, so it has to ask instead of wandering.

How it works

A tool_call handler (blocking) and a tool_result handler (annotating). Scope is session-local state set by the /scope command: either explicit globs (/scope src/pages/** packages/api/**) or /scope branch, which snapshots the files already changed on the branch (vs merge-base with main) plus current dirty files. /scope off clears it; bare /scope shows it. A footer status chip shows when a scope is active.

When to use it

Junk protection needs nothing; it's on.
Declare a scope at the start of tightly-bounded work ("only the help docs", "only IssuesTracking"), the exact situations where scope creep bit before.

ci

GitHub Actions results for the current branch, in-context. Exists because CI failure logs kept getting copy-pasted by hand.

What it does

ci status lists recent workflow runs on the current branch with conclusions and run ids.
ci logs fetches the failed-step logs of the latest failed run (or a specific runId), truncated to the last 30KB.
/ci asks the model to check the branch, pull failing logs, and identify the root cause before touching anything.

How it works

Thin wrapper over gh run list / gh run view --log-failed executed in the repo cwd. Auth and repo resolution are whatever gh already has.

When to use it

After a push, or the moment anyone says "the check is failing". The model is prompted to reach for it instead of asking for a paste.

devwatch

Dev servers the agent can read, plus port management.

What it does

dev tool: start/stop/restart/list/logs for named dev servers. Servers spawn detached with output teed to ~/.pi/dev-logs/<name>.log, so they survive pi exiting and any session (or another tool) can read the same logs. logs supports errorsOnly (error lines plus stack context) and grep, so the agent pulls fresh errors itself instead of me copy-pasting stack traces.
ports tool: list TCP listeners with pid, command, and project cwd; kill by port or pid. /ports shows a quick toast.

When to use it

Have the agent start dev servers through dev rather than raw bash, then after changes it checks dev logs errorsOnly:true on its own. ports kill replaces "kill whatever is on 3003".

shot

/shot [n] [message] attaches the n most recent screenshots from the macOS screenshot folder (override with PI_SHOT_DIR) to your message, downscaling anything over ~1.5MB. For the times you want to show the agent something faster than describing it. With probe in place, prefer letting the agent take its own screenshots; /shot covers everything probe can't see (native apps, other windows, your phone photo synced to Desktop).

Notes

Secrets: all credentials live outside this repo in ~/.pi/probe.json and ~/.pi/jira.json (0600). Nothing in extensions/ contains a secret.
pi 0.82 image gotcha: tool results and user messages take images as {type:"image", data, mimeType}. Older extensions using the Anthropic-style source wrapper fail silently.
Verification recipe used for these: typecheck with a tsconfig whose paths map the pi package's dist/*.d.ts (moduleResolution bundler, allowImportingTsExtensions), a harness that loads each extension with a fake ExtensionAPI via node --experimental-strip-types, and a real pi -p load.

pi-extensions

Personal extensions for the pi coding agent. Built from an analysis of my own Claude Code and Codex session history: each one automates something I was demonstrably doing by hand, over and over.

Extension	One-liner	Use it when
swarm	Codex review swarms + parallel worktree fix lanes	Before shipping meaningful changes; when fixing a list of independent issues
probe	Headless-browser screenshots, console errors, failed-request bodies	Verifying UI changes, local-vs-staging parity, debugging 4xx/5xx
jira	Jira via REST API token, including card attachment images	Any card-shaped work: start, review, verify against acceptance criteria
scope-guard	Blocks out-of-scope edits and junk commits	Always on; declare a scope for tightly-bounded tasks
ci	Pull GitHub Actions failures for the current branch	A check fails and you'd otherwise paste the log
devwatch	Dev servers with captured logs + port management	Running dev servers the agent should be able to read
shot	Attach recent screenshots to a message	Quickly showing the agent what you see

Install

Copy (or run ./install.sh, which does the same) into pi's user extension directory:

cp extensions/*.ts ~/.pi/agent/extensions/

Pi loads them on next start; /reload picks them up in a running session.

Requirements:

pi >= 0.82 (the ImageContent shape changed in 0.82 to {type, data, mimeType}; these extensions target the new shape)
macOS (uses sips for image downscaling and lsof in devwatch)
Codex CLI authenticated (codex on PATH) for swarm
GitHub CLI authenticated for ci
Chrome, Chromium, Arc, or a Playwright browser cache for probe (it auto-discovers ~/Library/Caches/ms-playwright builds)

No npm installs. Everything runs on Node builtins plus the packages pi already ships (typebox, @earendil-works/pi-ai).

swarm

My own take on pi-subagents + pi-worktree, merged into one pipeline and shaped around a workflow I used to run by hand: fan out independent read-only reviewers over a diff, verify every candidate finding, then fix the confirmed ones in parallel worktrees.

What it does

swarm review spawns one read-only codex exec lane per review angle. Eight angle presets: correctness, removed-behavior, cross-file, conventions, efficiency, reuse, simplification, altitude. Each lane reports up to 6 candidates in a strict line format. Candidates are deduped by file:line, then one verifier lane per candidate re-reads the code and returns CONFIRMED, PLAUSIBLE, or REFUTED with a reason. The aggregated report (confirmed first, ranked by severity) comes back as the tool result and is saved to ~/.pi/swarm/<run-id>/report.md.
swarm fix takes a list of independent items and creates one git worktree per item in a sibling directory <repo>-swarm/<slug> (branch swarm/<slug>), then runs a workspace-write codex lane in each. Lanes are instructed to stay in scope, commit nothing, and end with STATUS: done|partial|blocked — summary. The report shows each lane's status and git diff --stat; you review the worktree diffs and merge what you like.
swarm status / swarm kill / swarm clean inspect the run, kill every lane (including orphans from a crashed session, tracked in ~/.pi/swarm/running.json), and remove all swarm worktrees + branches.

How it works

Lanes are codex exec --json child processes in their own process groups, capped at 4 concurrent (PI_SWARM_CONCURRENCY), logging to ~/.pi/swarm/<run-id>/*.log. A widget above the editor shows lane progress, flags any lane silent for 3+ minutes as stalled, and a 30-minute hard timeout kills runaways. Default model is gpt-5.6-sol (PI_SWARM_MODEL or the model param to override). Reviewers and verifiers run with -s read-only; fix lanes get -s workspace-write scoped to their worktree. No coordination files ever land in the repo.

When to use it

/swarm review (optionally with notes) before committing or opening a PR on anything non-trivial. Add scope:'branch' to review the whole branch instead of the uncommitted diff, and pass both repo paths for paired-repo work.
/swarm fix after you've agreed on a list of independent fixes; the model derives the items from the conversation. One item per independent concern.
Not for single small fixes: the orchestration overhead isn't worth it, just fix it inline.

Commands:/swarm review [notes], /swarm fix [notes], /swarm status, /swarm kill, /swarm clean

probe

Lets the agent look at the running app itself instead of asking me to screenshot, open devtools, or paste network responses. This replaces the highest-volume manual loop in my history: screenshot local, screenshot staging, paste both, repeat.

What it does

snap navigates to a route, screenshots it, and returns the image plus console errors and failed requests (with response bodies) from the load.
parity captures the same route on local and staging and attaches both screenshots, first local then staging, for direct visual comparison.
errors skips the screenshot and just reports console exceptions/errors and failed request bodies, for "why is this 500ing" debugging.
config prints the resolved project config with the password redacted.

How it works

Zero dependencies: it launches an installed Chrome/Chromium with --headless=new --remote-debugging-port=0 and speaks the Chrome DevTools Protocol over Node's built-in WebSocket. If no system browser exists it falls back to the newest "Chrome for Testing" build in the Playwright cache. Base URLs, login credentials, and default routes live per project in ~/.pi/probe.json (created chmod 600 by /probe); projects are matched by cwd prefix. Each project gets a persistent Chrome profile under ~/.pi/probe/profiles/, so a login survives between calls, and when a page redirects to the login form the extension fills the configured selectors (with the native-setter trick so React controlled inputs register) and retries. Screenshots over ~1.5MB are downscaled via sips. A full http(s):// URL as route works without any project config.

When to use it

After UI changes: probe snap the affected route instead of asking "does it look right?".
Local-vs-staging drift: probe parity on the routes that differ.
Any browser-side failure (blank page, ChunkLoadError, failing fetch): probe errors reads the console and response bodies directly.

Setup: run /probe once to scaffold ~/.pi/probe.json, fill in URLs + test credentials. Keep real user credentials out of it; use dedicated test accounts.

jira

Jira over the plain REST API with an API token. Exists because the Atlassian MCP kept breaking OAuth and, worse, cannot see images attached to cards; this downloads attachments and hands them to the model as real images.

What it does

get pulls a card into context: summary, status, assignee, description (ADF converted to readable text), comments, and attachment images (downloaded with auth, downscaled, attached to the tool result so the model can read screenshots and mockups).
search runs a JQL query, comment adds a comment, create makes a new card (optionally under a parent/epic).
/jira SXCL-1234 pulls a card into the conversation. /jira start SXCL-1234 also has the agent create the branch off latest main (both repos in a paired-repo workspace). /jira verify [KEY] audits the current branch against the card's acceptance criteria and reports covered / partial / missing; the key defaults to the ticket id in the branch name.

How it works

Config in ~/.pi/jira.json (chmod 600): site URL, account email, API token from https://id.atlassian.com/manage-profile/security/api-tokens. /jira auth prompts for the three values and validates them against /myself before saving. Descriptions and comments arrive as Atlassian Document Format and are converted to markdown-ish text (headings, lists, code blocks, tables, mentions, task lists).

When to use it

Any time a ticket id comes up: the model is prompted to fetch cards itself rather than asking for a paste.
Start-of-work ritual: /jira start KEY = branch + requirements checklist in one step.
Before opening the PR: /jira verify catches the "card asked for three things, branch does two" gap.

scope-guard

Structural enforcement of "only touch what the task is about". Exists because agents (especially delegated workers) kept editing files outside scope and staging junk like .pnpm-store/ into PRs.

What it does

Always on: edit/write into node_modules/, .pnpm-store/, or .git/ is blocked outright.
After every git add / git commit the staged file list is checked; junk paths (dist/, build/, .next/, .turbo/, coverage/, .DS_Store, *.log, plus the hard list) and out-of-scope files produce a warning appended to the bash tool result, so the model sees it and unstages before committing. You also get a UI notification.
With a declared scope, any edit/write outside it is blocked with a reason the model can read, so it has to ask instead of wandering.

How it works

A tool_call handler (blocking) and a tool_result handler (annotating). Scope is session-local state set by the /scope command: either explicit globs (/scope src/pages/** packages/api/**) or /scope branch, which snapshots the files already changed on the branch (vs merge-base with main) plus current dirty files. /scope off clears it; bare /scope shows it. A footer status chip shows when a scope is active.

When to use it

Junk protection needs nothing; it's on.
Declare a scope at the start of tightly-bounded work ("only the help docs", "only IssuesTracking"), the exact situations where scope creep bit before.

ci

GitHub Actions results for the current branch, in-context. Exists because CI failure logs kept getting copy-pasted by hand.

What it does

ci status lists recent workflow runs on the current branch with conclusions and run ids.
ci logs fetches the failed-step logs of the latest failed run (or a specific runId), truncated to the last 30KB.
/ci asks the model to check the branch, pull failing logs, and identify the root cause before touching anything.

How it works

Thin wrapper over gh run list / gh run view --log-failed executed in the repo cwd. Auth and repo resolution are whatever gh already has.

When to use it

After a push, or the moment anyone says "the check is failing". The model is prompted to reach for it instead of asking for a paste.

devwatch

Dev servers the agent can read, plus port management.

What it does

dev tool: start/stop/restart/list/logs for named dev servers. Servers spawn detached with output teed to ~/.pi/dev-logs/<name>.log, so they survive pi exiting and any session (or another tool) can read the same logs. logs supports errorsOnly (error lines plus stack context) and grep, so the agent pulls fresh errors itself instead of me copy-pasting stack traces.
ports tool: list TCP listeners with pid, command, and project cwd; kill by port or pid. /ports shows a quick toast.

When to use it

Have the agent start dev servers through dev rather than raw bash, then after changes it checks dev logs errorsOnly:true on its own. ports kill replaces "kill whatever is on 3003".

shot

/shot [n] [message] attaches the n most recent screenshots from the macOS screenshot folder (override with PI_SHOT_DIR) to your message, downscaling anything over ~1.5MB. For the times you want to show the agent something faster than describing it. With probe in place, prefer letting the agent take its own screenshots; /shot covers everything probe can't see (native apps, other windows, your phone photo synced to Desktop).

Notes

Secrets: all credentials live outside this repo in ~/.pi/probe.json and ~/.pi/jira.json (0600). Nothing in extensions/ contains a secret.
pi 0.82 image gotcha: tool results and user messages take images as {type:"image", data, mimeType}. Older extensions using the Anthropic-style source wrapper fail silently.
Verification recipe used for these: typecheck with a tsconfig whose paths map the pi package's dist/*.d.ts (moduleResolution bundler, allowImportingTsExtensions), a harness that loads each extension with a fake ExtensionAPI via node --experimental-strip-types, and a real pi -p load.

pi-extensions

Personal extensions for the pi coding agent. Built from an analysis of my own Claude Code and Codex session history: each one automates something I was demonstrably doing by hand, over and over.

Extension	One-liner	Use it when
swarm	Codex review swarms + parallel worktree fix lanes	Before shipping meaningful changes; when fixing a list of independent issues
probe	Headless-browser screenshots, console errors, failed-request bodies	Verifying UI changes, local-vs-staging parity, debugging 4xx/5xx
jira	Jira via REST API token, including card attachment images	Any card-shaped work: start, review, verify against acceptance criteria
scope-guard	Blocks out-of-scope edits and junk commits	Always on; declare a scope for tightly-bounded tasks
ci	Pull GitHub Actions failures for the current branch	A check fails and you'd otherwise paste the log
devwatch	Dev servers with captured logs + port management	Running dev servers the agent should be able to read
shot	Attach recent screenshots to a message	Quickly showing the agent what you see

Install

Copy (or run ./install.sh, which does the same) into pi's user extension directory:

cp extensions/*.ts ~/.pi/agent/extensions/

Pi loads them on next start; /reload picks them up in a running session.

Requirements:

pi >= 0.82 (the ImageContent shape changed in 0.82 to {type, data, mimeType}; these extensions target the new shape)
macOS (uses sips for image downscaling and lsof in devwatch)
Codex CLI authenticated (codex on PATH) for swarm
GitHub CLI authenticated for ci
Chrome, Chromium, Arc, or a Playwright browser cache for probe (it auto-discovers ~/Library/Caches/ms-playwright builds)

No npm installs. Everything runs on Node builtins plus the packages pi already ships (typebox, @earendil-works/pi-ai).

swarm

My own take on pi-subagents + pi-worktree, merged into one pipeline and shaped around a workflow I used to run by hand: fan out independent read-only reviewers over a diff, verify every candidate finding, then fix the confirmed ones in parallel worktrees.

What it does

swarm review spawns one read-only codex exec lane per review angle. Eight angle presets: correctness, removed-behavior, cross-file, conventions, efficiency, reuse, simplification, altitude. Each lane reports up to 6 candidates in a strict line format. Candidates are deduped by file:line, then one verifier lane per candidate re-reads the code and returns CONFIRMED, PLAUSIBLE, or REFUTED with a reason. The aggregated report (confirmed first, ranked by severity) comes back as the tool result and is saved to ~/.pi/swarm/<run-id>/report.md.
swarm fix takes a list of independent items and creates one git worktree per item in a sibling directory <repo>-swarm/<slug> (branch swarm/<slug>), then runs a workspace-write codex lane in each. Lanes are instructed to stay in scope, commit nothing, and end with STATUS: done|partial|blocked — summary. The report shows each lane's status and git diff --stat; you review the worktree diffs and merge what you like.
swarm status / swarm kill / swarm clean inspect the run, kill every lane (including orphans from a crashed session, tracked in ~/.pi/swarm/running.json), and remove all swarm worktrees + branches.

How it works

Lanes are codex exec --json child processes in their own process groups, capped at 4 concurrent (PI_SWARM_CONCURRENCY), logging to ~/.pi/swarm/<run-id>/*.log. A widget above the editor shows lane progress, flags any lane silent for 3+ minutes as stalled, and a 30-minute hard timeout kills runaways. Default model is gpt-5.6-sol (PI_SWARM_MODEL or the model param to override). Reviewers and verifiers run with -s read-only; fix lanes get -s workspace-write scoped to their worktree. No coordination files ever land in the repo.

When to use it

/swarm review (optionally with notes) before committing or opening a PR on anything non-trivial. Add scope:'branch' to review the whole branch instead of the uncommitted diff, and pass both repo paths for paired-repo work.
/swarm fix after you've agreed on a list of independent fixes; the model derives the items from the conversation. One item per independent concern.
Not for single small fixes: the orchestration overhead isn't worth it, just fix it inline.

Commands:/swarm review [notes], /swarm fix [notes], /swarm status, /swarm kill, /swarm clean

probe

Lets the agent look at the running app itself instead of asking me to screenshot, open devtools, or paste network responses. This replaces the highest-volume manual loop in my history: screenshot local, screenshot staging, paste both, repeat.

What it does

snap navigates to a route, screenshots it, and returns the image plus console errors and failed requests (with response bodies) from the load.
parity captures the same route on local and staging and attaches both screenshots, first local then staging, for direct visual comparison.
errors skips the screenshot and just reports console exceptions/errors and failed request bodies, for "why is this 500ing" debugging.
config prints the resolved project config with the password redacted.

How it works

Zero dependencies: it launches an installed Chrome/Chromium with --headless=new --remote-debugging-port=0 and speaks the Chrome DevTools Protocol over Node's built-in WebSocket. If no system browser exists it falls back to the newest "Chrome for Testing" build in the Playwright cache. Base URLs, login credentials, and default routes live per project in ~/.pi/probe.json (created chmod 600 by /probe); projects are matched by cwd prefix. Each project gets a persistent Chrome profile under ~/.pi/probe/profiles/, so a login survives between calls, and when a page redirects to the login form the extension fills the configured selectors (with the native-setter trick so React controlled inputs register) and retries. Screenshots over ~1.5MB are downscaled via sips. A full http(s):// URL as route works without any project config.

When to use it

After UI changes: probe snap the affected route instead of asking "does it look right?".
Local-vs-staging drift: probe parity on the routes that differ.
Any browser-side failure (blank page, ChunkLoadError, failing fetch): probe errors reads the console and response bodies directly.

Setup: run /probe once to scaffold ~/.pi/probe.json, fill in URLs + test credentials. Keep real user credentials out of it; use dedicated test accounts.

jira

Jira over the plain REST API with an API token. Exists because the Atlassian MCP kept breaking OAuth and, worse, cannot see images attached to cards; this downloads attachments and hands them to the model as real images.

What it does

get pulls a card into context: summary, status, assignee, description (ADF converted to readable text), comments, and attachment images (downloaded with auth, downscaled, attached to the tool result so the model can read screenshots and mockups).
search runs a JQL query, comment adds a comment, create makes a new card (optionally under a parent/epic).
/jira SXCL-1234 pulls a card into the conversation. /jira start SXCL-1234 also has the agent create the branch off latest main (both repos in a paired-repo workspace). /jira verify [KEY] audits the current branch against the card's acceptance criteria and reports covered / partial / missing; the key defaults to the ticket id in the branch name.

How it works

Config in ~/.pi/jira.json (chmod 600): site URL, account email, API token from https://id.atlassian.com/manage-profile/security/api-tokens. /jira auth prompts for the three values and validates them against /myself before saving. Descriptions and comments arrive as Atlassian Document Format and are converted to markdown-ish text (headings, lists, code blocks, tables, mentions, task lists).

When to use it

Any time a ticket id comes up: the model is prompted to fetch cards itself rather than asking for a paste.
Start-of-work ritual: /jira start KEY = branch + requirements checklist in one step.
Before opening the PR: /jira verify catches the "card asked for three things, branch does two" gap.

scope-guard

Structural enforcement of "only touch what the task is about". Exists because agents (especially delegated workers) kept editing files outside scope and staging junk like .pnpm-store/ into PRs.

What it does

Always on: edit/write into node_modules/, .pnpm-store/, or .git/ is blocked outright.
After every git add / git commit the staged file list is checked; junk paths (dist/, build/, .next/, .turbo/, coverage/, .DS_Store, *.log, plus the hard list) and out-of-scope files produce a warning appended to the bash tool result, so the model sees it and unstages before committing. You also get a UI notification.
With a declared scope, any edit/write outside it is blocked with a reason the model can read, so it has to ask instead of wandering.

How it works

A tool_call handler (blocking) and a tool_result handler (annotating). Scope is session-local state set by the /scope command: either explicit globs (/scope src/pages/** packages/api/**) or /scope branch, which snapshots the files already changed on the branch (vs merge-base with main) plus current dirty files. /scope off clears it; bare /scope shows it. A footer status chip shows when a scope is active.

When to use it

Junk protection needs nothing; it's on.
Declare a scope at the start of tightly-bounded work ("only the help docs", "only IssuesTracking"), the exact situations where scope creep bit before.

ci

GitHub Actions results for the current branch, in-context. Exists because CI failure logs kept getting copy-pasted by hand.

What it does

ci status lists recent workflow runs on the current branch with conclusions and run ids.
ci logs fetches the failed-step logs of the latest failed run (or a specific runId), truncated to the last 30KB.
/ci asks the model to check the branch, pull failing logs, and identify the root cause before touching anything.

How it works

Thin wrapper over gh run list / gh run view --log-failed executed in the repo cwd. Auth and repo resolution are whatever gh already has.

When to use it

After a push, or the moment anyone says "the check is failing". The model is prompted to reach for it instead of asking for a paste.

devwatch

Dev servers the agent can read, plus port management.

What it does

dev tool: start/stop/restart/list/logs for named dev servers. Servers spawn detached with output teed to ~/.pi/dev-logs/<name>.log, so they survive pi exiting and any session (or another tool) can read the same logs. logs supports errorsOnly (error lines plus stack context) and grep, so the agent pulls fresh errors itself instead of me copy-pasting stack traces.
ports tool: list TCP listeners with pid, command, and project cwd; kill by port or pid. /ports shows a quick toast.

When to use it

Have the agent start dev servers through dev rather than raw bash, then after changes it checks dev logs errorsOnly:true on its own. ports kill replaces "kill whatever is on 3003".

shot

/shot [n] [message] attaches the n most recent screenshots from the macOS screenshot folder (override with PI_SHOT_DIR) to your message, downscaling anything over ~1.5MB. For the times you want to show the agent something faster than describing it. With probe in place, prefer letting the agent take its own screenshots; /shot covers everything probe can't see (native apps, other windows, your phone photo synced to Desktop).

Notes

Secrets: all credentials live outside this repo in ~/.pi/probe.json and ~/.pi/jira.json (0600). Nothing in extensions/ contains a secret.
pi 0.82 image gotcha: tool results and user messages take images as {type:"image", data, mimeType}. Older extensions using the Anthropic-style source wrapper fail silently.
Verification recipe used for these: typecheck with a tsconfig whose paths map the pi package's dist/*.d.ts (moduleResolution bundler, allowImportingTsExtensions), a harness that loads each extension with a fake ExtensionAPI via node --experimental-strip-types, and a real pi -p load.

pi-extensions

Personal extensions for the pi coding agent. Built from an analysis of my own Claude Code and Codex session history: each one automates something I was demonstrably doing by hand, over and over.

Extension	One-liner	Use it when
swarm	Codex review swarms + parallel worktree fix lanes	Before shipping meaningful changes; when fixing a list of independent issues
probe	Headless-browser screenshots, console errors, failed-request bodies	Verifying UI changes, local-vs-staging parity, debugging 4xx/5xx
jira	Jira via REST API token, including card attachment images	Any card-shaped work: start, review, verify against acceptance criteria
scope-guard	Blocks out-of-scope edits and junk commits	Always on; declare a scope for tightly-bounded tasks
ci	Pull GitHub Actions failures for the current branch	A check fails and you'd otherwise paste the log
devwatch	Dev servers with captured logs + port management	Running dev servers the agent should be able to read
shot	Attach recent screenshots to a message	Quickly showing the agent what you see

Install

Copy (or run ./install.sh, which does the same) into pi's user extension directory:

cp extensions/*.ts ~/.pi/agent/extensions/

Pi loads them on next start; /reload picks them up in a running session.

Requirements:

pi >= 0.82 (the ImageContent shape changed in 0.82 to {type, data, mimeType}; these extensions target the new shape)
macOS (uses sips for image downscaling and lsof in devwatch)
Codex CLI authenticated (codex on PATH) for swarm
GitHub CLI authenticated for ci
Chrome, Chromium, Arc, or a Playwright browser cache for probe (it auto-discovers ~/Library/Caches/ms-playwright builds)

No npm installs. Everything runs on Node builtins plus the packages pi already ships (typebox, @earendil-works/pi-ai).

swarm

My own take on pi-subagents + pi-worktree, merged into one pipeline and shaped around a workflow I used to run by hand: fan out independent read-only reviewers over a diff, verify every candidate finding, then fix the confirmed ones in parallel worktrees.

What it does

swarm review spawns one read-only codex exec lane per review angle. Eight angle presets: correctness, removed-behavior, cross-file, conventions, efficiency, reuse, simplification, altitude. Each lane reports up to 6 candidates in a strict line format. Candidates are deduped by file:line, then one verifier lane per candidate re-reads the code and returns CONFIRMED, PLAUSIBLE, or REFUTED with a reason. The aggregated report (confirmed first, ranked by severity) comes back as the tool result and is saved to ~/.pi/swarm/<run-id>/report.md.
swarm fix takes a list of independent items and creates one git worktree per item in a sibling directory <repo>-swarm/<slug> (branch swarm/<slug>), then runs a workspace-write codex lane in each. Lanes are instructed to stay in scope, commit nothing, and end with STATUS: done|partial|blocked — summary. The report shows each lane's status and git diff --stat; you review the worktree diffs and merge what you like.
swarm status / swarm kill / swarm clean inspect the run, kill every lane (including orphans from a crashed session, tracked in ~/.pi/swarm/running.json), and remove all swarm worktrees + branches.

How it works

Lanes are codex exec --json child processes in their own process groups, capped at 4 concurrent (PI_SWARM_CONCURRENCY), logging to ~/.pi/swarm/<run-id>/*.log. A widget above the editor shows lane progress, flags any lane silent for 3+ minutes as stalled, and a 30-minute hard timeout kills runaways. Default model is gpt-5.6-sol (PI_SWARM_MODEL or the model param to override). Reviewers and verifiers run with -s read-only; fix lanes get -s workspace-write scoped to their worktree. No coordination files ever land in the repo.

When to use it

/swarm review (optionally with notes) before committing or opening a PR on anything non-trivial. Add scope:'branch' to review the whole branch instead of the uncommitted diff, and pass both repo paths for paired-repo work.
/swarm fix after you've agreed on a list of independent fixes; the model derives the items from the conversation. One item per independent concern.
Not for single small fixes: the orchestration overhead isn't worth it, just fix it inline.

Commands:/swarm review [notes], /swarm fix [notes], /swarm status, /swarm kill, /swarm clean

probe

Lets the agent look at the running app itself instead of asking me to screenshot, open devtools, or paste network responses. This replaces the highest-volume manual loop in my history: screenshot local, screenshot staging, paste both, repeat.

What it does

snap navigates to a route, screenshots it, and returns the image plus console errors and failed requests (with response bodies) from the load.
parity captures the same route on local and staging and attaches both screenshots, first local then staging, for direct visual comparison.
errors skips the screenshot and just reports console exceptions/errors and failed request bodies, for "why is this 500ing" debugging.
config prints the resolved project config with the password redacted.

How it works

Zero dependencies: it launches an installed Chrome/Chromium with --headless=new --remote-debugging-port=0 and speaks the Chrome DevTools Protocol over Node's built-in WebSocket. If no system browser exists it falls back to the newest "Chrome for Testing" build in the Playwright cache. Base URLs, login credentials, and default routes live per project in ~/.pi/probe.json (created chmod 600 by /probe); projects are matched by cwd prefix. Each project gets a persistent Chrome profile under ~/.pi/probe/profiles/, so a login survives between calls, and when a page redirects to the login form the extension fills the configured selectors (with the native-setter trick so React controlled inputs register) and retries. Screenshots over ~1.5MB are downscaled via sips. A full http(s):// URL as route works without any project config.

When to use it

After UI changes: probe snap the affected route instead of asking "does it look right?".
Local-vs-staging drift: probe parity on the routes that differ.
Any browser-side failure (blank page, ChunkLoadError, failing fetch): probe errors reads the console and response bodies directly.

Setup: run /probe once to scaffold ~/.pi/probe.json, fill in URLs + test credentials. Keep real user credentials out of it; use dedicated test accounts.

jira

Jira over the plain REST API with an API token. Exists because the Atlassian MCP kept breaking OAuth and, worse, cannot see images attached to cards; this downloads attachments and hands them to the model as real images.

What it does

get pulls a card into context: summary, status, assignee, description (ADF converted to readable text), comments, and attachment images (downloaded with auth, downscaled, attached to the tool result so the model can read screenshots and mockups).
search runs a JQL query, comment adds a comment, create makes a new card (optionally under a parent/epic).
/jira SXCL-1234 pulls a card into the conversation. /jira start SXCL-1234 also has the agent create the branch off latest main (both repos in a paired-repo workspace). /jira verify [KEY] audits the current branch against the card's acceptance criteria and reports covered / partial / missing; the key defaults to the ticket id in the branch name.

How it works

Config in ~/.pi/jira.json (chmod 600): site URL, account email, API token from https://id.atlassian.com/manage-profile/security/api-tokens. /jira auth prompts for the three values and validates them against /myself before saving. Descriptions and comments arrive as Atlassian Document Format and are converted to markdown-ish text (headings, lists, code blocks, tables, mentions, task lists).

When to use it

Any time a ticket id comes up: the model is prompted to fetch cards itself rather than asking for a paste.
Start-of-work ritual: /jira start KEY = branch + requirements checklist in one step.
Before opening the PR: /jira verify catches the "card asked for three things, branch does two" gap.

scope-guard

Structural enforcement of "only touch what the task is about". Exists because agents (especially delegated workers) kept editing files outside scope and staging junk like .pnpm-store/ into PRs.

What it does

Always on: edit/write into node_modules/, .pnpm-store/, or .git/ is blocked outright.
After every git add / git commit the staged file list is checked; junk paths (dist/, build/, .next/, .turbo/, coverage/, .DS_Store, *.log, plus the hard list) and out-of-scope files produce a warning appended to the bash tool result, so the model sees it and unstages before committing. You also get a UI notification.
With a declared scope, any edit/write outside it is blocked with a reason the model can read, so it has to ask instead of wandering.

How it works

A tool_call handler (blocking) and a tool_result handler (annotating). Scope is session-local state set by the /scope command: either explicit globs (/scope src/pages/** packages/api/**) or /scope branch, which snapshots the files already changed on the branch (vs merge-base with main) plus current dirty files. /scope off clears it; bare /scope shows it. A footer status chip shows when a scope is active.

When to use it

Junk protection needs nothing; it's on.
Declare a scope at the start of tightly-bounded work ("only the help docs", "only IssuesTracking"), the exact situations where scope creep bit before.

ci

GitHub Actions results for the current branch, in-context. Exists because CI failure logs kept getting copy-pasted by hand.

What it does

ci status lists recent workflow runs on the current branch with conclusions and run ids.
ci logs fetches the failed-step logs of the latest failed run (or a specific runId), truncated to the last 30KB.
/ci asks the model to check the branch, pull failing logs, and identify the root cause before touching anything.

How it works

Thin wrapper over gh run list / gh run view --log-failed executed in the repo cwd. Auth and repo resolution are whatever gh already has.

When to use it

After a push, or the moment anyone says "the check is failing". The model is prompted to reach for it instead of asking for a paste.

devwatch

Dev servers the agent can read, plus port management.

What it does

dev tool: start/stop/restart/list/logs for named dev servers. Servers spawn detached with output teed to ~/.pi/dev-logs/<name>.log, so they survive pi exiting and any session (or another tool) can read the same logs. logs supports errorsOnly (error lines plus stack context) and grep, so the agent pulls fresh errors itself instead of me copy-pasting stack traces.
ports tool: list TCP listeners with pid, command, and project cwd; kill by port or pid. /ports shows a quick toast.

When to use it

Have the agent start dev servers through dev rather than raw bash, then after changes it checks dev logs errorsOnly:true on its own. ports kill replaces "kill whatever is on 3003".

shot

/shot [n] [message] attaches the n most recent screenshots from the macOS screenshot folder (override with PI_SHOT_DIR) to your message, downscaling anything over ~1.5MB. For the times you want to show the agent something faster than describing it. With probe in place, prefer letting the agent take its own screenshots; /shot covers everything probe can't see (native apps, other windows, your phone photo synced to Desktop).

Notes

Secrets: all credentials live outside this repo in ~/.pi/probe.json and ~/.pi/jira.json (0600). Nothing in extensions/ contains a secret.
pi 0.82 image gotcha: tool results and user messages take images as {type:"image", data, mimeType}. Older extensions using the Anthropic-style source wrapper fail silently.
Verification recipe used for these: typecheck with a tsconfig whose paths map the pi package's dist/*.d.ts (moduleResolution bundler, allowImportingTsExtensions), a harness that loads each extension with a fake ExtensionAPI via node --experimental-strip-types, and a real pi -p load.

pi-extensions

Personal extensions for the pi coding agent. Built from an analysis of my own Claude Code and Codex session history: each one automates something I was demonstrably doing by hand, over and over.

Extension	One-liner	Use it when
swarm	Codex review swarms + parallel worktree fix lanes	Before shipping meaningful changes; when fixing a list of independent issues
probe	Headless-browser screenshots, console errors, failed-request bodies	Verifying UI changes, local-vs-staging parity, debugging 4xx/5xx
jira	Jira via REST API token, including card attachment images	Any card-shaped work: start, review, verify against acceptance criteria
scope-guard	Blocks out-of-scope edits and junk commits	Always on; declare a scope for tightly-bounded tasks
ci	Pull GitHub Actions failures for the current branch	A check fails and you'd otherwise paste the log
devwatch	Dev servers with captured logs + port management	Running dev servers the agent should be able to read
shot	Attach recent screenshots to a message	Quickly showing the agent what you see

Install

Copy (or run ./install.sh, which does the same) into pi's user extension directory:

cp extensions/*.ts ~/.pi/agent/extensions/

Pi loads them on next start; /reload picks them up in a running session.

Requirements:

pi >= 0.82 (the ImageContent shape changed in 0.82 to {type, data, mimeType}; these extensions target the new shape)
macOS (uses sips for image downscaling and lsof in devwatch)
Codex CLI authenticated (codex on PATH) for swarm
GitHub CLI authenticated for ci
Chrome, Chromium, Arc, or a Playwright browser cache for probe (it auto-discovers ~/Library/Caches/ms-playwright builds)

No npm installs. Everything runs on Node builtins plus the packages pi already ships (typebox, @earendil-works/pi-ai).

swarm

My own take on pi-subagents + pi-worktree, merged into one pipeline and shaped around a workflow I used to run by hand: fan out independent read-only reviewers over a diff, verify every candidate finding, then fix the confirmed ones in parallel worktrees.

What it does

swarm review spawns one read-only codex exec lane per review angle. Eight angle presets: correctness, removed-behavior, cross-file, conventions, efficiency, reuse, simplification, altitude. Each lane reports up to 6 candidates in a strict line format. Candidates are deduped by file:line, then one verifier lane per candidate re-reads the code and returns CONFIRMED, PLAUSIBLE, or REFUTED with a reason. The aggregated report (confirmed first, ranked by severity) comes back as the tool result and is saved to ~/.pi/swarm/<run-id>/report.md.
swarm fix takes a list of independent items and creates one git worktree per item in a sibling directory <repo>-swarm/<slug> (branch swarm/<slug>), then runs a workspace-write codex lane in each. Lanes are instructed to stay in scope, commit nothing, and end with STATUS: done|partial|blocked — summary. The report shows each lane's status and git diff --stat; you review the worktree diffs and merge what you like.
swarm status / swarm kill / swarm clean inspect the run, kill every lane (including orphans from a crashed session, tracked in ~/.pi/swarm/running.json), and remove all swarm worktrees + branches.

How it works

Lanes are codex exec --json child processes in their own process groups, capped at 4 concurrent (PI_SWARM_CONCURRENCY), logging to ~/.pi/swarm/<run-id>/*.log. A widget above the editor shows lane progress, flags any lane silent for 3+ minutes as stalled, and a 30-minute hard timeout kills runaways. Default model is gpt-5.6-sol (PI_SWARM_MODEL or the model param to override). Reviewers and verifiers run with -s read-only; fix lanes get -s workspace-write scoped to their worktree. No coordination files ever land in the repo.

When to use it

/swarm review (optionally with notes) before committing or opening a PR on anything non-trivial. Add scope:'branch' to review the whole branch instead of the uncommitted diff, and pass both repo paths for paired-repo work.
/swarm fix after you've agreed on a list of independent fixes; the model derives the items from the conversation. One item per independent concern.
Not for single small fixes: the orchestration overhead isn't worth it, just fix it inline.

Commands:/swarm review [notes], /swarm fix [notes], /swarm status, /swarm kill, /swarm clean

probe

Lets the agent look at the running app itself instead of asking me to screenshot, open devtools, or paste network responses. This replaces the highest-volume manual loop in my history: screenshot local, screenshot staging, paste both, repeat.

What it does

snap navigates to a route, screenshots it, and returns the image plus console errors and failed requests (with response bodies) from the load.
parity captures the same route on local and staging and attaches both screenshots, first local then staging, for direct visual comparison.
errors skips the screenshot and just reports console exceptions/errors and failed request bodies, for "why is this 500ing" debugging.
config prints the resolved project config with the password redacted.

How it works

Zero dependencies: it launches an installed Chrome/Chromium with --headless=new --remote-debugging-port=0 and speaks the Chrome DevTools Protocol over Node's built-in WebSocket. If no system browser exists it falls back to the newest "Chrome for Testing" build in the Playwright cache. Base URLs, login credentials, and default routes live per project in ~/.pi/probe.json (created chmod 600 by /probe); projects are matched by cwd prefix. Each project gets a persistent Chrome profile under ~/.pi/probe/profiles/, so a login survives between calls, and when a page redirects to the login form the extension fills the configured selectors (with the native-setter trick so React controlled inputs register) and retries. Screenshots over ~1.5MB are downscaled via sips. A full http(s):// URL as route works without any project config.

When to use it

After UI changes: probe snap the affected route instead of asking "does it look right?".
Local-vs-staging drift: probe parity on the routes that differ.
Any browser-side failure (blank page, ChunkLoadError, failing fetch): probe errors reads the console and response bodies directly.

Setup: run /probe once to scaffold ~/.pi/probe.json, fill in URLs + test credentials. Keep real user credentials out of it; use dedicated test accounts.

jira

Jira over the plain REST API with an API token. Exists because the Atlassian MCP kept breaking OAuth and, worse, cannot see images attached to cards; this downloads attachments and hands them to the model as real images.

What it does

get pulls a card into context: summary, status, assignee, description (ADF converted to readable text), comments, and attachment images (downloaded with auth, downscaled, attached to the tool result so the model can read screenshots and mockups).
search runs a JQL query, comment adds a comment, create makes a new card (optionally under a parent/epic).
/jira SXCL-1234 pulls a card into the conversation. /jira start SXCL-1234 also has the agent create the branch off latest main (both repos in a paired-repo workspace). /jira verify [KEY] audits the current branch against the card's acceptance criteria and reports covered / partial / missing; the key defaults to the ticket id in the branch name.

How it works

Config in ~/.pi/jira.json (chmod 600): site URL, account email, API token from https://id.atlassian.com/manage-profile/security/api-tokens. /jira auth prompts for the three values and validates them against /myself before saving. Descriptions and comments arrive as Atlassian Document Format and are converted to markdown-ish text (headings, lists, code blocks, tables, mentions, task lists).

When to use it

Any time a ticket id comes up: the model is prompted to fetch cards itself rather than asking for a paste.
Start-of-work ritual: /jira start KEY = branch + requirements checklist in one step.
Before opening the PR: /jira verify catches the "card asked for three things, branch does two" gap.

scope-guard

Structural enforcement of "only touch what the task is about". Exists because agents (especially delegated workers) kept editing files outside scope and staging junk like .pnpm-store/ into PRs.

What it does

Always on: edit/write into node_modules/, .pnpm-store/, or .git/ is blocked outright.
After every git add / git commit the staged file list is checked; junk paths (dist/, build/, .next/, .turbo/, coverage/, .DS_Store, *.log, plus the hard list) and out-of-scope files produce a warning appended to the bash tool result, so the model sees it and unstages before committing. You also get a UI notification.
With a declared scope, any edit/write outside it is blocked with a reason the model can read, so it has to ask instead of wandering.

How it works

A tool_call handler (blocking) and a tool_result handler (annotating). Scope is session-local state set by the /scope command: either explicit globs (/scope src/pages/** packages/api/**) or /scope branch, which snapshots the files already changed on the branch (vs merge-base with main) plus current dirty files. /scope off clears it; bare /scope shows it. A footer status chip shows when a scope is active.

When to use it

Junk protection needs nothing; it's on.
Declare a scope at the start of tightly-bounded work ("only the help docs", "only IssuesTracking"), the exact situations where scope creep bit before.

ci

GitHub Actions results for the current branch, in-context. Exists because CI failure logs kept getting copy-pasted by hand.

What it does

ci status lists recent workflow runs on the current branch with conclusions and run ids.
ci logs fetches the failed-step logs of the latest failed run (or a specific runId), truncated to the last 30KB.
/ci asks the model to check the branch, pull failing logs, and identify the root cause before touching anything.

How it works

Thin wrapper over gh run list / gh run view --log-failed executed in the repo cwd. Auth and repo resolution are whatever gh already has.

When to use it

After a push, or the moment anyone says "the check is failing". The model is prompted to reach for it instead of asking for a paste.

devwatch

Dev servers the agent can read, plus port management.

What it does

dev tool: start/stop/restart/list/logs for named dev servers. Servers spawn detached with output teed to ~/.pi/dev-logs/<name>.log, so they survive pi exiting and any session (or another tool) can read the same logs. logs supports errorsOnly (error lines plus stack context) and grep, so the agent pulls fresh errors itself instead of me copy-pasting stack traces.
ports tool: list TCP listeners with pid, command, and project cwd; kill by port or pid. /ports shows a quick toast.

When to use it

Have the agent start dev servers through dev rather than raw bash, then after changes it checks dev logs errorsOnly:true on its own. ports kill replaces "kill whatever is on 3003".

shot

/shot [n] [message] attaches the n most recent screenshots from the macOS screenshot folder (override with PI_SHOT_DIR) to your message, downscaling anything over ~1.5MB. For the times you want to show the agent something faster than describing it. With probe in place, prefer letting the agent take its own screenshots; /shot covers everything probe can't see (native apps, other windows, your phone photo synced to Desktop).

Notes

Secrets: all credentials live outside this repo in ~/.pi/probe.json and ~/.pi/jira.json (0600). Nothing in extensions/ contains a secret.
pi 0.82 image gotcha: tool results and user messages take images as {type:"image", data, mimeType}. Older extensions using the Anthropic-style source wrapper fail silently.
Verification recipe used for these: typecheck with a tsconfig whose paths map the pi package's dist/*.d.ts (moduleResolution bundler, allowImportingTsExtensions), a harness that loads each extension with a fake ExtensionAPI via node --experimental-strip-types, and a real pi -p load.

pi-extensions

Personal extensions for the pi coding agent. Built from an analysis of my own Claude Code and Codex session history: each one automates something I was demonstrably doing by hand, over and over.

Extension	One-liner	Use it when
swarm	Codex review swarms + parallel worktree fix lanes	Before shipping meaningful changes; when fixing a list of independent issues
probe	Headless-browser screenshots, console errors, failed-request bodies	Verifying UI changes, local-vs-staging parity, debugging 4xx/5xx
jira	Jira via REST API token, including card attachment images	Any card-shaped work: start, review, verify against acceptance criteria
scope-guard	Blocks out-of-scope edits and junk commits	Always on; declare a scope for tightly-bounded tasks
ci	Pull GitHub Actions failures for the current branch	A check fails and you'd otherwise paste the log
devwatch	Dev servers with captured logs + port management	Running dev servers the agent should be able to read
shot	Attach recent screenshots to a message	Quickly showing the agent what you see

Install

Copy (or run ./install.sh, which does the same) into pi's user extension directory:

cp extensions/*.ts ~/.pi/agent/extensions/

Pi loads them on next start; /reload picks them up in a running session.

Requirements:

pi >= 0.82 (the ImageContent shape changed in 0.82 to {type, data, mimeType}; these extensions target the new shape)
macOS (uses sips for image downscaling and lsof in devwatch)
Codex CLI authenticated (codex on PATH) for swarm
GitHub CLI authenticated for ci
Chrome, Chromium, Arc, or a Playwright browser cache for probe (it auto-discovers ~/Library/Caches/ms-playwright builds)

No npm installs. Everything runs on Node builtins plus the packages pi already ships (typebox, @earendil-works/pi-ai).

swarm

My own take on pi-subagents + pi-worktree, merged into one pipeline and shaped around a workflow I used to run by hand: fan out independent read-only reviewers over a diff, verify every candidate finding, then fix the confirmed ones in parallel worktrees.

What it does

swarm review spawns one read-only codex exec lane per review angle. Eight angle presets: correctness, removed-behavior, cross-file, conventions, efficiency, reuse, simplification, altitude. Each lane reports up to 6 candidates in a strict line format. Candidates are deduped by file:line, then one verifier lane per candidate re-reads the code and returns CONFIRMED, PLAUSIBLE, or REFUTED with a reason. The aggregated report (confirmed first, ranked by severity) comes back as the tool result and is saved to ~/.pi/swarm/<run-id>/report.md.
swarm fix takes a list of independent items and creates one git worktree per item in a sibling directory <repo>-swarm/<slug> (branch swarm/<slug>), then runs a workspace-write codex lane in each. Lanes are instructed to stay in scope, commit nothing, and end with STATUS: done|partial|blocked — summary. The report shows each lane's status and git diff --stat; you review the worktree diffs and merge what you like.
swarm status / swarm kill / swarm clean inspect the run, kill every lane (including orphans from a crashed session, tracked in ~/.pi/swarm/running.json), and remove all swarm worktrees + branches.

How it works

Lanes are codex exec --json child processes in their own process groups, capped at 4 concurrent (PI_SWARM_CONCURRENCY), logging to ~/.pi/swarm/<run-id>/*.log. A widget above the editor shows lane progress, flags any lane silent for 3+ minutes as stalled, and a 30-minute hard timeout kills runaways. Default model is gpt-5.6-sol (PI_SWARM_MODEL or the model param to override). Reviewers and verifiers run with -s read-only; fix lanes get -s workspace-write scoped to their worktree. No coordination files ever land in the repo.

When to use it

/swarm review (optionally with notes) before committing or opening a PR on anything non-trivial. Add scope:'branch' to review the whole branch instead of the uncommitted diff, and pass both repo paths for paired-repo work.
/swarm fix after you've agreed on a list of independent fixes; the model derives the items from the conversation. One item per independent concern.
Not for single small fixes: the orchestration overhead isn't worth it, just fix it inline.

Commands:/swarm review [notes], /swarm fix [notes], /swarm status, /swarm kill, /swarm clean

probe

Lets the agent look at the running app itself instead of asking me to screenshot, open devtools, or paste network responses. This replaces the highest-volume manual loop in my history: screenshot local, screenshot staging, paste both, repeat.

What it does

snap navigates to a route, screenshots it, and returns the image plus console errors and failed requests (with response bodies) from the load.
parity captures the same route on local and staging and attaches both screenshots, first local then staging, for direct visual comparison.
errors skips the screenshot and just reports console exceptions/errors and failed request bodies, for "why is this 500ing" debugging.
config prints the resolved project config with the password redacted.

How it works

Zero dependencies: it launches an installed Chrome/Chromium with --headless=new --remote-debugging-port=0 and speaks the Chrome DevTools Protocol over Node's built-in WebSocket. If no system browser exists it falls back to the newest "Chrome for Testing" build in the Playwright cache. Base URLs, login credentials, and default routes live per project in ~/.pi/probe.json (created chmod 600 by /probe); projects are matched by cwd prefix. Each project gets a persistent Chrome profile under ~/.pi/probe/profiles/, so a login survives between calls, and when a page redirects to the login form the extension fills the configured selectors (with the native-setter trick so React controlled inputs register) and retries. Screenshots over ~1.5MB are downscaled via sips. A full http(s):// URL as route works without any project config.

When to use it

After UI changes: probe snap the affected route instead of asking "does it look right?".
Local-vs-staging drift: probe parity on the routes that differ.
Any browser-side failure (blank page, ChunkLoadError, failing fetch): probe errors reads the console and response bodies directly.

Setup: run /probe once to scaffold ~/.pi/probe.json, fill in URLs + test credentials. Keep real user credentials out of it; use dedicated test accounts.

jira

Jira over the plain REST API with an API token. Exists because the Atlassian MCP kept breaking OAuth and, worse, cannot see images attached to cards; this downloads attachments and hands them to the model as real images.

What it does

get pulls a card into context: summary, status, assignee, description (ADF converted to readable text), comments, and attachment images (downloaded with auth, downscaled, attached to the tool result so the model can read screenshots and mockups).
search runs a JQL query, comment adds a comment, create makes a new card (optionally under a parent/epic).
/jira SXCL-1234 pulls a card into the conversation. /jira start SXCL-1234 also has the agent create the branch off latest main (both repos in a paired-repo workspace). /jira verify [KEY] audits the current branch against the card's acceptance criteria and reports covered / partial / missing; the key defaults to the ticket id in the branch name.

How it works

Config in ~/.pi/jira.json (chmod 600): site URL, account email, API token from https://id.atlassian.com/manage-profile/security/api-tokens. /jira auth prompts for the three values and validates them against /myself before saving. Descriptions and comments arrive as Atlassian Document Format and are converted to markdown-ish text (headings, lists, code blocks, tables, mentions, task lists).

When to use it

Any time a ticket id comes up: the model is prompted to fetch cards itself rather than asking for a paste.
Start-of-work ritual: /jira start KEY = branch + requirements checklist in one step.
Before opening the PR: /jira verify catches the "card asked for three things, branch does two" gap.

scope-guard

Structural enforcement of "only touch what the task is about". Exists because agents (especially delegated workers) kept editing files outside scope and staging junk like .pnpm-store/ into PRs.

What it does

Always on: edit/write into node_modules/, .pnpm-store/, or .git/ is blocked outright.
After every git add / git commit the staged file list is checked; junk paths (dist/, build/, .next/, .turbo/, coverage/, .DS_Store, *.log, plus the hard list) and out-of-scope files produce a warning appended to the bash tool result, so the model sees it and unstages before committing. You also get a UI notification.
With a declared scope, any edit/write outside it is blocked with a reason the model can read, so it has to ask instead of wandering.

How it works

A tool_call handler (blocking) and a tool_result handler (annotating). Scope is session-local state set by the /scope command: either explicit globs (/scope src/pages/** packages/api/**) or /scope branch, which snapshots the files already changed on the branch (vs merge-base with main) plus current dirty files. /scope off clears it; bare /scope shows it. A footer status chip shows when a scope is active.

When to use it

Junk protection needs nothing; it's on.
Declare a scope at the start of tightly-bounded work ("only the help docs", "only IssuesTracking"), the exact situations where scope creep bit before.

ci

GitHub Actions results for the current branch, in-context. Exists because CI failure logs kept getting copy-pasted by hand.

What it does

ci status lists recent workflow runs on the current branch with conclusions and run ids.
ci logs fetches the failed-step logs of the latest failed run (or a specific runId), truncated to the last 30KB.
/ci asks the model to check the branch, pull failing logs, and identify the root cause before touching anything.

How it works

Thin wrapper over gh run list / gh run view --log-failed executed in the repo cwd. Auth and repo resolution are whatever gh already has.

When to use it

After a push, or the moment anyone says "the check is failing". The model is prompted to reach for it instead of asking for a paste.

devwatch

Dev servers the agent can read, plus port management.

What it does

dev tool: start/stop/restart/list/logs for named dev servers. Servers spawn detached with output teed to ~/.pi/dev-logs/<name>.log, so they survive pi exiting and any session (or another tool) can read the same logs. logs supports errorsOnly (error lines plus stack context) and grep, so the agent pulls fresh errors itself instead of me copy-pasting stack traces.
ports tool: list TCP listeners with pid, command, and project cwd; kill by port or pid. /ports shows a quick toast.

When to use it

Have the agent start dev servers through dev rather than raw bash, then after changes it checks dev logs errorsOnly:true on its own. ports kill replaces "kill whatever is on 3003".

shot

/shot [n] [message] attaches the n most recent screenshots from the macOS screenshot folder (override with PI_SHOT_DIR) to your message, downscaling anything over ~1.5MB. For the times you want to show the agent something faster than describing it. With probe in place, prefer letting the agent take its own screenshots; /shot covers everything probe can't see (native apps, other windows, your phone photo synced to Desktop).

Notes

Secrets: all credentials live outside this repo in ~/.pi/probe.json and ~/.pi/jira.json (0600). Nothing in extensions/ contains a secret.
pi 0.82 image gotcha: tool results and user messages take images as {type:"image", data, mimeType}. Older extensions using the Anthropic-style source wrapper fail silently.
Verification recipe used for these: typecheck with a tsconfig whose paths map the pi package's dist/*.d.ts (moduleResolution bundler, allowImportingTsExtensions), a harness that loads each extension with a fake ExtensionAPI via node --experimental-strip-types, and a real pi -p load.

Name		Name	Last commit message	Last commit date
extensions		extensions
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh

Name		Name	Last commit message	Last commit date
extensions		extensions
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh

Name		Name	Last commit message	Last commit date
extensions		extensions
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh

Name		Name	Last commit message	Last commit date
extensions		extensions
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh

Name		Name	Last commit message	Last commit date
extensions		extensions
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh

Latest commit

History

Folders and files

Repository files navigation

pi-extensions

Install

swarm

probe

jira

scope-guard

ci

devwatch

shot

Notes

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

pi-extensions

Install

swarm

probe

jira

scope-guard

ci

devwatch

shot

Notes

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

pi-extensions

Install

swarm

probe

jira

scope-guard

ci

devwatch

shot

Notes

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

pi-extensions

Install

swarm

probe

jira

scope-guard

ci