Fusion

Fusion pairs a strong lead model with a lower-cost sidekick model, so the lead plans and the sidekick does the routine work.

@pi-unipi/fusion · part of UniPi

What it does

• Gives /unipi:model, a keyboard model picker. It shows all available models, their prices and a thinking level for each model.
• Lets you select one model, or a Fusion pair of a lead and a sidekick.
• Runs one persistent sidekick for each lead session. The sidekick is a child Pi process. Its context and shells stay between handoffs.
• Tells the lead to give work to the sidekick. In each turn, the first direct edit or write of the lead gets a reminder. Each 4 non-trivial bash calls of the lead also get a reminder.
• Shows the estimated savings of the sidekick in /unipi:fusion-stats.

Quick start

1. Install UniPi: pi install npm:@pi-unipi/unipi. You can also install this package alone: pi install npm:@pi-unipi/fusion.
2. Open /unipi:settings. Select "Edit fusion presets…". Mark the lead and sidekick models.
3. Type /unipi:model. Select the Fusion row. Push Enter.
4. Give the agent a task. The lead calls the sidekick tool.

Commands

| Command | What it does | |---|---| | /unipi:model | Opens the model picker. When you type /model, the picker is the first suggestion. | | /unipi:fusion-stats | Shows sidekick tokens, costs, savings, handoffs and runtime state. |

Picker keys

| Key | What it does | |---|---| | Up, Down | Moves the selection. | | Typing | Filters the models. | | Left, Right | Changes the thinking level of the selected row. Fusion keeps the level for each model. | | Tab, Shift+Tab | On the Fusion row, moves the focus: effort, lead, sidekick. | | Space | On the Fusion row, selects lead effort or sidekick effort. | | Enter | Applies the selection. | | Alt+Enter | Saves the selected row as the startup model. | | Esc | Closes the picker. |

If you change the model with Pi's own /model or Ctrl+P, Fusion mode stops.

Agent tools

| Tool | What it does | |---|---| | sidekick | Gives a message to the sidekick. block: true (default) waits for the report. block: false returns now. The report comes later as a completion notice. | | read_subagent | Reads or waits for a sidekick handoff. |

A call to sidekick while the sidekick works sends the message as an interrupt. It does not start a second sidekick.

Settings

Namespace fusion. Open it with /unipi:settings.

| Key | Default | What it does | |---|---|---| | startup.model | empty | Model that Pi opens with. Empty uses Pi's default. Global only. | | startup.thinking | not set | Thinking level that Pi opens with. Global only. | | default.lead | empty | Lead model when you confirm the Fusion row with no change. | | default.sidekick | empty | Sidekick model for the same case. |

The preset file holds the model lists, levels, recent models and badges:

• Global: ~/.unipi/config/fusion/preset.json
• Project: <project>/.unipi/fusion-preset.json. Its lists replace the global lists. Its objects merge with the global objects.

Add a prices object to the preset file when a provider gives no prices:

{"prices": {"provider/model": {"input": 0.2, "cachedInput": 0.02, "output": 1.2}}}

How it works

The sidekick session file is ~/.unipi/workspace/<id>/sessions/<sid>/fusion/sidekick/<lead-session-id>.jsonl. The sidekick compacts its own context. The child gets UNIPI_FUSION_CHILD=1 and UNIPI_SUBAGENT_CHILD=1, so it does not load Fusion tools or commands.

Read Delegation for the lead and sidekick flow.

See also

• Subagents
• Prefix cache
• Commands reference