Token-efficient autonomous task execution with automatic context collapse for pi coding agent.

/boomerang Fix the login bug 

The agent executes autonomously. When done, the entire exchange collapses to a brief summary—work gets done, tokens get saved.

Long autonomous tasks consume massive context. A bug fix that reads 10 files, makes 5 edits, and runs tests might burn 50k tokens. With pi-boomerang, the LLM only sees:

[BOOMERANG COMPLETE] Task: "Fix the login bug" Actions: read 10 file(s), modified src/auth.ts, src/login.ts, ran 3 command(s). Outcome: Fixed the login bug by correcting the JWT validation logic... 

Same outcome. Fraction of the tokens. The session tree preserves full history for /tree navigation if you need it.

An inverted D-Mail: where D-Mail rewrites reality while the observer remembers, boomerang rewrites the observer while reality persists. The session tree is your Reading Steiner.

pi install pi-boomerang

Then restart pi to load the extension.

# Plain task /boomerang Refactor the auth module to use JWT # Run a prompt template /boomerang /commit "fix auth bug" # Chain templates together /boomerang /scout "map the auth module" -> /planner "design JWT refresh" -> /impl # Cancel mid-task (no collapse) /boomerang-cancel

The agent works without asking questions, making reasonable assumptions. When complete, everything collapses into a summary branch.

Run multiple templates in sequence with a single collapse at the end:

/boomerang /scout "analyze the codebase" -> /planner "design the fix" -> /impl "build it"

Each step can specify its own args inline. You can also set global args as a fallback for steps without inline args:

/boomerang /scout -> /planner -> /impl -- "build the auth system"

Each template's frontmatter controls model, skill, and thinking level for that step. Scout runs on sonnet, planner on opus, impl on whatever—boomerang switches automatically and restores your original config after collapse.

Status indicator shows progress as chain 1/3, chain 2/3, etc.

Run the full task multiple times with context collapse between runs:

/boomerang /deslop --rethrow 3 /boomerang "improve code quality" --rethrow 2 /boomerang /scout -> /impl --rethrow 2 -- "auth module"

Each rethrow executes the full task, collapses to the same anchor point, and continues with fresh context plus accumulated summaries from prior rethrows.

File changes persist on disk across rethrows. Boomerang consumes --rethrow N directly. For compatibility, --loop N is treated as an alias for --rethrow N in boomerang commands, so loop flags are not injected into the rendered prompt body. If both flags are present, --rethrow takes precedence and --loop is ignored.

Status shows rethrow 2/3 and for chain rethrows rethrow 2/3 · chain 1/2. Cancel mid-rethrow with /boomerang-cancel.

If the task starts with /, boomerang treats it as a template reference:

/boomerang /commit "fix the auth bug" /boomerang /codex/review "the auth module"

Templates load from <cwd>/.pi/prompts/ first, then ~/.pi/agent/prompts/. Subdirectories map to path segments (/codex/review → codex/review.md).

Frontmatter fields:

--- model: claude-opus-4-6 skill: git-workflow thinking: xhigh --- Commit current work. $@

• model — switches before the task, restores after
• skill — injects into the system prompt
• thinking — sets thinking level, restores after
• $@ expands to all args, $1 $2 etc. for positional

By default, each boomerang collapses just its own work. Set an anchor when you want multiple tasks to share the same collapse point:

/boomerang anchor # set anchor here /boomerang "task A" # collapses to anchor with summary A /boomerang "task B" # collapses to anchor with summaries A + B /boomerang anchor clear # remove anchor

Summaries accumulate, so each task's context includes what came before.

When enabled, the extension registers a boomerang tool the agent can call directly. Two modes:

Task mode — pass a task string and it runs autonomously when the current turn ends:

boomerang({ task: "refactor the auth module" }) boomerang({ task: "/deslop --rethrow 3" }) boomerang({ task: '/scout -> /impl -- "auth module"' }) 

Supports everything the command does: templates, chains, --rethrow N. The task queues and executes after the agent's current turn completes.

Anchor mode — call with no task to toggle an anchor/collapse point. First call sets the anchor, second call collapses everything since the anchor into a summary. Useful for self-managed context without user intervention.

Disabled by default because agents got too aggressive with it. Enable with:

/boomerang tool on

You can provide guidance for when the agent should use it:

/boomerang tool on "Use only for tasks that modify 3+ files" /boomerang guidance "Use for refactoring or multi-step implementations"

Tool state and guidance persist to ~/.pi/agent/boomerang.json across restarts.

One quirk: tool-initiated anchor/collapse may not update the UI immediately (the context IS collapsed, agent sees it, but chat display lags until /reload).

pi-context gives the agent Git-like tools to manage its own context—create milestones, monitor token usage, decide when to squash.

The problem: LLMs cut corners when told about resource limits. "You're at 80% capacity" triggers scarcity mindset—rushing, skipping exploration, shallower analysis.

pi-boomerang keeps the agent unaware. It sees the task, works thoroughly, collapse happens invisibly.

Independent. pi-boomerang collapses context/tokens. Rewind restores files. Use together: boomerang saves tokens, rewind fixes broken files.

• Summary is heuristic—extracts file operations from tool calls, may miss semantic details
• Agent might still ask questions despite instructions (boomerang completes anyway)
• Anchor state is in-memory only, clears on session start/switch
• Tool-initiated collapse may not update UI immediately (/reload to refresh)