pi-tool-usage-tracker

A pi extension that remembers which tools/commands your working directory actually uses, tracks which are missing, and auto-promotes them once they get installed — so the more you use pi in a path, the more complete (and the less frequently interrupted) your tooling becomes.

It is the companion to pi-tool-missing-guard:

	tool-missing-guard	tool-usage-tracker
Role	Interrupts when a command is missing	Remembers usage & missing, hints proactively
Writes to disk	No (read-only, no-op)	Yes (persisted tool state)
Focus	React to a failure	Learn over time, reduce future failures

⚠️ Security note for reviewers: unlike tool-missing-guard, this extension does persist state to disk (a small JSON file per project). It only reads tool names from command input/output — it never executes arbitrary commands of its own.

What it does

For each working directory, this extension maintains a lightweight record of:

• Used tools — every bash command that actually ran (keyed by command name, version suffix preserved, e.g. python3.11 vs python3.12).
• Missing tools — commands reported missing by bash (via command not found etc.), tracked with a missing flag.

Behavioral loop:

1. A command runs successfully → it's recorded as available.
2. A command is reported missing → it's recorded as missing; only after being confirmed ≥2 times within a session is it treated as "known missing".
3. A known-missing tool later runs successfully → it's auto-promoted back to available, and removed from the proactive hint.
4. At each agent start (before_agent_start), the known-missing tools are injected into the system prompt so the model avoids calling them — reducing future interruptions.

Install

pi install npm:pi-tool-usage-tracker

Then reload pi (/reload) or restart.

Verify it's active:

/tool-usage

How to use

Nothing to configure. Let it run — it records usage as the agent works.

• /tool-usage — show the tracked tool list: total, known-missing (archival), confirmed-missing (injected into the prompt), and global-layer tools.
• State is stored per working directory and persists across sessions.

State files

File	Layer	Contents
<cwd>/.pi/tool-missing.json	project	Auto-learned usage & missing (gitignored by default)
~/.pi/agent/tool-missing.json	global	User-confirmed tools (layering in with the project)

Reads merge both (project wins over global). Writes default to the project layer.

Privacy: the project file records your personal tool usage, so it is gitignored by default. The repo ships a .gitignore covering **/.pi/tool-missing.json.

Development

npm run typecheck   # TypeScript check
npm test            # Node native test runner (Node 22+)

The extension reuses parsing logic (extractMissingCmd, looksLikeMissing, textOf, detectLang) from pi-tool-missing-guard, which it imports as a dependency, so missing-detection stays consistent with the guard.

License

MIT