pi-librarian

GitHub-focused research subagent package for pi.

Installation

From npm (after publish):

pi install npm:pi-librarian

From git:

pi install git:github.com/default-anton/pi-librarian

Or use without installing:

pi -e npm:pi-librarian
# or
pi -e git:github.com/default-anton/pi-librarian

What it does

• Registers a librarian tool for GitHub code investigation via gh, using known query context when provided (without guessing unknown scope).
• Runs a dedicated subagent session with a strict fixed turn budget (10 turns).
• Uses only bash + read tools in the subagent.
• Instructs the subagent to use gh directly for search/tree/fetch workflows.
• Caches only selected files in an isolated temporary workspace under /tmp/pi-librarian/run-*/repos/....
• Returns the subagent's final Markdown answer as-is (no extension-side post-processing).
• Selects subagent model via ordered PI_LIBRARIAN_MODELS failover with ctx.model fallback.
• Emits compact selection diagnostics (reason) in tool details.

Tool interface

librarian({
  query: string,
  repos?: string[],
  owners?: string[],
  maxSearchResults?: number,
})

Model selection policy

Librarian uses local deterministic model routing with ordered failover.

Configure candidates with PI_LIBRARIAN_MODELS:

PI_LIBRARIAN_MODELS="provider/model:thinking,provider/model:thinking,..."

Concrete example:

export PI_LIBRARIAN_MODELS="openai-codex/gpt-5.3-codex-spark:high,google-antigravity/gemini-3-flash:medium,anthropic/claude-sonnet-4-6:high"

Rules:

• thinking must be one of: off, minimal, low, medium, high, xhigh.
• Tokens are parsed in order (comma-separated, trimmed, empty tokens ignored).
• Each token is filtered by:
  1. ctx.modelRegistry.getAvailable()
  2. Librarian's in-memory temporary-unavailable cache (reason-aware TTL)
• Librarian picks the first candidate passing both filters.
• If PI_LIBRARIAN_MODELS is unset/blank, or no candidate passes filters, Librarian tries ctx.model fallback using the same availability + temporary-unavailable filters.
• On any final non-abort model failure, Librarian fails over to the next available candidate.
• Temporary-unavailable TTLs are:
  • quota-like final failures: 30 minutes
  • other final failures: 10 minutes
• Librarian does not add its own retry/backoff loop for transient errors; SDK retry behavior remains the first-line retry mechanism.
• Selection diagnostics stay compact and expose only subagentSelection.reason.

gh workflow examples (tested)

These are the same patterns encoded in the librarian system prompt.

Public repo example (cli/cli)

# code search
gh search code "NewCmdRoot" --repo cli/cli --json path,repository,sha,url,textMatches --limit 3

# repo tree
gh api "repos/cli/cli/git/trees/trunk?recursive=1"

# fetch one file into local cache
REPO='cli/cli'
REF='trunk'
FILE='pkg/cmd/root/root.go'
mkdir -p "repos/$REPO/$(dirname "$FILE")"
gh api "repos/$REPO/contents/$FILE?ref=$REF" --jq .content | tr -d '\n' | base64 --decode > "repos/$REPO/$FILE"

Private repo example (default-anton/jagc)

# code search with path matching
gh search code "README.md" --repo default-anton/jagc --match path --json path,repository,sha,url --limit 3

# repo tree
gh api "repos/default-anton/jagc/git/trees/main?recursive=1"

# fetch one file into local cache
REPO='default-anton/jagc'
REF='main'
FILE='README.md'
mkdir -p "repos/$REPO/$(dirname "$FILE")"
gh api "repos/$REPO/contents/$FILE?ref=$REF" --jq .content | tr -d '\n' | base64 --decode > "repos/$REPO/$FILE"

If a repo is inaccessible, gh returns 404/403; the subagent should report that constraint.

Requirements

• GitHub CLI installed.
• GitHub CLI authenticated (gh auth login).

No proactive auth pre-check is performed; command failures from gh are surfaced directly.

The subagent runs with cwd set to that temporary workspace, so relative writes stay in /tmp/pi-librarian/run-* and do not touch your project repository.

License

Apache-2.0