pi extensions

A small collection of extensions for pi-coding-agent.

Included extensions

File	What it does	How to use	Requirements
auth-backup.ts	Manages backups of ~/.pi/agent/auth.json through a single interactive command	Run /auth-backup	Interactive UI
branch-pr-widget.ts	Shows the GitHub PR for the current branch	Auto-runs on session start and after agent turns	gh installed, current repo branch associated with a PR
docs-changes.ts	Shows changed files under docs/ as a widget	Auto-runs on session start and after agent turns	Git repo with a docs/ directory
export-dialogue.ts	Exports the current branch to a dated, LLM-titled JSONL file	Run /xp	Active model credentials; optional PI_XP_PATH
replace-pi-with-claude-code.ts	Rewrites pi to claude code in the system prompt	Auto-runs before each agent start and before each provider request	None
read-url.ts	Adds a read_url tool that reads public URLs as Markdown through Jina Reader	Agent calls read_url when it needs external docs	Optional JINA_API_KEY for authenticated Jina quota
usage-widget.ts	Shows Anthropic or Codex usage bars for the active provider	Auto-runs on session start, model change, and after agent turns	Valid Anthropic OAuth or OpenAI Codex auth
fix-anthropic-thinking-block-drop.ts	Reinjects signed thinking blocks that pi-ai drops, avoiding Anthropic 400 errors on Opus/Sonnet 4.8	Auto-runs before each Anthropic provider request	Anthropic model with thinking enabled

Installation

Copy any extension file into your pi extensions directory:

cp auth-backup.ts ~/.pi/agent/extensions/
cp branch-pr-widget.ts ~/.pi/agent/extensions/
cp docs-changes.ts ~/.pi/agent/extensions/
cp export-dialogue.ts ~/.pi/agent/extensions/
cp replace-pi-with-claude-code.ts ~/.pi/agent/extensions/
cp read-url.ts ~/.pi/agent/extensions/
cp usage-widget.ts ~/.pi/agent/extensions/
cp fix-anthropic-thinking-block-drop.ts ~/.pi/agent/extensions/

Then reload pi:

/reload

You can also load a file directly for testing:

pi -e ./auth-backup.ts

Extensions

auth-backup.ts

Interactive auth backup manager for ~/.pi/agent/auth.json.

Behavior:

• Stores backups under ~/.pi/agent/auth-backups/
• Uses one command: /auth-backup
• Shows an interactive list with:
  • + New auth backup
  • existing backups with creation time and provider summary
• For an existing backup, opens an action menu:
  • Backup current auth here
  • Restore this backup
  • Delete this backup

Restore overwrites the full ~/.pi/agent/auth.json and reloads pi.

Use it when:

• you switch between multiple auth setups
• you want to save the current login state before replacing it
• you want to restore a previous full auth state quickly

Screenshots

Backup list:

Action menu:

branch-pr-widget.ts

Shows the GitHub PR number and URL for the current branch.

Behavior:

• Runs gh pr view --json number,url
• Displays a widget when a PR is found
• Refreshes on:
  • session_start
  • session_switch
  • agent_end

Use it when:

• you work in a GitHub repo with branch-to-PR mapping
• you want the active PR visible in the UI

docs-changes.ts

Shows changed files in docs/ as a widget.

Behavior:

• Reads tracked changes from git diff --name-status HEAD -- docs/
• Reads untracked files from git ls-files --others --exclude-standard -- docs/
• Ignores docs/index.md and nested index.md
• Refreshes on:
  • session_start
  • session_switch
  • agent_end

Use it when:

• you are editing documentation alongside code
• you want a compact docs change summary visible at all times

export-dialogue.ts

Exports the active session branch to JSONL with a filename generated by the active model.

Behavior:

• Registers /xp
• Waits for the current agent run to settle, then snapshots the active branch
• Uses the current model and compaction-aware session context to generate a concise title without appending the title request to the session
• Writes {YYYY-MM-DD}-{title}.jsonl
• Re-chains branch entry parent IDs into a linear JSONL session
• Overwrites an existing file with the same name
• Reads the destination directory from PI_XP_PATH, falling back to pi's current working directory
• Requires the destination directory to exist and be writable

Optional destination configuration:

export PI_XP_PATH="/Users/sukit/Mars/life-engineering/5. Dialogues"

Use it when:

• you want a portable JSONL transcript of the current branch
• you want dialogue exports named by topic instead of session UUID

replace-pi-with-claude-code.ts

Rewrites occurrences of pi in the system prompt to claude code before each run.

Behavior:

• Hooks before_agent_start for turns started by typed input or sendUserMessage
• Hooks before_provider_request and rewrites the serialized system blocks, covering turns triggered by extension custom messages (pi.sendMessage with triggerTurn), which never fire before_agent_start
• Replaces pi case-insensitively with claude code
• Preserves cache_control and other block fields; leaves message content and non-Anthropic payload shapes untouched
• Idempotent: an already-rewritten prompt passes through unchanged

Use it when:

• you want the agent framed as Claude Code instead of pi
• you use Anthropic subscription OAuth, whose billing classifier rejects requests that do not look like Claude Code with 400 "You're out of extra usage" even when quota remains

read-url.ts

Adds a read_url tool for reading public HTTPS URLs as LLM-friendly Markdown using Jina Reader.

Behavior:

• Registers a read_url tool callable by the agent
• Uses anonymous Jina Reader requests first
• Falls back to JINA_API_KEY when anonymous quota is exhausted and the environment variable is set
• Caches successful fetches for 30 days under ~/.pi/agent/caches/read-url/
• Stores each cached document as:
  • content.md
  • meta.json
• Uses readable cache directory names, with a short URL hash suffix to avoid collisions
• Canonicalizes document URLs by default:
  • removes fragments
  • strips query parameters
  • removes non-root trailing slashes
• Supports line-based pagination with offset and limit
• Provides compact TUI rendering, with expandable results
• Returns actionable error messages for Jina rate limits, missing API keys, invalid API keys, insufficient balance, and stale-cache fallback

Tool parameters:

Parameter	Default	Description
url	required	HTTPS URL to read. Non-HTTPS URLs are refused
offset	1	1-based line offset for pagination
limit	300	Number of lines to return, max 1000
refresh	false	Force re-fetch and overwrite cache. Do not use by default
preserveQuery	false	Preserve query parameters when they are required for page content

Cache example:

~/.pi/agent/caches/read-url/
  openai.com--index-introducing-trusted-contact-in-chatgpt--178cf0649d10/
    content.md
    meta.json

Optional authenticated quota:

export JINA_API_KEY="..."

Use it when:

• you want the agent to inspect public documentation, blog posts, changelogs, or API references
• you want cached URL reading with pagination instead of manually pasting Markdown into the prompt
• you want anonymous Jina usage by default, with API-key fallback only when needed

Security note:

read_url puts external webpage content into the agent context. Treat every fetched page as untrusted input. Do not read random links, suspicious pages, or user-generated content you do not trust. A page can contain prompt injection text that tells the agent to ignore previous instructions, reveal secrets, call tools, run commands, or follow links.

The extension reduces this risk in a few ways:

• Tool output labels fetched content as untrusted external content
• Fetched content is wrapped inside a <document> boundary
• The tool guidelines tell the agent not to follow instructions inside fetched pages
• The tool does not use browser cookies or your logged-in Chrome session
• The tool refuses non-HTTPS URLs, so fetched content is not retrieved over unauthenticated HTTP transport

These are prompt-level mitigations, not a security boundary. They do not guarantee that the agent will never be influenced by malicious content. Only read URLs from sources you trust, such as official documentation, vendor docs, repository docs, and known technical blogs.

Limitations:

• Does not use browser cookies or your logged-in Chrome session
• Does not read non-HTTPS URLs
• Does not read private documents unless Jina Reader can access them publicly
• Query parameters are stripped by default; pass preserveQuery: true for search, pagination, filters, or pages where query parameters define the content
• Prompt injection remains possible if the fetched page contains malicious instructions

usage-widget.ts

Shows usage information for the active provider when supported.

Supported providers:

• anthropic
• openai-codex

Behavior:

• Displays usage bars for primary and secondary windows
• Shows reset times
• Computes a 7-day pace delta for Anthropic-style usage windows
• Caches usage briefly to avoid excessive requests
• Refreshes on:
  • session_start
  • model_select
  • agent_end

Data sources:

• Anthropic: https://api.anthropic.com/api/oauth/usage
• Codex: https://chatgpt.com/backend-api/wham/usage

Use it when:

• you want quota visibility while working
• you switch between Anthropic and Codex models

Screenshot

fix-anthropic-thinking-block-drop.ts

Workaround for an Anthropic 400 error seen on Opus/Sonnet 4.8:

thinking or redacted_thinking blocks in the latest assistant message cannot be modified

The root cause is in pi-ai: when building the Anthropic payload it drops any thinking block whose visible text is empty, even when the block is signed. With adaptive (summarized) thinking the model often emits signed thinking blocks with an empty summary, and Opus/Sonnet 4.8 rejects the replay when one is missing.

Behavior:

• Hooks before_provider_request and only acts on the anthropic-messages API
• Aligns each assistant message in the outgoing payload with the original session message from the tail
• Reinjects any signed, empty-text thinking block that pi-ai dropped, at its correct position
• Repairs same-model turns only; cross-model thinking drops are intentional and left untouched
• Bails out without modifying the payload if its model of pi-ai's transform diverges from the actual payload
• Sets a status line reporting how many blocks were reinjected

Use it when:

• you run Anthropic Opus/Sonnet 4.8 with adaptive (summarized) thinking
• you hit thinking ... blocks in the latest assistant message cannot be modified 400 errors
• you want a stopgap until upstream pi-ai keeps signed thinking blocks regardless of text emptiness

Notes

Extension	Notes
auth-backup.ts	Requires interactive UI. Restore replaces the full auth file, not a single provider entry.
branch-pr-widget.ts	Hidden when no PR is associated with the current branch or gh is unavailable.
docs-changes.ts	Hidden when there is no docs/ directory or no matching changes.
export-dialogue.ts	/xp makes a separate title-generation request with the active model. The request is not persisted in the exported session.
replace-pi-with-claude-code.ts	Only affects system prompt text (agent state and serialized provider payload), not UI labels, command names, or message content.
read-url.ts	Reads public URLs through Jina Reader. Set JINA_API_KEY only if you want authenticated fallback after anonymous quota is exhausted.
usage-widget.ts	Hidden when the active provider is unsupported or no usage data is available.
fix-anthropic-thinking-block-drop.ts	Workaround for a pi-ai thinking-block drop bug. Acts only on the anthropic-messages API and same-model turns. Remove once pi-ai keeps signed empty-text thinking blocks.

License

MIT License