pi-extensions

Local pi extensions for a self-hosted homelab workflow: Forgejo, Harbor, Outline, Plane, OpenTelemetry, Google Docs, and a full subagent/swarm suite.

This repo is the extensions directory — clone it (or symlink individual subdirectories) at ~/.pi/agent/extensions/ and pi will load every extension-shaped subdirectory automatically on startup.

git clone <this-repo> ~/.pi/agent/extensions
# or, to pick individual extensions:
ln -s $(pwd)/plane ~/.pi/agent/extensions/plane

External packages (installed separately via pi's package manager, not part of this repo): pi-intercom, pi-web-access, pi-markdown-preview, pi-chrome, pi-btw, pi-provider-kimi-code, pi-image-attachments, @juicesharp/rpiv-pi, @juicesharp/rpiv-todo, @juicesharp/rpiv-advisor, @juicesharp/rpiv-i18n, @juicesharp/rpiv-args, @juicesharp/rpiv-workflow.

---

Extensions

Extension	Purpose	Key tools
pi-swarm-suite	Subagent orchestration: Agent tool, homogeneous swarms, team mode, live TUI, durable task store, workflow gates	Agent, agent_swarm, swarm_status, task_status, workflow
forgejo	Git forge integration (repos, PRs, branches, CI, webhooks)	forgejo_create_pr, forgejo_merge_pr, forgejo_list_ci_runs, forgejo_comment_on_pr
plane	Project management / ticketing	plane_create_item, plane_update_item, plane_list_items, plane_comment, plane_add_to_cycle
outline	Outline wiki integration + knowledge graph	outline_*_document, outline_search_documents, lab_director_graph_build, lab_director_graph_query
lab-director	Artifact tracking + pipeline skills (knowledge-graph, incident-response)	lab_director_generate_html_artifact, lab_director_record_artifact
harbor	Harbor container registry operations	harbor_push_image, harbor_pull_image, harbor_list_projects, harbor_list_tags
pi-google-docs	Google Docs read/write + knowledge-graph indexing	google_docs_read, google_docs_create, google_docs_update, google_docs_build_graph
pi-otel-telemetry	OpenTelemetry tracing for pi sessions (sessions, turns, tools, LLM calls → OTLP/Tempo)	query_telemetry

pi-swarm-suite

The largest piece. Core sub-agents (foreground/background spawn, concurrency queue, cron scheduling, custom agent types from .pi/agents/*.md), Kimi-style swarms (agent_swarm — one template × N items → N parallel children), team mode, a live TUI overlay (ctrl+shift+g, /swarm-view) with failure diagnosis and retry/resume/steer/abort actions, a durable task store, and a workflow-gate mode. See pi-swarm-suite/README.md — it has its own package.json; run npx vitest run from that directory for its test suite.

Configuration / environment variables

Every integration is configured via environment variables (or, where noted, pi's extension-settings panel) — nothing machine-specific is hardcoded:

# Forgejo
export FORGEJO_BASE_URL="https://forgejo.example.com"
export FORGEJO_API_KEY="..."

# Plane
export PLANE_BASE_URL="https://plane.example.com"
export PLANE_API_KEY="..."
export PLANE_WORKSPACE_SLUG="..."

# Outline
export OUTLINE_API_URL="https://docs.example.com/api"
export OUTLINE_API_KEY="ol_api_..."

# Harbor (falls back to ~/.docker/config.json for auth)
export HARBOR_BASE_URL="https://harbor.example.com"
export HARBOR_USERNAME="..."
export HARBOR_PASSWORD="..."
# export HARBOR_LAN_ENDPOINT="192.0.2.10"  # optional direct-LAN push fallback

# OpenTelemetry (defaults to http://localhost:4318)
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_EXPORTER_OTLP_HEADERS='{"Authorization":"Basic base64(<user>:<token>)"}'

pi-google-docs uses an OAuth flow — run its /google_docs_auth command once to provision ~/.pi/google-docs/.

Notes

• The knowledge-graph tools (lab_director_graph_*) live in outline/; lab-director/ keeps artifact tracking and the pipeline skills.
• herdr-agent-state.ts (if present in a live install) is machine-generated glue installed by herdr and deliberately gitignored — not part of this repo.
• Removed extensions: paperclip (HOMELAB-1457) and outline-vault (superseded by outline/ + the knowledge graph).

License

Apache-2.0 — see LICENSE and NOTICE. pi-swarm-suite/src/core vendors MIT-licensed @tintinweb/pi-subagents (see pi-swarm-suite/LICENSE).