pi-config

My personal pi coding agent configuration — a pi package containing extensions, agent definitions, and a one-shot bootstrap for new machines.

Upstream pi ships a solid baseline (read/edit/bash + skills). This repo layers on what pi doesn't do out of the box: searching the web through my own SearXNG instance instead of third-party APIs, driving both Chromium and Firefox as a debugging surface, and orchestrating tmux subagents.

Philosophy

• Modified extensions live here — anything I changed (or want to own) is bundled in this repo and deployed to every machine through it.
• Stock extensions install straight from upstream via pi install git:... and are updated independently with pi update --extensions — no forks to maintain.
• The repo is the single source of truth: edit here, push, pi update --extensions everywhere else.

What's inside

├── extensions/
│   ├── web-search/          MODIFIED — dual backend: SearXNG (JSON API) or Google CSE.
│   │                        Structured queries (exactPhrases, excludeTerms, site:),
│   │                        backend selected by env, backend tag shown in results.
│   ├── web-fetch/           Borrowed (amosblomqvist/pi-config) — URL → markdown via
│   │                        Readability+Turndown, PDF extraction, RSC support,
│   │                        Jina Reader fallback for JS-rendered pages.
│   ├── browser/             MODIFIED — Playwright-driven headless browser with
│   │                        Chromium AND Firefox dual-engine support (upstream is
│   │                        Chromium-only), private root CA import, runtime engine
│   │                        switching. See extensions/browser/README.md for details.
│   ├── ask-user-question/   Borrowed (amosblomqvist/pi-config) — replaces the
│   │                        @juicesharp/rpiv-ask-user-question npm package. Same
│   │                        ask_user_question tool, one-question flow, shared UI
│   │                        lock so popup tools from other extensions coexist.
│   └── opsx-grounding.ts    Auto-injects planning-grounding lines when a prompt
│                            starts with /opsx-explore or /opsx-propose (mechanism
│                            borrowed from prompt-snippets, made automatic).
├── openspec-schema/
│   ├── doubt-review/        OpenSpec workflow schema (user override) — extends
│   │                        spec-driven with a doubt-review artifact between
│   │                        design and tasks: 3 parallel reviewer subagents,
│   │                        each may ask the user questions, best-of merged
│   │                        before tasks.md is written. Deployed by bootstrap
│   │                        to ~/.local/share/openspec/schemas/.
│   ├── tests/               OpenSpec workflow schema — doubt-review PLUS
│   │                        language-aware test-case generation (tests.md,
│   │                        auto-detects Playwright/vitest/pytest/cargo/go)
│   │                        and test-first verification during apply. Enable
│   │                        per project with enable-tests.sh.
│   └── ui-mocks/            OpenSpec workflow schema — tests PLUS a ui-mocks
│                            artifact (static HTML mock screens + screens.md
│                            wireframe index) between design and doubt-review:
│                            the visual big picture for greenfield/UI changes,
│                            reviewed by the doubt-review agents. Backend-only
│                            changes record a skip in screens.md. NEVER a
│                            project default — toggle per change:
│                            openspec new change <name> --schema ui-mocks.
├── agents/
│   ├── doubt-skeptic.md     Red-team reviewer: falsify the plan against the
│   │                        real code (assumptions, coupling, edge cases).
│   ├── doubt-architect.md   Blue-team reviewer — must propose concretely better
│   │                        design alternatives, not just critique.
│   └── doubt-realist.md     Value/feasibility reviewer — YAGNI, simpler paths,
│                            user impact, plan-vs-code grounding drift.
├── pi-global/
│   ├── AGENTS.md             Global agent discipline rules (always loaded by pi in
│   │                         every project; deployed to ~/.pi/agent/ by bootstrap).
│   └── .pi-lsp.json          Default LSP server config for pi-lsp-extension
│                             (auto-start: python, typescript, bash).
├── skills/code-grounding/   Planning-time LSP scan battery (overview → symbols →
│                           definitions → references); deployed to ~/.pi/agent/
│                           skills/ by bootstrap; fires during OpenSpec planning.
├── openspec-schema/         OpenSpec workflow schemas (deployed to
│                           ~/.local/share/openspec/schemas/ by bootstrap).
├── agents/                  doubt-review reviewer agents (deployed to
│                           ~/.pi/agent/agents/ by bootstrap).
├── forge_setup.md           Cheat sheet: Forgejo git auth + internal-https recipe.
├── bootstrap.sh             One-shot new-machine setup (12 steps): install pi, packages,
│                           LSP servers, .pi-lsp.json, .tmux.conf, browser deps, settings
└── package.json             Root manifest: pi entry points + ALL runtime deps
                             (one node_modules, one npm install for the whole repo).

Interactive subagents (amosblomqvist/pi-interactive-subagents) are not in this repo: bootstrap installs the vanilla upstream package alongside the Forgejo one. Roles as shipped upstream — scout: local, read-only, fast file scanner (no web tools); researcher: web/deeper exploration; worker: implementer. This repo adds three read-only doubt-review agents (agents/, deployed to ~/.pi/agent/agents/): they run the 3× parallel plan review of the doubt-review OpenSpec schema and can park themselves with ask_question when they surface a decision only the user can make (the orchestrator relays via ask_user_question).

Tool surface

Tool	From	Purpose
web_search	web-search	SearXNG/Google search with structured queries
web_fetch	web-fetch	URL → clean markdown (HTML, PDF, RSC)
browser_goto/eval/console/network/fill/click/screenshot/close	browser	Drive a live 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	subagents (vanilla upstream package)	Spawn and steer tmux subagents
ask_question	subagents (vanilla upstream package)	(subagent sessions only) Ask the orchestrator, park as waiting

Requirements

Requirement	Needed for	Notes
Node.js + npm	everything	pi is an npm package
pi install git:forge.angelhost.eu/Lynx/pi-config	this whole setup	installs the repo + runs npm install for all deps
SearXNG instance with search.formats: [json]	web_search (SearXNG backend)	or Google CSE keys as fallback backend
Playwright binaries: npx playwright-core install chromium firefox	browser	one-time download per machine
Browser system libs (Arch: gtk3 nss nspr alsa-lib libx11 ...)	browser	full list in bootstrap.sh; required even headless (linked, not a display server)
tmux	interactive-subagents	subagents run in tmux panes
pi install git:github.com/amosblomqvist/pi-interactive-subagents	subagent tools	done by bootstrap.sh; vanilla upstream, updated via pi update --extensions
certutil (pacman -S nss) + your root CA	browser over internal https	only if browsing private-CA domains
NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt	web_search/web_fetch over internal https	Node ignores the OS trust store; pointing it at the system bundle picks up imported CAs
bash-language-server	LSP for shell scripts	npm install -g bash-language-server
python-lsp-server (pylsp)	Python LSP fallback for pi-lsp-extension	pip install python-lsp-server

Install (new machine)

git clone https://forge.angelhost.eu/Lynx/pi-config && cd pi-config
./bootstrap.sh                      # everything: pi, packages, deps, settings

Or manually:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi install git:forge.angelhost.eu/Lynx/pi-config
pi install git:github.com/amosblomqvist/pi-interactive-subagents

bootstrap.sh also merges default settings (hideThinkingBlock, model/provider defaults), downloads browser binaries, and deploys a global .pi-lsp.json (symlinked into project dirs under ~/projects/). Safe to re-run. See forge_setup.md for Forgejo token setup and the internal-https recipe.

Environment variables

Variable	Default	Effect
SEARXNG_URL	unset	SearXNG base URL — takes precedence over Google backend
GOOGLE_SEARCH_API_KEY / GOOGLE_CSE_ID	unset	Google CSE fallback backend
SEARXNG_AUTH	unset	user:password for basic-auth'd SearXNG
PI_BROWSER_ENGINE	chromium	chromium, firefox, or auto
PI_BROWSER_ROOT_CA	unset	Root CA pem imported into browser NSS stores
PI_BROWSER_IGNORE_TLS	unset	Last resort: accept self-signed certs outright
PI_BROWSER_ENABLED	unset	1 = browser tools active from session start
PI_BROWSER_HEADFUL	unset	Launch a visible window
NODE_EXTRA_CA_CERTS	unset	Set to the system CA bundle for internal https

Keeping machines in sync

• Repo changes (this repo): edit → commit → push → pi update --extensions on other machines.
• Upstream packages (pi-lsp-extension, pi-interactive-subagents): vanilla installs — update with pi update --extensions; no local forks to maintain.
• Settings are machine-local by design; bootstrap.sh only sets what this repo manages.
• LSP config (.pi-lsp.json): lives in pi-global/.pi-lsp.json in this repo. bootstrap.sh deploys it to ~/.pi/.pi-lsp.json and symlinks into ~/projects/*/. Edit the repo copy, commit and push, then re-run bootstrap.sh or symlink manually.

Credits

• amosblomqvist/pi-config — web-fetch, ask-user-question, and the base of the browser extension.
• amosblomqvist/pi-interactive-subagents (fork of HazAT's) — the subagent engine, installed as a vanilla upstream pi package (MIT).
• pi by Mario Zechner / earendil-works.