librarian

A pi GitHub research scout inspired by pi-librarian, with a local checkout cache disabled by default.

When the librarian tool runs, it can cache/reuse repository checkouts locally. Use /librarian-cache off to force GitHub API/search and temporary fetched files only, or /librarian-cache on to re-enable cached local checkouts.

The internal librarian subagent uses a fast auto-selected model by default, requests low thinking, and prompts its scout to batch independent GitHub probes in parallel. Automatic candidates and fallbacks stay within the current Pi session's model scope when that scope is non-empty; an explicit tool or /librarian-config model remains authoritative. Use /librarian-config to set a persistent internal model or thinking-level preference.

Install

Standalone npm package

pi install npm:@diegopetrucci/pi-librarian

Collection package

pi install npm:@diegopetrucci/pi-extensions

GitHub package

pi install git:github.com/diegopetrucci/pi-extensions

Then reload pi:

/reload

Behavior

• Tool name: librarian
• Uses a restricted subagent with bash, read, and any configured MCP tools (MCP tools run without confirmation; may have side effects; use for evidence gathering only; requires host Pi >=1.0.4; older hosts degrade to no MCP, no error); the global mcp.json always applies; a project .pi/mcp.json is never loaded (the librarian subagent runs in a separate temp workspace)
• Uses gh for GitHub search/API access
• Uses cached local checkouts only when enabled
• Toggle cache behavior for future calls with /librarian-cache on | off | toggle | status
• Configure internal subagent defaults with /librarian-config status | model <provider/model|auto> | thinking <off|minimal|low|medium|high|xhigh|max|auto> | clear [all|model|thinking]
• Cached repos are removed lazily after 7 days without use

Commands

/librarian-cache status
/librarian-cache off
/librarian-cache on
/librarian-cache toggle

/librarian-config status
/librarian-config model auto
/librarian-config model anthropic/claude-haiku-4-5:medium
/librarian-config thinking low
/librarian-config clear model

The commands work in interactive mode, RPC mode, and print/JSON mode. They write global preferences to ~/.pi/agent/extensions/librarian.json, so separate non-UI invocations use the same settings. In non-UI modes, command feedback is written to stderr so stdout remains usable for normal output or JSON events.

Cache location

macOS:

~/Library/Caches/pi-librarian/repos/github.com/<owner>/<repo>

Linux:

${XDG_CACHE_HOME:-~/.cache}/pi-librarian/repos/github.com/<owner>/<repo>

Windows:

%LOCALAPPDATA%\pi-librarian\repos\github.com\<owner>\<repo>

Override the cache root if needed:

export PI_LIBRARIAN_CACHE_ROOT="$HOME/Library/Caches/pi-librarian/repos"

Requirements

• GitHub CLI (gh) installed and authenticated for private repositories you want to inspect
• git for local checkout caching
• common shell tools such as rg, jq, and base64 for best results

Notes

Do not install this alongside another extension that registers a librarian tool unless you intentionally want duplicate/conflicting tool names.