Summary

pi-boomerang addresses the challenge of excessive token consumption in long, autonomous LLM agent tasks. It provides token-efficient autonomous task execution by automatically summarizing raw turn history into a concise "handoff summary." This benefits users of the 'pi' coding agent by enabling thorough work completion while drastically reducing context window usage and simplifying chat interfaces.

How It Works

The core mechanism involves replacing extensive raw turn histories with a compact, expanded handoff summary upon task completion. This summary encapsulates crucial operational details like changed files, commands executed, validation outcomes, and task results. This approach ensures the LLM sees only essential information for subsequent turns, preserving the full history in a navigable "session tree" for optional deep dives.

Quick Start & Requirements

• Installation: pi install pi-boomerang, followed by restarting the 'pi' agent.
• Prerequisites: Requires a functional 'pi' coding agent environment.
• Usage: Initiate tasks with /boomerang <task> or prompt templates like /boomerang /<template>. Supports chaining (/a -> /b) and an auto-mode (Ctrl+Alt+B or /boomerang auto on) for seamless summarization of the next normal prompt.
• Documentation: Core usage patterns are demonstrated via command-line examples within the README.

Highlighted Details

• Token Reduction: Achieves significant token savings by replacing large histories with concise summaries.
• Chained Execution: Enables sequential execution of multiple prompt templates, consolidating their outputs into a single summary.
• Rethrow Capability: Supports iterative task refinement by re-running the entire task multiple times, accumulating context summaries across passes (--rethrow N).
• Prompt Templates: Integrates with user-defined prompt templates located in <cwd>/.pi/prompts/ or ~/.pi/agent/prompts/, allowing configuration of model, skill, and thinking parameters via frontmatter.
• Agent Tool Integration: Can be enabled as an agent-callable tool (/boomerang tool on) for autonomous task management, with optional guidance.

Maintenance & Community

The provided README does not detail specific contributors, sponsorships, partnerships, or community channels (e.g., Discord, Slack).

Licensing & Compatibility

The license type is not explicitly stated in the README. Compatibility for commercial use or closed-source linking cannot be determined without a specified license.

Limitations & Caveats

The summary generation is heuristic and may miss nuanced semantic details. Agents might still ask clarifying questions, though boomerang completes the task regardless. Anchor states are in-memory and reset upon session start or switch. Tool-initiated summaries might exhibit UI lag, requiring a manual /reload. File state is preserved but not managed by boomerang; separate extensions are needed for file rollback.