pi-extensions

Extensions for the pi coding agent, living in a single repository that is consumed as a bare ~/.pi/agent/extensions/ directory.

Every subdirectory pi recognises as an extension is auto-discovered — either a root index.ts, or a package.json carrying a pi.extensions manifest that names a different entry point (pi-google-docs and pi-swarm-suite load from src/index.ts this way). No package install is required. The repository is the install unit.

Extensions

Extension	What it does	Docs
forgejo	Git forge: pull requests, CI runs, branches, repos, PR comments, webhooks.	docs/forgejo.md
forgejo-ci	Per-job CI status/durations and failure-log excerpts for Forgejo Actions (landing-pipeline evidence).	docs/forgejo-ci.md
harbor	Harbor container registry: push/pull images, list projects/repos/tags, inspect config.	docs/harbor.md
plane	Plane project management: tickets, comments, cycles, modules, relations, states, labels.	docs/plane.md
outline	Outline docs: create/update/search/move documents, collections, comments, plus the knowledge-graph tools.	docs/outline.md
lab-director	Lab Director stage artifact recording, HTML review artifacts, and the task-scoped Outline shortcuts.	docs/lab-director.md
pi-google-docs	Google Docs read/create/update/search/list plus Drive-folder graph indexing.	docs/pi-google-docs.md
pi-otel-telemetry	OpenTelemetry traces to OTLP + the query_telemetry tool for Tempo traces and PromQL.	docs/pi-otel-telemetry.md
pi-skills	Four vendored skills (code-review, create-handoff, resume-handoff, commit) registered via resources_discover.	docs/pi-skills.md
skill-args	Skill argument plumbing: $ARGUMENTS/$N, ${SKILL_DIR}, ${SESSION_ID}, shell blocks, shell-timeout.	docs/skill-args.md
todo	The todo tool, /todos command, and a live todo overlay panel.	docs/todo.md
ask-user-question	The ask_user_question tool: a structured multi-question dialog with authored options.	docs/ask-user-question.md
epic-session	The /epic-session command: claim a parallel-session slot, create epic worktrees, print a sourceable env block, and tear the session down.	docs/epic-session.md
pi-swarm-suite	Subagent fleet: Agent, agent_swarm, swarm_status, task_status, workflow, plus steering and result retrieval. Also publishes the current in-process spawn role (AsyncLocalStorage) for the session-tag extension.	docs/pi-swarm-suite.md
pi-session-tag	Stamps every OmniRoute provider request with x-omniroute-session-id (proj/role/sid) so the gateway fills call_logs.session_tag; fail-safe by construction, OmniRoute-only. Not installed yet — see its README.	pi-session-tag/README.md
voice-whisper	Local push-to-talk dictation (whisper.cpp large-v3-turbo, EN/ES auto-detect) via a warm whisper-server; Ctrl+R toggles recording.	docs/voice-whisper.md
mcp-bridge	Typed MCP seam: an MCP server's tools registered as mcp_* pi tools (built for the agent-sandbox server: claim, status, exec, file transfer, delete).	docs/mcp-bridge.md
refocus	Byte-threshold intent re-injection: a long session's context crossing a threshold gets one <500-token delta restating its intent and last verified activity, so it re-orients instead of restarting. Metered via refocus_status.	docs/refocus.md
redact	Masks secrets (Anthropic/OpenAI/GitHub/Forgejo tokens, URL creds, Authorization, JWTs, OpenBao tokens, AWS/age/PEM keys, password assignments, k8s Secret data) in every tool result before it reaches model context, the session JSONL or a subagent .output transcript. Outputs only, never args or files; fail-open.	docs/redact.md

Extensions that ship their own in-tree documentation link to it from their page rather than duplicating it (pi-swarm-suite, pi-skills, todo, ask-user-question, skill-args, harbor, pi-google-docs, forgejo-ci, epic-session, mcp-bridge, refocus, redact).

Herdr Session Janitor

scripts/herdr_janitor/janitor.py is a standalone mgmt helper, not a pi auto-loaded extension. It is dry-run by default and closes only named, allowlisted old sessions with a proven successor plus handoff evidence, or an explicit retire marker, and only when the old pane has no live agents/workers/shells. See docs/herdr-janitor.md for the safety contract, 15-minute systemd --user timer, evidence paths, and the separate supervisor activation procedure. The implementation change does not install or activate the timer.

Install

Symlink the checkout into pi's extension directory (recommended — keeps edits live and git pull effective):

git clone git@forgejo.aaron.reynoza.org:Homelab/pi-extensions.git ~/repos/pi-extensions
ln -s ~/repos/pi-extensions ~/.pi/agent/extensions

Or clone directly into place:

git clone git@forgejo.aaron.reynoza.org:Homelab/pi-extensions.git ~/.pi/agent/extensions

Either way pi discovers every extension-shaped subdirectory at startup — a root index.ts, or the entry named by a pi.extensions manifest in that directory's package.json. Restart the session, or run /reload after editing an extension.

If you want only a subset, symlink the individual extension directories instead of the repository root — each one is self-contained.

Configuration

Extensions read credentials from the environment; there is no central config file in this repository. Set the variables in your shell profile (or in the workspace that launches pi):

Extension	Variables
forgejo	FORGEJO_BASE_URL, FORGEJO_API_KEY
forgejo-ci	FORGEJO_BASE_URL, FORGEJO_API_KEY, and FORGEJO_SESSION_COOKIE (or FORGEJO_WEB_USERNAME + FORGEJO_WEB_PASSWORD) for job logs
harbor	HARBOR_BASE_URL, HARBOR_USERNAME, HARBOR_PASSWORD, HARBOR_LAN_ENDPOINT, HARBOR_INSECURE
plane	PLANE_API_KEY, PLANE_WORKSPACE_SLUG, PLANE_BASE_URL
outline, lab-director	OUTLINE_API_URL, OUTLINE_API_KEY
pi-otel-telemetry	OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME, ZITADEL_ID_TOKEN / ZITADEL_ACCESS_TOKEN, PAPERCLIP_*
mcp-bridge	AGENT_SANDBOX_MCP_URL, AGENT_SANDBOX_MCP_TOKEN (or MCP_TOKEN), PI_MCP_BRIDGE_TIMEOUT_MS, PI_MCP_BRIDGE_DISABLED
refocus	All optional: REFOCUS_INTENT / REFOCUS_INTENT_FILE (where the intent comes from), REFOCUS_THRESHOLD, REFOCUS_RESET, REFOCUS_BYTE_THRESHOLD, REFOCUS_MAX_DELTA_TOKENS, REFOCUS_MAX_DELTA_BYTES, REFOCUS_MAX_INJECTIONS, REFOCUS_MIN_TURNS_BETWEEN, REFOCUS_FALLBACK, REFOCUS_RESTART_BASELINE_TOKENS, REFOCUS_ACTION_SUMMARY_CHARS, REFOCUS_SCOPE, REFOCUS_ENABLED, REFOCUS_LOG
redact	All optional: PI_REDACT_LOG (count log path, default ~/.pi/agent/redact.log), PI_REDACT_DISABLED=1 (operator kill switch)

Required-ness differs. The forgejo, plane, and outline tools throw when their variables are unset; for lab-director only the three outline_* shortcut tools need OUTLINE_* (the client is built per call, so artifact recording and HTML rendering work without it). Every harbor, pi-otel-telemetry, and mcp-bridge variable has a default or a fallback — mcp-bridge degrades to no mcp_* tools when the server is unreachable rather than erroring — see each extension's page. Every refocus variable is optional: with no intent set it is a strict no-op, and with the intent set the defaults implement the <500-token contract as shipped.

pi-google-docs stores OAuth credentials under ~/.pi/google-docs/ instead (see its docs page). Never commit credentials.

External packages

Two kinds of dependency live outside this repository.

pi packages installed through pi's package manager (not part of this repo; listed under packages in ~/.pi/agent/settings.json): pi-intercom, pi-web-access, pi-markdown-preview, pi-chrome, pi-btw, and pi-image-attachments. The @juicesharp/rpiv-* packages also used to be in that list and are no longer installed — most of their surface was vendored here instead (see the vendoring note below). pi-provider-kimi-code was dropped too (HOMELAB-2301): models are reached through OmniRoute only.

Local npm dependencies, installed inside the extension directory that owns them:

• pi-swarm-suite builds on the vendored Agent/task core and expects the pi coding agent runtime it was written against.
• pi-otel-telemetry connects to any OTLP/HTTP collector and a Tempo-compatible trace backend and Prometheus-compatible metrics API.
• pi-google-docs uses the Google APIs Node client.
• mcp-bridge uses the @modelcontextprotocol/sdk client (pinned) to reach an MCP server over streamable HTTP.
• Skill and tool schemas use typebox / @sinclair/typebox as provided by pi.

Where an extension has a package.json, install its dependencies inside that extension directory before first use.

Vendoring note (HOMELAB-1609)

Three extensions and the pi-skills bundle are MIT-licensed ports of @juicesharp/rpiv-* packages, not original work: skill-args (from rpiv-args), todo (from rpiv-todo), ask-user-question (from rpiv-ask-user-question), and the four skills under pi-skills/skills/ (from rpiv-pi, v2.10.1). They were vendored when the @juicesharp/rpiv-* packages were uninstalled (HOMELAB-1609) so that the used surface survives. Tool and command names and expansion semantics are byte-for-byte preserved; the unused @juicesharp/* internal dependencies (rpiv-config, rpiv-i18n) were inlined or dropped. Upstream license text is preserved in each directory's LICENSE, and modifications are listed in the per-extension README (pi-skills/README.md for the skills, including the stripped contract: frontmatter). Where a port needed its own config surface it ships a local-config.ts (ask-user-question/, todo/).

Notes

• The knowledge-graph tools (lab_director_graph_*) live in outline/; lab-director/ keeps artifact tracking, the HTML artifact renderer, and the pipeline skills.
• herdr-agent-state.ts (if present in a live install) is machine-generated glue written by herdr and deliberately gitignored — see .gitignore. It is not part of this repository.
• Removed extensions. paperclip (HOMELAB-1457) and outline-vault (superseded by outline/ plus the knowledge graph) were retired. Their integration points outlive them: pi-otel-telemetry still reads PAPERCLIP_* (docs/pi-otel-telemetry.md) and the outline graph builder still writes a markdown vault under ~/.pi/outline-vault (docs/outline.md).

License

Apache-2.0 — see LICENSE and NOTICE. pi-swarm-suite/src/core (the fifth vendored component) vendors the MIT-licensed @tintinweb/pi-subagents — see pi-swarm-suite/LICENSE. Other vendored third-party code keeps its upstream copyright and license files in the directory that contains it.

Adding an extension

1. Create <name>/index.ts exporting pi's extension shape. If the entry point has to live elsewhere, add a package.json with {"pi": {"extensions": ["./src/index.ts"]}} instead.
2. Document it in docs/<name>.md and add a row to the table above.
3. Reload pi and confirm its tools and commands appear.