Pi Toolbox

Deferred tool loading for Pi.

Keep heavyweight tool schemas out of normal model context, then enable them only when the user prompt needs them.

Why

Pi sends active tool schemas with model requests. Big tool groups like Web, MCP, notes, databases, issue trackers, or docs search can add unnecessary context and cost to every turn.

Toolbox keeps ordinary turns lean and activates heavy tool groups only for prompts that need them.

What it does

• Keeps one tiny always-on fallback tool: enable_toolbox
• Removes configured heavy tool groups from normal turns
• Detects user intent in Pi's input event before the model request starts
• Enables matching tools for that same prompt
• Lets the model use those tools in the same turn
• Restores lean tools after the agent run
• Avoids hidden/fake follow-up messages

How it works

Pi lifecycle used by Toolbox:

user input
  ↓
input event
  ↓
before_agent_start
  ↓
model request
  ↓
tool calls
  ↓
agent_end

Toolbox flow:

1. session_start / session_switch strips heavy tools and records lean baseline.
2. input inspects raw user prompt.
3. If prompt matches a domain, Toolbox enables that domain's tools immediately.
4. before_agent_start sees the current prompt was enabled and does not strip those tools.
5. Model request includes only normal tools + matching heavy tools.
6. Model can call those heavy tools in the same turn.
7. agent_end restores lean baseline and clears status.

This means prompts like:

Update note:Y3NuISlJ with latest changes

can activate Inkdrop tools before the LLM starts, so the same turn can call inkdrop_read / inkdrop_save.

Prompts like:

Search web for latest AI news and summarize the second result

can activate Web tools before the LLM starts, so the same turn can call websearch / webfetch.

Prompts that mention both can activate both:

Create an Inkdrop note from the latest AI news on the web

Same-turn automation vs fallback

Toolbox has two activation paths.

1. Automatic input intent

Best path. The extension detects intent before the model request, enables tools, and the model uses them immediately.

No extra user prompt. No fake follow-up. No enable_toolbox call.

2. Manual fallback tool

If intent detection misses something, the model can call:

enable_toolbox({ domain: "web" })

The tool returns:

toolbox_enabled

It also remembers the requested domain for the next user prompt. So if the next prompt is only:

continue

Toolbox still enables the remembered domain before the model starts.

This fallback exists because pi.setActiveTools() changes the active tools for later model calls, not the already-running model request.

Install

Recommended: Pi package install

pi install npm:@jdrly/pi-toolbox

Git install also works:

pi install https://github.com/jdrly/pi-toolbox

Then reload Pi:

/reload

Pi reads package.json from npm or git and loads:

{
  "pi": {
    "extensions": ["./extensions/toolbox.ts"]
  }
}

Manual install

Clone repo somewhere stable:

git clone https://github.com/jdrly/pi-toolbox.git ~/.pi/extensions/pi-toolbox

Add package to Pi settings:

{
  "packages": [
    "../extensions/pi-toolbox"
  ]
}

Or load extension directly:

pi -e ~/.pi/extensions/pi-toolbox/extensions/toolbox.ts

Reload Pi:

/reload

Wire your own tools

Edit extensions/toolbox.ts.

1. Define tool groups

Default example:

const WEB_TOOLS = ["webfetch", "websearch"];
const INKDROP_TOOLS = [
  "inkdrop_titles",
  "inkdrop_search",
  "inkdrop_read",
  "inkdrop_save",
];

Add your own groups:

const GITHUB_TOOLS = ["gh_issue_search", "gh_pr_read", "gh_issue_update"];
const DOCS_TOOLS = ["docs_search", "docs_read"];

2. Extend domain type

type Domain = "web" | "inkdrop" | "both";

Example:

type Domain = "web" | "inkdrop" | "github" | "docs" | "both";

3. Include groups in heavyTools

function heavyTools(): string[] {
  return [...WEB_TOOLS, ...INKDROP_TOOLS];
}

Example:

function heavyTools(): string[] {
  return [...WEB_TOOLS, ...INKDROP_TOOLS, ...GITHUB_TOOLS, ...DOCS_TOOLS];
}

4. Map domains to tool groups

function domainTools(domain: Domain): string[] {
  if (domain === "web") return WEB_TOOLS;
  if (domain === "inkdrop") return INKDROP_TOOLS;
  return heavyTools();
}

Example:

function domainTools(domain: Domain): string[] {
  if (domain === "web") return WEB_TOOLS;
  if (domain === "inkdrop") return INKDROP_TOOLS;
  if (domain === "github") return GITHUB_TOOLS;
  if (domain === "docs") return DOCS_TOOLS;
  return heavyTools();
}

5. Detect intent from prompts

function detectDomain(text: string): Domain | undefined {
  const wantsInkdrop = /\b(inkdrop|note:[a-z0-9_-]+|book:[a-z0-9_-]+)\b/i.test(text);
  const wantsWeb = /\b(web|search web|latest|https?:\/\/)\b/i.test(text);

  if (wantsInkdrop && wantsWeb) return "both";
  if (wantsInkdrop) return "inkdrop";
  if (wantsWeb) return "web";
  return undefined;
}

Example GitHub detector:

const wantsGitHub = /\b(github|issue #?\d+|pr #?\d+|pull request)\b/i.test(text);
if (wantsGitHub) return "github";

Example docs detector:

const wantsDocs = /\b(docs|documentation|api reference|sdk)\b/i.test(text);
if (wantsDocs) return "docs";

Keep regexes conservative. False positives activate more tools than needed.

Prompt guidance

Toolbox registers enable_toolbox with guidance telling the model:

• auto-detection handles most Web/Inkdrop prompts
• call enable_toolbox only if needed tools are missing
• after calling it, output only toolbox_enabled
• next user prompt will have requested tools active

When adding domains, update description, promptSnippet, and promptGuidelines so the model knows when to use the fallback.

Status indicator

When Toolbox enables a domain, it sets Pi status:

🧰web
🧰inkdrop

Status clears after agent_end restores lean tools.

Notes

• Tool names must match registered Pi tool names.
• Missing tools are ignored.
• Normal coding/local-file prompts stay lean.
• Same-turn automation depends on input intent detection, not on the fallback tool.
• Fallback enable_toolbox cannot make new tools available inside the already-running model request.

License

MIT