pi-tools

pi-tools lets you expose additional CLI programs as pi tools through config files loaded globally and per project.

Goal

Use this extension when you want pi to call specific CLIs directly instead of going through bash.

You can define tools in:

• a global file: ~/.pi/agent/tools.json
• a local project file: ./.pi/tools.json

This lets you keep shared tools for all projects and add project-specific tools locally.

Benefits

• better prompt steering through tool-specific descriptions and guidance
• no shell quoting problems because arguments are passed as structured arrays
• more consistent tool selection for tasks that clearly belong to registerd tools

Installation

Install the package with pi:

pi install npm:@jademind/pi-tools

How to use

Create one or both of these files:

• global: ~/.pi/agent/tools.json
• local: ./.pi/tools.json in the project where you run pi

Both files are loaded. Global tools are available everywhere, and local tools extend them for the current project. If a tool name exists in both files, the local definition wins.

Minimal examples

Global ~/.pi/agent/tools.json:

{
  "tools": [
    { "name": "tree", "command": "tree" },
    { "name": "jq", "command": "jq" }
  ]
}

Local ./.pi/tools.json:

{
  "tools": [
    { "name": "yq", "command": "yq" }
  ]
}

Full example

Global ~/.pi/agent/tools.json:

{
  "tools": [
    {
      "name": "tree",
      "command": "tree",
      "label": "tree",
      "description": "Show a directory tree.",
      "promptSnippet": "Inspect directory structure with tree using explicit argv arguments.",
      "promptGuidelines": [
        "Pass arguments as an array of strings in argv order.",
        "Use this tool instead of bash when you specifically need tree output."
      ]
    },
    {
      "name": "jq",
      "command": "jq",
      "label": "jq",
      "description": "Query and transform JSON with jq.",
      "promptSnippet": "Use jq for JSON filtering and transformation with explicit argv arguments.",
      "promptGuidelines": [
        "Pass the jq filter and flags as separate argv items.",
        "Use this tool instead of bash for JSON processing."
      ]
    }
  ]
}

Local ./.pi/tools.json:

{
  "tools": [
    {
      "name": "yq",
      "command": "yq",
      "label": "yq",
      "description": "Query and transform YAML with yq.",
      "promptSnippet": "Use yq for YAML filtering and transformation with explicit argv arguments.",
      "promptGuidelines": [
        "Pass the yq expression and flags as separate argv items.",
        "Use this tool instead of bash for YAML processing."
      ]
    }
  ]
}

JSON format

Top level:

• tools — array of tool definitions

Load order:

1. ~/.pi/agent/tools.json
2. local ./.pi/tools.json

If the same tool name appears in both, the local entry overrides the global one.

Each tool supports:

• name — tool name exposed to pi, must match ^[a-z0-9_]+$
• command — executable name or full path
• label — optional display label
• description — optional description shown to the model
• promptSnippet — optional short prompt text for the model
• promptGuidelines — optional array of extra guidance strings

Tool input

Every configured tool accepts the same input:

• args?: string[] — CLI arguments in argv order
• timeoutMs?: number — optional timeout in milliseconds, default 30000, max 300000

Examples:

tree

{
  "args": ["-L", "2"],
  "timeoutMs": 10000
}

jq

{
  "args": [".items[] | .name", "data.json"]
}

yq

{
  "args": [".spec.template.spec.containers[] | .image", "deployment.yaml"]
}

Commands

/pi-tools

Shows the global path, local path, which config files were loaded, the configured tools, and per-session call counts.

/pi-tools-reload

Re-reads both ~/.pi/agent/tools.json and local ./.pi/tools.json, then registers newly added tools.

If you removed or renamed tools, use pi's /reload command for a clean runtime reset.