---
title: "Pi extensions"
description: "How the pi coding-agent extensions in this configuration are provisioned and what they do."
---

# Pi extensions

This configuration ships a large set of [pi](https://github.com/badlogic/pi-mono) 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.

- **Document / web / media**:
  - [`docparse/`](../pi-extensions/docparse/) — parse PDFs, Excel, ODF, and documents (text, markdown, tables, OCR, screenshots).
  - [`pixelrag/`](../pi-extensions/pixelrag/) — visual RAG; render documents and web pages to screenshot tiles and search a hosted visual index.
  - [`typst/`](../pi-extensions/typst/) — initialize, compile, query, and inspect fonts for Typst documents.
  - [`pi-mermaid/`](../pi-extensions/pi-mermaid/) and [`drawio/`](../pi-extensions/drawio/) — diagrams (Mermaid and draw.io shapes, auto-layout).
  - [`menyoki/`](../pi-extensions/menyoki/) — screen capture, screencast recording, and image editing/analysis.
- **Integrations**:
  - [`anytype/`](../pi-extensions/anytype/), [`anytype-tree-view/`](../pi-extensions/anytype-tree-view/) — Anytype objects (see [Anytype integration](#anytype-integration)).
  - [`azure/`](../pi-extensions/azure/), [`azure-app-id/`](../pi-extensions/azure-app-id/) — Azure & Microsoft 365.
  - [`application-assistant/`](../pi-extensions/application-assistant/) — job-application workflow.
  - [`denful/`](../pi-extensions/denful/) — Nix flakes editor and tool-versioning CLI.
  - [`r-modern/`](../pi-extensions/r-modern/) — R code analysis and evaluation.
- **Models & providers**:
  - [`scaleway/`](../pi-extensions/scaleway/), [`engine-gate/`](../pi-extensions/engine-gate/) (on-demand local engine lifecycle), [`model-identity/`](../pi-extensions/model-identity/).
- **Security**:
  - [`path-guard/`](../pi-extensions/path-guard/) — file-access allowlist/denylist (see [security.mdx](security.mdx)).
  - [`azure-guard/`](../pi-extensions/azure-guard/) — disable Azure/Microsoft 365 tools in unattended Firstmate sessions.
  - [`credential-leak/`](../pi-extensions/credential-leak/) — transcript scanning and redaction.
  - [`curl/`](../pi-extensions/curl/) — safe HTTP requests (see below).
- **Workflow & helpers**:
  - [`branch-guard/`](../pi-extensions/branch-guard/) — branch-per-task enforcement (see below).
  - [`nix-fmt/`](../pi-extensions/nix-fmt/) — auto-format Nix files after edits.
  - [`rg-replace/`](../pi-extensions/rg-replace/), [`fd-replace/`](../pi-extensions/fd-replace/) — swap `grep`/`find` for `rg`/`fd` in bash tool calls.
  - [`cost-tracker/`](../pi-extensions/cost-tracker/), [`cost-tracker-scaleway/`](../pi-extensions/cost-tracker-scaleway/) — token/cost tracking (see below).
  - [`tps-tracker/`](../pi-extensions/tps-tracker/) — footer stat for average tokens/sec.
  - [`subagent/`](../pi-extensions/subagent/) — delegate to isolated subagent processes.
  - [`clipboard/`](../pi-extensions/clipboard/) — push text to the macOS clipboard via `pbcopy`.
  - [`lazy-load/`](../pi-extensions/lazy-load/), [`schema-sanitizer/`](../pi-extensions/schema-sanitizer/), [`request-logger/`](../pi-extensions/request-logger/), [`nix-pi-crafter/`](../pi-extensions/nix-pi-crafter/) — miscellaneous plumbing.
  - [`integration-layer/`](../pi-extensions/integration-layer/) — extension coordination and workflows (see below).
  - [`integration-example/`](../pi-extensions/integration-example/), [`workflow-example/`](../pi-extensions/workflow-example/) — usage examples.

## 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`:

```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:

```text
# 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](security.mdx) for how to edit encrypted secrets.

### Related

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