@ssk_dev/pi-subagents-lean

Lean Pi subagents extension with full features: 268 initial tokens (96.5% fewer than current upstream). 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.

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 initialization overhead in the model context is:

Model-facing tool	Lean	Upstream @tintinweb/pi-subagents@0.19.0
Facade / Agent	subagent: 268	Agent: 1,487
Workflow	Included in facade	SubagentWorkflow: 5,722
Result retrieval	Included in facade	get_subagent_result: 183
Steering	Included in facade	steer_subagent: 183
Total	268	7,575

This saves 7,307 tokens (96.5%) compared to the current upstream package. The benchmark was measured on Pi 0.84.4 with pi-context-view@0.4.3 in a fresh isolated session, excluding built-in tools, skills, context files, and unrelated extensions. Context View estimates tokens as ceil(characters / 4). Pure runtime UI elements and slash commands are excluded as they are not sent to the model.

Measured initialization footprint

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

Model-facing tool	Lean	Upstream @tintinweb/pi-subagents@0.19.0
Facade / Agent	subagent: 268	Agent: 1,487
Workflow	Included in facade	SubagentWorkflow: 5,722
Result retrieval	Included in facade	get_subagent_result: 183
Steering	Included in facade	steer_subagent: 183
Total	268	7,575

That is 7,307 fewer tokens (96.5%) than the current upstream extension. The measurement used Pi 0.84.4 and pi-context-view@0.4.3 in a fresh isolated session, excluding Pi built-in tools, skills, context files, messages, and unrelated extensions. Context View estimates text as ceil(characters / 4), so these are reproducible context-footprint estimates rather than exact GPT tokenizer counts. Runtime-only UI and slash commands are not included because they are not sent to the model.

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.