pi-config

My personal pi configuration.

The setup from My Pi Setup After 6 Months (and its predecessor, Pi Coding Agent Setup After 2 Months).

This is not meant to be installed as one big package. Browse the repo and copy the pieces you want into your own Pi config.

Some extensions are big enough to live in their own repositories:

• pi-interactive-subagents — async subagents on tmux or Herdr terminal surfaces, maintained in a separate fork
• pi-observational-memory — V3 branch-local observations/reflections with deterministic compaction
• pi-web-access — web search and content retrieval, replacing this catalogue's former local web-search and web-fetch extensions

The active catalogue contains three local extension implementations, four README-only external integration stubs, seven local skill implementations, and one README-only external skill stub. Stub directories point to external projects rather than vendoring their code.

For an architectural overview, see the coarse system map.

Copy an extension

Single-file extension:

cp extensions/ask-user-question.ts ~/.pi/agent/extensions/

Directory extension:

cp -r extensions/prompt-snippets ~/.pi/agent/extensions/

The three active local extensions have no extension-local package manifest or dependency-install step. External catalogue stubs are installed with the separately documented package or plugin command rather than copied from this repository.

Then restart pi or run /reload.

Install an externally maintained integration

Directories described as stubs contain documentation only; do not copy them as implementations. Follow each stub's reviewed pin, requirements, state boundary, and upstream links:

• extensions/herdr-annotate/ — pinned Herdr Annotate Lite plugin; a Herdr integration, not a Pi extension.
• extensions/interactive-subagents/ — maintained fork for async tmux/Herdr child agents.
• extensions/observational-memory/ — pinned npm V3 observational-memory package and local-model reproducibility notes.
• extensions/web-access/ — external pi-web-access package.
• skills/effective-html/ — pinned Pi package exposing six HTML artifact skills.

Copy a skill

cp -r skills/pdf-reader ~/.pi/agent/skills/

Then restart pi or run /reload.

Do not clone over your config

Avoid cloning this repo directly into ~/.pi/agent unless it is a fresh setup. If you already use pi, copy individual files/folders instead so you don't replace your own config.

Contents

Extensions

• ask-user-question.ts — the agent asks you a question through a UI popup; popups from different extensions serialize via a shared UI lock
• custom-header.ts — the big capital Π header
• herdr-annotate/ — README-only external stub for pinned Herdr Annotate Lite; it is a Herdr plugin, not a Pi extension
• interactive-subagents/ — README-only external stub, see gpmarques/pi-interactive-subagents
• observational-memory/ — README-only external stub, see elpapi42/pi-observational-memory; documents the pinned npm 3.0.4 local-Qwen setup
• prompt-snippets/ — small, reusable behavior rules toggled onto a message before sending; reset after send; includes close-retrospective.md for invoking the bounded closure routine
• web-access/ — README-only external stub, see pi-web-access

Skills

• analyze-sessions/ — Python scripts to query past pi sessions: cost rollups, prompt-pattern mining, session rendering
• effective-html/ — README-only external stub for a pinned Pi package providing six standalone HTML artifact skills
• pdf-reader/ — read PDFs (lecture notes, papers) into the context
• session-retrospective/ — a bounded, evidence-based closure routine that carries approved general lessons through implementation and verification
• simple-visual-presenter/ — a simple visual-presentation workflow that composes show-me, Effective HTML, and bounded visual QA while keeping the source authoritative
• software-factory/ — a four-gate feature workflow—Product, Architecture, Program Design, then Vertical Slices—with explicit approval before implementation
• web-debug/ — a runtime-first frontend debugging playbook driven through the installed agent-browser CLI
• youtube-transcript/ — fetch a YouTube video's title and transcript as JSON

Deprecated

deprecated/ holds the extensions and skills from the two-month setup that are no longer in active use. They are kept for reference, not as a supported install set: some still work, while others reference removed extension paths or tool names and require adaptation or restored dependencies.

Dependencies

The three local extensions have no extension-local package manifests or nested npm setup. README-only stubs have no local runtime dependencies because their implementations and setup remain external. The Herdr Annotate Lite integration requires Herdr 0.8.0 or later and Bun; Linux clipboard support also requires wl-clipboard, xclip, or xsel. Effective HTML is installed as a pinned Pi package and has no runtime service or account requirement.

web-debug/ requires an external agent-browser executable; it is not an extension-local dependency. After copying the skill, check availability and version:

command -v agent-browser
agent-browser --version

The bundled workflows are validated against agent-browser 0.18.0. If another version is installed, consult its top-level and relevant subcommand help before using the examples. The skill fails closed when the executable is unavailable and does not install or switch to another browser provider.

Optional system tools:

brew install yt-dlp

Used by youtube-transcript/. Python 3 is needed for youtube-transcript/ and analyze-sessions/ (stdlib only).

PDF reader setup after copying skills/pdf-reader/:

python3 -m venv ~/.pi/agent/skills/pdf-reader/.venv
~/.pi/agent/skills/pdf-reader/.venv/bin/pip install -r ~/.pi/agent/skills/pdf-reader/requirements.txt