pi-config

Personal pi package — skills, extensions, prompts, and Nix infrastructure for the pi coding agent.

Tools & Skills

Tool/Skill	Description
chrome-cdp	Interact with local Chrome browser via Chrome DevTools Protocol. Navigate, evaluate JS, take screenshots.
kagi-search	CLI tool for Kagi web search with Quick Answers.
grafana-dashboards	Skill-only: create and manage Grafana dashboards via the API.
teaching-assistant	Skill-only: guided learning through explanation and feedback.
pdf-font-fix	Diagnose and fix PDF font embedding issues by embedding fonts using Ghostscript.
mattpocock-skills	Selected skills vendored from mattpocock/skills (MIT), including code review, codebase design, diagnosis, domain modeling, architecture improvement, prototyping, research, merge-conflict resolution, and writing workflows. Enabled skills also ship as standalone homeModules.<name> modules.
pi-hashline-edit	Strict hashline read/replace tool with hash-anchored edits (3-char, 18-bit, perfect hashing). Source only — disabled in the extension registry, so it is not built or exported as a package/homeModule.
pi-web-access	Web search, URL fetching, GitHub cloning, PDF extraction, YouTube/local video analysis. Runtime deps: ffmpeg, yt-dlp.
pi-apply-patch	Codex-style apply-patch tool for GPT-family models — registers a streaming patch tool and swaps write/edit while those models are active. Built as a package but disabled in the extension registry, so it is not installed or exported as a homeModule.
pi-openai-compaction	Replays OpenAI native standalone compaction windows without patching Pi core. Built as a package but disabled in the extension registry, so it is not installed or exported as a homeModule.
pi-blackhole	Unified algorithmic compaction + session-aware observational memory — deterministic zero-cost compaction with durable observations, fallback model chains, and a recall tool.
pi-boomerang	Token-efficient autonomous task execution with automatic context summarization.
pi-provider-qoder	Qoder AI provider extension for pi-coding-agent.
plannotator	Interactive plan review, annotation, approval, and execution tracking. Owns plan mode, --plan flag, and /plannotator command.
pi-subagents	Delegate tasks to focused child agents: code review, scouting, implementation, parallel audits, and background jobs.
pi-permission-system	Enforce configurable allow/ask/deny policies for tools, bash, MCP, skills, and file access. Configure at ~/.pi/agent/extensions/pi-permission-system/config.json (see upstream README).
pi-herdsman	Asynchronous managed Pi agents with nested delegation, background work, and fleet supervision in herdr.
pi-caffeinate	Automatically inhibits system/display sleep during Pi agent runs and releases afterward. /caffeinate sleep allows screen blanking; /caffeinate status shows the inhibitor state. Linux uses systemd-inhibit.
pi-context-view	Visualize context usage and inspect the hidden parts of the context: the system prompt, tool definitions, and extension injections. /context and /context injections.
pi-codex-api	Expose the Codex subscription to Pi: codex_ask text/vision delegation, codex_image generation, codex_search web/image search, Fast mode, and /codex-usage monitoring. Ships the gpt-image-prompts skill.
pi-fff	FFF-powered fuzzy file search and indexed content search for pi - fffind, ffgrep, fff-multi-grep tools plus FFF-backed @ autocomplete, backed by a prebuilt Rust engine (libfff_c). /fff-health, /fff-rescan, /fff-mode (tools-and-ui / tools-only / override).
mpi-bash	Bash execution policy: default 300s timeout, 30s foreground window with auto-detach to the background, completion notices, doubling stall reminders, a running-jobs widget, and /bash-logs overlay for reading full background logs. Config via MPI_BASH_FOREGROUND_SECONDS / MPI_BASH_STALL_SECONDS.

Each tool ships its skill definition under <tool>/skill/ (installed to $out/share/skills/<tool>/ where applicable).

Pi Package (available via pi install or nix module)

These components are loaded by pi when this repo is installed as a package:

Extensions

Extension	Description
branch-sessions	Automatically creates named session branches, restoring views and extensions context on session switch.
clipboard	Registers copy_to_clipboard tool — copies text via OSC52 escape sequences. Works across SSH sessions and most terminal emulators.
openai-fast	Toggles service_tier: "priority" for OpenAI GPT models. /openai-fast to toggle, --fast to start enabled. Inactive and hidden on openai-codex.
environment-context	Injects dynamic environment info (CWD, user, Git, Nix, direnv, OS) into the system prompt before each agent start.
notify	Desktop notification on agent completion via OSC terminal sequences. Supports iTerm2, WezTerm, Kitty, Ghostty, Windows Terminal. /notify to toggle.
oracle	Ask questions about your codebase using an oracle model for review/analysis. /oracle <question> sends a prompt to a dedicated model.
pi-mono-context-guard	Guards context usage and compaction behavior.
questionnaire	Interactive single- or multi-question prompts for the agent (questionnaire tool).
rewind	Git-backed session checkpoints, compaction snapshots, and branch restore (/rewind).
scoped-model-prompts	Appends per-model Markdown instructions to the system prompt only when the active model belongs to /scoped-models.
slow-mode	Intercepts write/edit tool calls, shows proposed changes for review before applying. Supports delta syntax highlighting, external editor, and vim keybindings.
stash	Save/restore editor text with Alt+S (session) and Alt+Shift+S (global). Persists across sessions and pi restarts.

Scoped model system prompts

Create ~/.pi/agent/model-prompts/<provider>/<model-id>.md with the instructions for that exact model, then include the model in /scoped-models (or use Pi's --models flag / enabledModels setting). For example:

~/.pi/agent/model-prompts/anthropic/claude-sonnet-4-5.md
~/.pi/agent/model-prompts/openrouter/anthropic/claude-sonnet-4.5.md

PI_CODING_AGENT_DIR overrides the agent directory. Slashes in model IDs become subdirectories. These are plain Markdown instructions, not slash-command prompt templates; no frontmatter or template expansion is performed.

Before each agent run, the extension reads the currently selected model's file and appends it to the existing system prompt. Switching models, changing the scope, or editing/removing a file takes effect on the next run without /reload. No instructions are added when the scope is empty or the active model is outside it. The openai-codex models gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, and gpt-6-astra default to a bundled KISS/ablation policy: perform an ablation pass after every implementation/debugging round, and add tests only for complicated or unreproducible bugs or high-level program properties. A user Markdown file replaces this default; a blank file disables injection for that model. For other models, missing/blank files add nothing. Other read errors are reported by Pi. User overrides stay in the agent directory, not the package.

Web access with mihomo TUN / fake-IP DNS

When mihomo resolves public domains into its fake-IP pool, pi-web-access's SSRF guard rejects source fetching with Blocked internal address ... 198.18.x.x. OpenAI search can still return an answer while fetch_content and searches with includeContent fail to retrieve the cited pages.

Merge this setting into your existing web-search.json for a mihomo fake-IP pool of 198.18.0.0/15:

{
  "ssrf": {
    "allowRanges": ["198.18.0.0/15"]
  }
}

The extension reads $PI_CODING_AGENT_DIR/web-search.json when that variable is set. Otherwise, when XDG_CONFIG_HOME is set, it prefers $XDG_CONFIG_HOME/pi/web-search.json and falls back to ~/.pi/web-search.json. Without XDG_CONFIG_HOME, it prefers ~/.pi/agent/web-search.json, then ~/.pi/web-search.json. Edit the file used by the Pi process and keep your other settings and existing range entries. Restart Pi after changing the config.

Use the actual fake-IP CIDR from your mihomo config. Only that pool is exempted; localhost and other private/reserved ranges remain blocked. This is an explicit per-machine setting supported by the pinned extension, so no package patch is needed. See the upstream configuration documentation.

Prompts

Prompt	Description
handoff	Creates a detailed handoff plan of the conversation for continuing work in a new session. Writes to .plan/handoffs/.
pickup	Resumes work from a previous handoff session stored in .plan/handoffs/.

Installation

Using Nix Flakes + home-manager

Add as an input to your flake:

inputs.pi-config = {
  url = "git+https://codeberg.org/comonad/pi-config";
  inputs.nixpkgs.follows = "nixpkgs";
};

Import the home-manager module:

imports = [ inputs.pi-config.homeModules.default ];

programs.pi-config.enable = true;

This:

• Installs selected skill/extension binaries (e.g. kagi-search, cdp)
• Installs and configures Herdr, including its Pi control skill
• Assembles a pi package at ~/.pi/agent/packages/pi-config (extensions, skills, prompts)
• Symlinks agent configs (AGENTS.md, keybindings.json) into ~/.pi/
• Symlinks skill definitions into ~/.claude/skills/ and ~/.opencode/skills/

Claude Code request shim

The default Home Manager module and development profile install pi-claude-shim, which runs the same Pi runtime with pi-cc-shim explicitly loaded. Ordinary pi does not load this extension. Do not separately install it with pi install if you want to preserve that separation.

nix run .#pi-claude-shim -- --help
# Or install packages.<system>.pi-claude-shim and run:
pi-claude-shim

Settings, credentials, sessions, and other extensions are shared with normal Pi. Upstream defaults only match anthropic-messages providers whose base URL contains anyrouter.top; configure other providers with providers or baseUrlPatterns in ~/.pi/agent/pi-cc-shim.json (and leave enabled true). Configure the provider itself in Pi's models.json. This shapes outbound requests, not the Claude CLI protocol, and does not change authentication or billing. The extension is packaged as dependency-free TypeScript, so no npm dependency cache is needed, and the build runs the upstream test suite.

This repo patches pi-cc-shim (model-patterns.patch) to add a modelPatterns config field: case-insensitive model-id globs (*, ?) that narrow whichever provider providers/baseUrlPatterns already selected. Use it when one relay fronts several vendors, so only its Claude models are disguised. For a local CLIProxyAPI instance serving Claude alongside Kimi/DeepSeek/Grok on one anthropic-messages endpoint, ~/.pi/agent/pi-cc-shim.json becomes:

{
  "enabled": true,
  "providers": ["anthropic"],
  "baseUrlPatterns": ["127.0.0.1:8317"],
  "modelPatterns": ["claude-*"]
}

modelPatterns: [] keeps upstream behaviour (every model on a matched provider). /cc-shim status reports model "<id>" matches no modelPatterns entry when a request is deliberately left alone.

Herdr

The default module enables Herdr with agent-session restore, the Gruvbox theme, and system toast delivery. Its Pi control skill is included in the assembled pi package. The standalone apply.sh installer also installs Herdr and pi-herdr, and links the same generated configuration to $HERDR_CONFIG_PATH or $XDG_CONFIG_HOME/herdr/config.toml.

Per-skill modules

Individual skills are available as standalone home-manager modules:

imports = [
  inputs.pi-config.homeModules.kagi-search
  inputs.pi-config.homeModules.chrome-cdp
];

These install just the tool + skill definition, without the full pi-config extensions/prompts/global config.

Per-extension modules (3rdparty-extensions)

Individual 3rd-party extensions are also available as standalone modules (one per entry in nix/extensions.nix):

imports = [
  inputs.pi-config.homeModules.pi-blackhole
  inputs.pi-config.homeModules.pi-boomerang
  inputs.pi-config.homeModules.pi-web-access
  inputs.pi-config.homeModules.plannotator
  inputs.pi-config.homeModules.pi-provider-qoder
  inputs.pi-config.homeModules.pi-codex-api
  inputs.pi-config.homeModules.pi-caffeinate
  inputs.pi-config.homeModules.pi-subagents
  inputs.pi-config.homeModules.pi-permission-system
  inputs.pi-config.homeModules.pi-herdsman
];

Extensions with runtime dependencies (e.g., pi-web-access needs ffmpeg + yt-dlp) get those binaries on PATH automatically. These modules install the extension and a minimal pi package at ~/.pi/agent/packages/pi-config-<name>/.

Herdsman vs. pi-subagents

	pi-herdsman	pi-subagents
Execution	Herdr-backed, asynchronous managed Pi sessions with nested ownership and cross-lead supervision	Pi child-agent delegation, background jobs, and scripted parallel workflows
Coordination	Agent lifecycle, steering, owner questions, and /agents / /chief interfaces	Workflow scripts, chains, reviews, and configurable agent runners
Requirements	Pi >=0.87.0 <0.88.0, herdr >=0.9.1, Node >=22.19.0	No Herdr dependency

Both packages register orchestration tools, so select them deliberately for a given Pi installation. pi-herdsman also requires a compatible Pi, Herdr, and Node runtime as documented in its upstream package metadata.

Override skillDirs

By default skill definitions are symlinked into ~/.claude/skills/ and ~/.opencode/skills/. Override programs.pi-config.skillDirs to target different agent harnesses:

programs.pi-config.skillDirs = [ ".claude/skills" ];

Pi package (standalone, no nix)

Note: This installs extensions, skills, and prompts only. Binaries, keybindings, and global config files require the Nix flake.

pi install git:codeberg.org/comonad/pi-config

# (Optional) Install 3rd-party extensions
for ext in ~/.pi/agent/packages/pi-config/3rdparty-extensions/*/; do
  (cd "$ext" && npm install)
  pi install "$ext"
done

Verify installation

After installing, confirm the package is loaded:

ls -d ~/.pi/agent/packages/pi-config
ls ~/.pi/agent/packages/pi-config/extensions/
ls ~/.pi/agent/packages/pi-config/skills/
cat ~/.pi/agent/packages/pi-config/AGENTS.md

Development

nix develop       # Enter dev shell
nix fmt           # Format Nix files
nix flake check   # Run all checks

To test a skill or extension locally before deploying, inspect its sources under skills/, extensions/, or 3rdparty-extensions/ and build with nix build .#<package> to validate.

License

MIT