pi-curated-tools

Intent-driven read and bash output curation with durable token savings and cost tracking for Pi

Packages

Package details

extension

Install pi-curated-tools from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-curated-tools
Package
pi-curated-tools
Version
1.0.0
Published
Aug 20, 2026
Downloads
166/mo · 24/wk
Author
claudiolaas
License
MIT
Types
extension
Size
32.1 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Pi Curated Tools Extension

A high-signal, context-saving extension for pi.

Overview

Large file reads (read) and verbose terminal outputs (bash) are the biggest contributors to context bloat and degradation over long agent sessions.

This extension wraps the built-in tools (read, bash) with an Intent-Driven Sub-Agent Curator:

  1. Mandatory intent parameter: Requires the LLM agent to specify what exact information or outcome it is looking for.
  2. Sub-Agent Curation Step: A fast sub-model extracts only relevant code snippets (preserving line numbers), error traces, and matching answers before passing them into the main agent's context.
  3. Dual Token Tracking:
    • Context Saved: Tracks how many cumulative tokens were prevented from entering the main agent's long-term context window.
    • Sub-Agent Cost: Tracks the exact one-off tokens (input and output) spent by the sub-agent model call.

Outputs shorter than 250 characters bypass the curator and are returned directly.

Installation

The extension is installed globally at: ~/.pi/agent/extensions/curated-tools/

It auto-loads on startup or can be reloaded in an active session with /reload.

Commands

  • /curator-model
    Interactively select from a compact shortlist of the active and fast models. Use /curator-model <provider/model-or-pattern> to choose any other registered model (e.g. claude-3-5-haiku, gemini-2.0-flash, or gpt-4o-mini). The default is OpenRouter's openai/gpt-5.6-luna, requested with reasoning disabled and a dedicated final-output budget.

  • /curation-stats
    Show a detailed lifetime and current-session breakdown of:

    • Total tool calls
    • Context tokens saved vs. curated tokens injected
    • Sub-agent token consumption (one-off input + output)
    • Cached tokens, measured curator cost, and the immediate token-price break-even ratio
    • Per-tool stats (read, bash)

Usage is durably recorded across Pi sessions in ~/.pi/agent/curated-tools/token-usage.jsonl. Set PI_CURATION_STATS_PATH to store the append-only ledger elsewhere.

Live Status Widget

While running, the extension continuously updates a bottom widget:

🌿 Context Saved: ~48.2k tokens (74% reduction) | Sub-agent spent: ~14.1k tokens across 14 calls