Lincoln504 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:
knowledge600000ms ·research --depth 11500000ms ·--depth 21800000ms ·--depth 32400000ms. 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: trueon 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 exit75(see Exit codes). Prefer oneresearchcall with a well-scoped query over splitting one topic into many parallel calls — depth 1 already parallelises internally.
Workflow
- Knowledge store first (always). Run one
knowledgecheck 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.
- 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").
- Depth
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.