pi-research skill

Run via your shell tool — the Bash tool in Claude Code, whatever equivalent your harness exposes elsewhere. <SKILL_DIR> is this skill's own directory: substitute the absolute path your harness reports for this skill (some harnesses expose it as {baseDir}).

node "<SKILL_DIR>/scripts/run.mjs" research  "<query>" --depth 1
node "<SKILL_DIR>/scripts/run.mjs" knowledge "<query>" ["<q2>" ...]
node "<SKILL_DIR>/scripts/run.mjs" status    [--json]

• stdout = Markdown report — read and cite it.
• stderr = progress + errors — relay errors, suppress routine progress.
• Always set a generous command timeout so a stalled run can't block forever, but leave plenty of headroom — a real run should finish well inside it: knowledge 600000ms · research --depth 1 1500000ms · --depth 2 1800000ms · --depth 3 2400000ms. These already include headroom for the run to sit queued behind other runs on a busy machine (see below); don't shorten them on the assumption a slot is free.
• Background — use ONE mechanism, never two. If your shell tool has its own background option (e.g. run_in_background: true on Claude Code's Bash tool), use that alone and do not also append &: with both, the shell forks the run and exits at once, the harness reports that instant exit as "completed" while the research continues detached, and the completion notification is meaningless. Only on a harness with no background option, append & and keep the PID — and then wait on that PID, not on any "completed" signal, before reading output. Otherwise it runs foreground (blocks). Timeouts apply either way.
• Several at once is fine. Up to 3 runs execute concurrently machine-wide (shared with any other tool or agent on this machine); further runs queue for a slot and report • queued: … on stderr — that is normal, not a stall. Only if nothing frees up within the queue window does a run exit 75 (see Exit codes). Prefer one research call with a well-scoped query over splitting one topic into many parallel calls — depth 1 already parallelises internally.

Workflow

1. Knowledge store first (always). Run one knowledge check with the same intent before any live research — it's instant and free.
   • Complete answer → use it, skip live research.
   • Partial → note it, fill gaps with research.
   • Exit 78 → store is off in this directory; proceed with research. Don't mention it unless the user asks — then see Knowledge store scope below to turn it on.
2. Live research — always depth 1. It's the default and correct for effectively every request; depth 1 already decomposes and parallelises internally, so it covers big/broad/complex/important topics too. Do NOT raise depth on your own judgment.
   • Depth 2 — super rare: only a genuinely ultra-broad or unusually detailed topic where the user signalled they want deeper/thorough work. Unsure → depth 1.
   • Depth 3 — never unless the user explicitly asks for ludicrously deep / exhaustive research ("ultra", "exhaustive", "comprehensive deep-dive", "maximum").

Reporting back to the user (always)

• Cite the report's sources. Carry its URLs/[n] references into your answer; attribute each non-trivial claim. Never present researched facts as unsourced; never invent or substitute sources.
• Surface the saved file. Look for a saved-report line: stdout's report footer ends with Research report saved to: <path>, and stderr carries [pi-research] report saved to: <path>. Give the user that exact path. If neither appears, no file was written — say nothing about one.

Exit codes

Exit	Meaning	Action
0	Success	Read stdout; cite sources; relay any "saved to: " line.
78 on knowledge	Two cases — read stderr to tell them apart.	Says the store is disabled: silent; proceed to research. Mentions credentials/model/API key: this is the same hard config failure as 78 on research — stop and relay full stderr; don't silently continue, research will fail the same way.
78 on research	Engine missing or no model/key	Stop. Relay full stderr (it shows where to configure). Don't retry until fixed.
75	Machine at capacity — other research runs are already using every slot	Nothing is broken. Wait for an in-flight run to finish, then retry this query once. Don't reconfigure anything and don't retry in a tight loop.
130 (and 129/131/143)	Cancelled — the run was interrupted. These are the POSIX 128 + signal codes: 130 Ctrl-C/SIGINT, 143 SIGTERM, 129 SIGHUP, 131 SIGQUIT. Treat any exit ≥ 128 as a cancellation.	Nothing is broken and nothing failed. Say the research was cancelled. Do NOT re-run it unless the user asks; they stopped it deliberately.
70	Runtime error	Relay stderr; suggest one retry for transient failures (network, rate limit).
64	Bad arguments	Fix args; don't surface unless the query itself is malformed.

Knowledge store scope (act on the user's request)

The knowledge store — what knowledge searches — is on by default (mode global) and scoped per directory: global (one shared store), project (this directory only), or none (off here). The user manages it by asking you in chat — they don't have to run anything themselves.

When the user asks you to turn the store off, make it global, or scope it to this project for the current directory (or clearly implies a preference), do it on their behalf and tell them the new setting. Check the current one first if useful:

node "<SKILL_DIR>/scripts/run.mjs" knowledge-config                    # current mode + where it's set
node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set <none|project|global>   # pick ONE value

The change applies to the current directory on the next run. Never change it unprompted.

When NOT to use this

WEB / internet research ONLY. Never use it to investigate this project (source, config, architecture, tests, logs, anything on this machine) — use your own Read/Grep/Bash for that. Reach for pi-research only when the answer lives on the public internet or in the knowledge store.

Configuration (relay only on exit 78 from research)

On exit 78 the engine prints exact configure locations to stderr — relay verbatim:

config file:  ~/.pi/research/config.env
env vars:     PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
pi config (keys):    ~/.pi/agent/auth.json   (supplies the API key only)
pi config (models):  ~/.pi/agent/models.json

PI_RESEARCH_MODEL (a provider/model-id) is always required — pi's configuration supplies only the key, and the skill never uses the model selected inside the pi extension.

Run status for the resolved paths on this machine. Full reference: references/configuration.md.

The engine shuts down cleanly on every exit (browser pool, LanceDB, embedding model all released) — nothing is left behind between runs.