pi-short-docs

Replace pi's verbose built-in <docs> system-prompt section with a one-line pointer to the installed pi README.

<docs>
-Pi documentation (read only when the user asks about the harness itself, its SDK, extensions, themes, skills, or TUI):
-- Main documentation: /…/node_modules/@earendil-works/pi-coding-agent/README.md
-- Additional docs: /…/node_modules/@earendil-works/pi-coding-agent/docs
-- Examples: /…/node_modules/@earendil-works/pi-coding-agent/examples (extensions, custom tools, SDK)
-- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
-- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), packages (docs/packages.md), environment variables (docs/environment-variables.md), MCP servers (docs/mcp.md), codemode scripts and non-LLM models such as classifiers and image models (docs/codemode.md)
-- Before implementing harness changes, read the relevant docs and examples in full, following related cross-references.
+Pi documentation (read only when the user asks about pi itself): /…/node_modules/@earendil-works/pi-coding-agent/README.md
</docs>

~1,257 chars → ~125 chars (~280 tokens) per request — and it stays cached, because the change is recorded, not per-request (see below).

Install

pi install npm:pi-short-docs

Or install from git:

pi install git:github.com/dam9000/pi-short-docs

Requires pi 1.3 or newer (the named section map on systemPromptOptions) and Node.js 22.19 or newer. Run /reload after installing. To undo: pi remove … and /reload — the next prompt diff restores pi's default docs section.

What it does

A before_agent_start handler sets event.systemPromptOptions.sections["docs"] to a single line:

Pi documentation (read only when the user asks about pi itself): <readme path>

• The pointer mirrors pi's default heading shape (gate in parens, value after the colon) and resolves the path with pi's own getReadmePath() — the same function pi's prompt builder uses — so it stays correct for any install layout (npm/pnpm/yarn/Nix, PI_PACKAGE_DIR override).
• The README is a sufficient entry point: it links docs/index.md, which acts as a hub for the major reference pages; the rest is one cross-reference away, and the package root is the README's parent directory.
• Only the docs section is touched. preamble, tools, rules, project_context, skills, cwd are left exactly as pi built them.

Why a recorded override (not per-request trimming)

pi persists the section change as a normal section patch in the session, so every consumer of the recorded prompt state sees the same head: pi's own chat requests, compaction, and model requests built by other extensions from the session state (e.g. pi-protokoll's protocol backfill/follow-up requests).

Per-request trims (the context_with_system approach used by pi-trim) only reach pi's own chat requests — other extensions' requests carry the untrimmed head. With local models and a shared prefix cache (llama.cpp), that head divergence invalidates the cached prefix on every such request. The recorded override keeps all request heads byte-identical, so the provider's prompt cache stays warm.

Limits

• The section is replaced, not removed: pi's builder only accepts non-empty section content. If you replace the whole prompt via SYSTEM.md, pi no longer emits a default docs section; this extension then adds the pointer line as its own docs section (harmless, and usually desirable).
• The pointer line assumes the installed package's README keeps serving as the documentation entry point. It does not hard-code any pi version's wording, so prompt rewording upstream does not affect it.
• No new runtime dependencies. The extension is a single ~40-line file with one import from the host package.

License

MIT