Search Documentation

Search for pages and headings in the documentation

Pi extensions

This configuration ships a large set of pi coding-agent extensions. There are three provisioning paths:

  1. Home-manager managed extensions: modules/ai.nix builds pi-extensions-merged from everything under pi-extensions/, plus external answer.ts and todos.ts from mitsuhiko/agent-stuff. It symlinks the result to ~/.pi/agent/extensions/. Any directory with an index.ts (or a top-level *.ts file) is loaded as an extension on the next home-manager switch.
  2. Package-based extensions: extensions shipped as Nix packages — pi-observability, r-modern, drawio-extension, astro-web-terminal. They are installed via modules/pi-extensions.nix and surface options under programs.pi-extensions.*.
  3. Extension loading: pi loads extensions from cwd/.pi/extensions/ (project-local), ~/.pi/agent/extensions/ (global, symlinked to the home-manager directory). It also loads explicitly configured paths (the package-based ones, wired in modules/ai.nix settings.json).

Inside pi, run /extensions to list the loaded extensions and /tools to discover their tools.

Extension inventory

Curated list of the extensions in pi-extensions/, grouped by purpose. The exact set drifts as extensions are added and removed, so treat this as an overview rather than an exhaustive index.

Branch guard

pi-extensions/branch-guard/ enforces the “branch-per-task” workflow documented in AGENTS.md.

Behavior:

  • On session start, checks if we are on the main branch.
  • If on main and starting a new task, prompts to create a new branch.
  • Suggests branch names following Conventional Commits conventions (e.g. feat/short-description, fix/issue-name).
  • Automatically handles git operations (switch to main, create and switch to a new branch).
  • Tracks state to avoid repeated prompts in the same session.

Curl extension with path restrictions

pi-extensions/curl/ provides HTTP request capabilities with fine-grained security controls. The extension-specific documentation lives in pi-extensions/docs/CURL_ENHANCEMENTS.md.

Features: domain allowlisting, path-level restrictions, wildcard path patterns, method restrictions, rate limiting (30 req/min per domain), and request caching (5-minute TTL). It also provides automatic retries, comprehensive logging, and graceful error handling.

Domains and paths are configured in pi-extensions/curl-config.json:

{
  "safeUrls": [
    { "domain": "codefloe.com", "methods": ["GET", "POST", "PUT", "DELETE"], "paths": ["/spectral-cockpit", "/philipp-baumann", "/crowci"] },
    { "domain": "httpbin.org", "methods": ["GET", "POST", "PUT", "DELETE"] }
  ]
}

Inside pi, the tools curl_request, curl_add_safe_url, curl_check_rate_limit, and curl_clear_cache expose the functionality programmatically.

Cost tracker

pi-extensions/cost-tracker/ tracks Claude/Anthropic spend. It writes one JSON line per assistant turn to ~/.pi/agent/cost-tracker.jsonl and shows a live per-session status line in pi’s footer (cost: api=$… sub=$…).

Each turn is classified as either api (billed to your Anthropic API key) or subscription (absorbed by a Claude Max/Pro plan via pi’s /login OAuth flow). On this machine all Anthropic traffic goes through ANTHROPIC_API_KEY (exported by modules/shell.nix from a SOPS secret), so in practice every live turn lands in the api bucket.

Commands, all run inside pi:

# show today / last 7d / last 30d / all time, plus per-day (14), per-week (8),
# per-month (6), and per-model breakdowns
/cost

# one-time import of historical Claude turns from ~/.pi/agent/sessions into
# the log. pi does not persist the OAuth/subscription flag per message, so you
# must tell it which bucket old turns should land in. On this setup, use `api`.
/cost-backfill api

# re-run the backfill (e.g. after editing the log or wiping the sentinel)
/cost-backfill api --force

The backfill sentinel lives at ~/.pi/agent/cost-tracker.backfilled. Delete it (or pass --force) to re-import.

pi-extensions/cost-tracker-scaleway/ does the same for Scaleway model usage, logging to ~/.pi/agent/cost-tracker-scaleway.jsonl. It exposes a /cost-scaleway command plus a scw: … footer status.

Integration layer

pi-extensions/integration-layer/ lets extensions cooperate while staying independent. It provides extension registration, dependency resolution, health monitoring, workflow creation, and cross-extension tool discovery.

The full API and examples live in pi-extensions/docs/README.md and pi-extensions/INTEGRATION_LAYER.md. Highlights:

  • Extension Registration: extensions register themselves with metadata, dependencies, and optional health checks.
  • Dependency Management: topological resolution of declared dependencies.
  • Workflow Creation: combine extensions into reusable workflows with a priority-ordered execution pipeline.
  • Health Monitoring: central health checks for all registered extensions.
  • Slash commands: /integration, /integration list, /integration health, /integration workflow, /integration workflows, /integration start, /integration tools.
  • Tools: integration_list_extensions, integration_check_health, integration_list_workflows, integration_start_workflow, integration_get_workflow_status, integration_list_all_tools.

The examples in pi-extensions/integration-example/ and pi-extensions/workflow-example/ demonstrate best practices.

Anytype integration

The Anytype integration has two independent pieces that share secrets/anytype.yaml:

  • pi-extensions/anytype/ — pi tools that call the Anytype desktop app’s REST API on http://localhost:31009. See pi-extensions/anytype/README.md for setup, env vars, tool reference, and troubleshooting.
  • modules/anytype.nix — packages the standalone anytype-mcp MCP server plus anytype-cli, and writes a wrapper at ~/.config/anytype/anytype-mcp-wrapper.sh that injects the API key from sops. Use this wrapper in external MCP clients such as Claude Desktop or Cursor.

The integration is enabled via programs.anytype.enable = true; in home.nix. Nothing in this repo runs the desktop-app-backed pi extension as a long-running service; the optional headless CLI server runs as a launchd/systemd service on port 31012.

Credentials

secrets/anytype.yaml holds the apiKey and workspaceId keys. They are declared in modules/ai.nix and exported as ANYTYPE_API_KEY and ANYTYPE_WORKSPACE by modules/shell.nix for use by the pi extension. See security.mdx for how to edit encrypted secrets.

  • pi-extensions/anytype-tree-view/ — a tree-view over Anytype search results.
  • pi-extensions/anytype/README.md — detailed documentation.