npm package: @jademind/pi-tools
Description: pi extension that registers additional CLI tools from local/global config files
Author: JadeMind
Latest version: 1.0.0

# 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:

```bash
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`:

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

Local `./.pi/tools.json`:

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

### Full example

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

```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`:

```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

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

#### jq

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

#### yq

```json
{
  "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.