@ssk_dev/pi-subagents-lean

Token benchmark: Lean 275, upstream @tintinweb/pi-subagents@0.19.0 8,540 — 96.8% fewer.

See my full setup for Pi

简体中文

A lightweight Pi wrapper for @tintinweb/pi-subagents. It preserves the full upstream subagent engine while condensing all agent operations into a single, compact tool schema.

Core Features

• Full upstream runtime: Keeps agent discovery, spawning, background execution, result retrieval, steering, and lifecycle handling untouched.
• Unified tool interface: Combines Agent, get_subagent_result, and steer_subagent under one subagent tool.
• Advanced options on demand: Detailed parameters and schemas remain accessible via help and JSON inputs without cluttering the default prompt.
• Available agent names: subagent_type shows the enabled types captured at extension startup. Reload the extension after changing agent definitions/settings; if the upstream description format is unrecognized, use help with input: "run".

This package does not strip down or rewrite the underlying engine; it only slims down the prompt footprint exposed to the model.

Installation

pi install npm:@ssk_dev/pi-subagents-lean

Do not load this alongside another pi-subagents wrapper to avoid registering duplicate tools.

Usage

The model interacts with a single tool:

subagent

Supported operations include run, result, steer, workflow, and help.

{
  "op": "run",
  "prompt": "Find the implementation of the cache key.",
  "description": "Locate cache key",
  "subagent_type": "Explore",
  "run_in_background": true
}

• Use result with agent_id to retrieve output from a finished task.
• Use steer with agent_id and message to redirect a running agent.
• Use help to inspect advanced upstream parameters when needed.

Important: Review Your Agent Definitions

The upstream runtime automatically discovers built-in and custom agents across global, workspace, and project directories. This repository does not package your private agents, sessions, or memory, but it intentionally preserves that discovery mechanism.

After installation:

1. Review all discovered agent definitions and make sure each model field points to a model available in your environment.
2. Remove any agent types you do not need.
3. Adjust prompts, tools, and extension allowlists to match your workflow.
4. Check for naming collisions: a custom agent with the same name can override a built-in type depending on discovery precedence.

The upstream package includes built-in general-purpose, Explore, and Plan types. Your environment may load additional custom definitions.

Context Footprint Benchmark

With only this extension enabled, its recurring model-facing initialization contribution is:

This saves 8,265 tokens (96.8%). Measured with Pi 1.0.0 in separate temporary processes with empty working directories and configuration. Built-in tools, skills, context files, session history, user messages, unrelated extensions, runtime UI, and slash commands are excluded; before_agent_start additions are included. Tokens are a fixed character-proxy estimate using ceil(characters / 4), not provider tokenizer billing.

Versions

Upstream runtime is pinned to @tintinweb/pi-subagents@0.19.0.

Development

npm ci
npm run check

License

MIT. This project wraps the MIT-licensed @tintinweb/pi-subagents.