pi-list-tools

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pi-list-tools

A [Pi](https://pi.dev) coding-agent extension that prints a **canonical, verbatim list of every tool** configured in the current session — built-in, extension, and SDK — including the exact text the model sees (descriptions, per-parameter descriptions, prompt guidelines, and source metadata).

Pi has no native flag for this: `pi --help` prints only a short static list of built-in tool *names* and omits extension/package tools. This extension surfaces Pi's live tool registry (`pi.getAllTools()`).

## Install

Copy `list-tools.ts` into an auto-discovered extensions directory:

```bash
cp list-tools.ts ~/.pi/agent/extensions/        # global (all projects)
# or
cp list-tools.ts .pi/extensions/                # project-local
```

Or register it explicitly in `~/.pi/agent/settings.json`:

```json
{ "extensions": ["/absolute/path/to/list-tools.ts"] }
```

## Usage

```bash
pi --list-tools                 # table overview (default), then exit
pi --list-tools verbose         # exhaustive markdown (everything the model sees)
pi --list-tools json            # exhaustive JSON (full parameter schemas + sourceInfo)
pi --list-tools=verbose         # equals form also works
pi --list-tools --tools-filter web,bash   # filter by name substrings (any mode)
pi --show-tool bash             # exhaustive output for a single tool
```

Inside a running session:

```
/tools [table|verbose|json] [substring]
/show-tool <name>
```

### Output modes

| Mode | What it is |
|------|-----------|
| `table` (default) | Terminal-aligned overview table: **Tool**, **Extension**, **Params**, and **Description**. Cells wrap to the terminal width; `*` marks required params. |
| `verbose` | Exhaustive Markdown grouped by extension: full description, every parameter with type/required/description, enum values, and all prompt guidelines. |
| `json` | Exhaustive JSON: full parameter schemas, prompt guidelines, and `sourceInfo`. |

The **Extension** column identifies each tool's origin: `(built-in)`, `pi-web-access (git)`, `pi-codex-goal (npm)`, etc.
The default table is sorted by extension first, then tool name.

### `--no-extensions`

With `pi --no-extensions`, Pi loads only built-in tools, so the output shows only those. Note that `--no-extensions` also disables auto/settings-discovered extensions, so load this one explicitly in that case:

```bash
pi --no-extensions -e /path/to/list-tools.ts --list-tools   # builtin-only
```

## Pipeable

Output is written to real stdout (fd 1) and flushed in full, so it composes with standard tools:

```bash
pi --list-tools | grep web_search
pi --list-tools json | jq '.[].name'
pi --list-tools verbose | less
```

## Development

```bash
npm install      # installs pinned pi + typescript + @types/node
npm run typecheck
npm test         # runs the bash test suite in test/run.sh
```

### Tests

`test/run.sh` is a dependency-free bash suite. It runs pi with `--no-extensions -e list-tools.ts` so results are **deterministic on any machine** (only the 7 built-in tools plus this extension are loaded), and needs **no API key or network** (the extension exits during `session_start`, before any model call).

Coverage includes:

- all three modes (table / verbose / json) and both flag forms (`x verbose`, `x=verbose`)
- output lands on **stdout**, not stderr (original bug)
- **>64KB piped output is not truncated** (partial-`writeSync` bug), with a `test/fixtures/big-emitter.ts` fixture that emits a 200KB payload
- valid JSON with `description` / `parameters` / `sourceInfo` and per-parameter descriptions
- `--show-tool` including the not-found + suggestion path
- `--tools-filter`
- regression: the extension stays silent when `--list-tools` is absent

## CI

GitHub Actions (`.github/workflows/ci.yml`) type-checks the extension and runs the suite on Node 20 and 22 for every push and pull request. No secrets required.

## License

MIT

pi-list-tools

A Pi coding-agent extension that prints a canonical, verbatim list of every tool configured in the current session — built-in, extension, and SDK — including the exact text the model sees (descriptions, per-parameter descriptions, prompt guidelines, and source metadata).

Pi has no native flag for this: pi --help prints only a short static list of built-in tool names and omits extension/package tools. This extension surfaces Pi's live tool registry (pi.getAllTools()).

Install

Copy list-tools.ts into an auto-discovered extensions directory:

cp list-tools.ts ~/.pi/agent/extensions/        # global (all projects)
# or
cp list-tools.ts .pi/extensions/                # project-local

Or register it explicitly in ~/.pi/agent/settings.json:

{ "extensions": ["/absolute/path/to/list-tools.ts"] }

Usage

pi --list-tools                 # table overview (default), then exit
pi --list-tools verbose         # exhaustive markdown (everything the model sees)
pi --list-tools json            # exhaustive JSON (full parameter schemas + sourceInfo)
pi --list-tools=verbose         # equals form also works
pi --list-tools --tools-filter web,bash   # filter by name substrings (any mode)
pi --show-tool bash             # exhaustive output for a single tool

Inside a running session:

/tools [table|verbose|json] [substring]
/show-tool <name>

Output modes

Mode	What it is
`table` (default)	Terminal-aligned overview table: Tool, Extension, Params, and Description. Cells wrap to the terminal width; `*` marks required params.
`verbose`	Exhaustive Markdown grouped by extension: full description, every parameter with type/required/description, enum values, and all prompt guidelines.
`json`	Exhaustive JSON: full parameter schemas, prompt guidelines, and `sourceInfo`.

The Extension column identifies each tool's origin: (built-in), pi-web-access (git), pi-codex-goal (npm), etc. The default table is sorted by extension first, then tool name.

`--no-extensions`

With pi --no-extensions, Pi loads only built-in tools, so the output shows only those. Note that --no-extensions also disables auto/settings-discovered extensions, so load this one explicitly in that case:

pi --no-extensions -e /path/to/list-tools.ts --list-tools   # builtin-only

Pipeable

Output is written to real stdout (fd 1) and flushed in full, so it composes with standard tools:

pi --list-tools | grep web_search
pi --list-tools json | jq '.[].name'
pi --list-tools verbose | less

Development

npm install      # installs pinned pi + typescript + @types/node
npm run typecheck
npm test         # runs the bash test suite in test/run.sh

Tests

test/run.sh is a dependency-free bash suite. It runs pi with --no-extensions -e list-tools.ts so results are deterministic on any machine (only the 7 built-in tools plus this extension are loaded), and needs no API key or network (the extension exits during session_start, before any model call).

Coverage includes:

all three modes (table / verbose / json) and both flag forms (x verbose, x=verbose)
output lands on stdout, not stderr (original bug)
>64KB piped output is not truncated (partial-writeSync bug), with a test/fixtures/big-emitter.ts fixture that emits a 200KB payload
valid JSON with description / parameters / sourceInfo and per-parameter descriptions
--show-tool including the not-found + suggestion path
--tools-filter
regression: the extension stays silent when --list-tools is absent

CI

GitHub Actions (.github/workflows/ci.yml) type-checks the extension and runs the suite on Node 20 and 22 for every push and pull request. No secrets required.

License

MIT