pi-config

My personal pi coding agent configuration — a pi package with extensions, reviewer agents, an OpenSpec planning workflow, and a one-shot bootstrap for new Arch machines.

Anything I changed or want to own lives in this repo. Stock packages install straight from upstream and update on their own with pi update --extensions, so there are no forks to maintain.

What's inside

├── extensions/
│   ├── browser/                  Playwright headless browser, Chromium AND Firefox,
│   │                             private root CA import (see extensions/browser/README.md)
│   ├── ask-user-question.ts      ask_user_question tool (borrowed from amosblomqvist/pi-config)
│   ├── subagent-model-router.ts  Picks the model per subagent type from subagent-models.json
│   └── opsx-grounding.ts         Injects code-grounding rules into /opsx-explore and /opsx-propose
├── agents/doubt-*.md             Three read-only plan reviewers: skeptic, architect, realist
├── openspec-schema/
│   ├── quality/                  Default workflow: proposal → specs → design → tasks →
│   │                             verification → 3-reviewer doubt review → apply
│   └── quality-ui/               Same, plus approved HTML mocks and a screen-flow index
├── pi-global/
│   ├── AGENTS.md                 Global agent rules
│   ├── subagent-models.json      Model per subagent type ("inherit", "ask", or provider/model)
│   └── .pi-lsp.json              LSP config: auto-start python, typescript, bash
├── skills/
│   ├── code-grounding/           Planning-time LSP scan (overview → symbols → definitions → references)
│   └── knowledge-loop/           Planning lessons + design patterns: read, distill, retro, promote
├── knowledge/                    Global OKF bundle of promoted lessons and patterns,
│                                 linked to ~/.pi/agent/knowledge
├── scripts/check-plan.mjs        Deterministic validator for finished plans, deployed as `check-plan`
├── enable-quality.sh             Sets `schema: quality` and the archive retro guidance in a project,
│                                 deployed as `enable-quality`
├── tmux/themes/, .tmux.conf      tmux config and themes
├── tests/                        node:test suites for bootstrap.sh and check-plan
├── forge_setup.md                Forgejo git auth and the internal-https recipe
└── bootstrap.sh                  New-machine setup

Bootstrap also installs these upstream packages unchanged:

• pi-web-access: web search and page extraction. Bootstrap writes ~/.pi/web-search.json (only if it's missing): Firecrawl first, keyless Exa as the fallback, raw results with no curator popups (toggle with /curator).
• pi-interactive-subagents: subagents that run in tmux panes (scout, researcher, worker, plus the doubt reviewers from agents/).
• pi-lsp-extension: LSP tools for code navigation.
• @upstash/context7-pi: current library docs, plus the /c7-docs command.

Tool surface

Tool	From	Purpose
web_search	pi-web-access	Firecrawl search (Exa fallback); recency/domain filters, batch queries
fetch_content	pi-web-access	URL(s) → markdown; GitHub clone, PDF, YouTube, video
get_search_content / source_check	pi-web-access	Retrieve cached content / fact-check a claim
resolve-library-id / query-docs	context7-pi	Find a library's Context7 ID, then fetch its docs
code_overview / lsp_*	pi-lsp-extension	Code navigation: symbols, definitions, references, hover, diagnostics, rename
browser_goto/eval/console/network/fill/click/screenshot/close	browser	Drive a headless browser (either engine)
ask_user_question	ask-user-question	Ask the human one question (options / free text / multi-select)
subagent / subagent_message / subagents_list	pi-interactive-subagents	Spawn and steer tmux subagents
ask_question	pi-interactive-subagents	(subagents only) Ask the orchestrator, then wait for the answer

Install (new machine)

git clone https://forge.angelhost.eu/Lynx/pi-config && cd pi-config
./bootstrap.sh            # interactive; the Forgejo token prompt is hidden
./bootstrap.sh --yes      # unattended; needs sudo -n and existing Forgejo auth
                          # (or FORGEJO_TOKEN + a keyring/cache Git helper)

Bootstrap is Arch-only and safe to re-run. It installs system packages, Podman, mise, Node.js, Python, uv, pi with all the packages above, Playwright browsers, OpenSpec with both schemas, and the LSP servers. It then deploys the agent rules, skills, reviewers, helper scripts, tmux config and .pi-lsp.json, and adds any default settings that are missing (it never overwrites existing keys). See forge_setup.md for the Forgejo token and internal https.

Manual install of just the pi side:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi install git:forge.angelhost.eu/Lynx/pi-config
pi install git:github.com/samfoy/pi-lsp-extension
pi install git:github.com/amosblomqvist/pi-interactive-subagents
pi install npm:pi-web-access
pi install npm:@upstash/context7-pi

Then put the API keys in ~/.bashrc (see Environment variables).

OpenSpec workflow

After openspec init, enable the workflow once per project:

enable-quality
openspec new change <name>                      # quality
openspec new change <name> --schema quality-ui  # adds approved UI mocks

Both schemas end with a three-reviewer doubt review. As the review spawns its reviewers, pi opens a model picker for each one in turn: Agent default keeps the reviewer's frontmatter model, Session default uses the current /model, or pick any available model (your last choice comes first). To skip a reviewer's picker, set it to a fixed provider/model in ~/.pi/agent/subagent-models.json.

The review and apply steps run check-plan first:

check-plan <change-name>                  # from the project root
check-plan /absolute/change/directory \
  --project-root /absolute/project/root  # change directory outside the project
check-plan <change-name> --fingerprint    # fingerprint of the reviewed artifacts, for doubt-review.md

It rejects incomplete or ungrounded plans, broken task dependencies, gaps in verification coverage, unapproved UI plans, a reduced reviewer panel, a review lesson not backed by a fixed must-fix, and any edit to reviewed artifacts after the review (except ticking task checkboxes). Add --json for machine-readable output.

Knowledge loop

Each project keeps an OKF bundle in openspec/knowledge/: Planning Lessons (mistakes the review caught) and Design Patterns (approaches that were built and verified). The knowledge-loop skill runs it:

1. Read: every planning artifact applies the matching lessons from the project bundle and the global one. Design decisions name the pattern they adopt.
2. Lesson: the doubt review ends by recording at most one lesson, from fixed must-fix findings only, in doubt-review.md ## Lesson (or NO_ENTRY).
3. Retro: before archive, each design decision is checked against the built code (held / changed / dropped). Patterns get confirmed, rewritten to what actually worked, or deprecated. The result goes to retro.md.
4. Promote: a lesson or pattern backed by two or more changes, and statable without repo-specific names, is offered for the global bundle. Nothing moves up without your answer. Updates to promoted entries are offered again, which keeps global patterns current.

Plans reviewed before the knowledge loop existed need ## Lesson with NO_ENTRY added to doubt-review.md before check-plan passes again. The fingerprint is unaffected. Re-run enable-quality in existing projects to add the archive guidance.

Active changes keep the schema recorded in their .openspec.yaml, so don't delete a retired user-level schema until every change that uses it is archived.

Environment variables

Variable	Default	Effect
OPENROUTER_API_KEY	unset	OpenRouter key for pi's default provider (openrouter) and the subagent models
FIRECRAWL_API_KEY	unset	Firecrawl key for web_search and blocked-page extraction; read at request time through ~/.pi/web-search.json. Without it, search falls back to keyless Exa
CONTEXT7_API_KEY	unset	Optional Context7 key (free); without it, IP-based rate limits apply
FORGEJO_TOKEN	unset	Forgejo token used only during bootstrap; stored through a keyring/cache Git helper, then unset
SKIP_BROWSER_DEPS	unset	1 skips browser system libraries, binaries, and checks in bootstrap
PI_BROWSER_ENGINE	chromium	chromium, firefox, or auto
PI_BROWSER_ENABLED	unset	1 turns the browser tools on from session start
PI_BROWSER_HEADFUL	unset	Launch a visible window
PI_BROWSER_PROFILE	~/.pi/agent/extensions/browser/.profile-<engine>	Browser profile directory
PI_BROWSER_ROOT_CA	unset	Root CA pem imported into the browser NSS stores (needs certutil)
PI_BROWSER_IGNORE_TLS	unset	Last resort: accept self-signed certs outright
NODE_EXTRA_CA_CERTS	unset	Set to /etc/ssl/certs/ca-certificates.crt so Node trusts internal CAs

export OPENROUTER_API_KEY=sk-or-...
export FIRECRAWL_API_KEY=fc-...
export CONTEXT7_API_KEY=ctx7sk_...   # optional

Keeping machines in sync

• This repo: edit → commit → push, then pi update --extensions on the other machines. That only refreshes what pi loads from the package (the extensions). After changing schemas, agents, helper scripts, tmux, or LSP config, re-run ./bootstrap.sh --no-pi too.
• Upstream packages: pi update --extensions.
• Settings stay local to each machine; bootstrap only adds missing defaults.

Credits

• amosblomqvist/pi-config: ask-user-question and the base of the browser extension.
• nicobailon/pi-web-access: web search and content extraction.
• amosblomqvist/pi-interactive-subagents (fork of HazAT's): the subagent engine (MIT).
• pi by Mario Zechner / earendil-works.