pi-context-ratel

Context engineering plugin for the Pi coding agent, powered by Ratel.

Cuts input token usage by ~70–90% on multi-skill, multi-tool agent setups by replacing up-front context loading with in-process BM25 progressive capability disclosure.

The Problem

Default Pi sessions inject:

• Every discovered skill into <available_skills> in the system prompt (~3,000–8,000 tokens/turn).
• All registered tool JSON schemas into the model request (~2,500–5,000 tokens/turn).

In a session with 25 tools and 40 skills, the agent pays 5,500–13,000 tokens of input overhead on every single turn.

How pi-ratel Fixes It

1. System Prompt Pruning: Intercepts before_agent_start, indexes all skills into Ratel's SkillCatalog, and strips <available_skills> from the system prompt.
2. Lean Tool Initial State: Keeps core tools (read, bash, edit, write) active; moves secondary & extension tools to Ratel's ToolCatalog.
3. Dynamic Capability Discovery: Exposes search_capabilities (BM25 Rust engine).
4. Dual-Activation:
   • Dynamic Tool Activation: Automatically calls pi.setActiveTools() with matched tools so the model can invoke them natively.
   • Direct Execution: invoke_tool allows instant calling within the same turn.
   • Skill Playbooks: get_skill_content loads markdown instructions on-demand.

Installation

Project-local (Recommended for testing)

pi -e ./extensions/index.ts

Permanent install

pi install npm:pi-context-ratel

Commands

• /ratel status: View catalog sizes, active tool count, and estimated token savings.
• /ratel search <query>: Test BM25 capability search directly in chat.
• /ratel reload: Refresh tool and skill indexes from Pi and filesystem.
• /ratel toggle: Toggle skill prompt pruning on/off for comparative benchmarks.

Configuration

Optional .pi/ratel.json in your project root:

{
  "enabled": true,
  "alwaysActiveTools": [
    "read",
    "bash",
    "edit",
    "write",
    "search_capabilities",
    "get_skill_content",
    "invoke_tool"
  ],
  "prunePromptSkills": true,
  "topKTools": 5,
  "topKSkills": 3,
  "enableDynamicActivation": true
}

Development & Testing

bun install
bun run typecheck
bun test
node /Users/sivaraman/.agents/skills/unlazy/scripts/gate-check.mjs GATES.md