The Marionette
An optional quick pass before each prompt: a cheap model finds the files and line ranges your request is about and attaches that map for the main agent.
Copy & share
On this page6 sections
The Marionette is an optional step that runs before the main agent sees your prompt. A cheap model looks at your request, finds the files and line ranges it is about, and attaches that list to your message. The main agent then starts in the right place instead of spending expensive steps searching.
It is marked experimental and is off by default.
Every prompt already includes the Genome, a map of the whole repository. The Marionette adds a map of *this request*: which files matter, how they connect, and which past decisions apply.
Your prompt is never rewritten. The map is attached underneath it.
It finds code, it doesn't suggest fixesLink to this section
The Marionette only locates. Its output has no place for a guessed cause or a suggested fix. That is deliberate: a cheap model's guess can steer a stronger model the wrong way, while a list of relevant files only helps. Deciding what to change stays with the main agent.
Using itLink to this section
In the terminal UI or the desktop composer:
/marionette fix the race in tab restore # run it for this one prompt
/marionette fix it --steps 12 --time 90s # limit how long the survey runs
/marionette on | off | status # run it on every prompt, or checkon and off apply to the current project. Add global to change it everywhere, for example /marionette on global.
On desktop, the same switch is in the Router dialog under agent behavior. In headless runs, pass --marionette, and choose a mode with --marionette-mode <mode>.
In config, the always-on switch is agentFeatures.marionette.
What the map containsLink to this section
While it runs, the map fills in under your prompt. Expand it to read:
| Section | Contents |
|---|---|
| asks | Each separate thing you asked for, quoting your words |
| loci | Relevant locations, like file.ts:120-180 · symbol · role, marked as primary or nearby |
| strands | How those locations connect: callers, files that change together, what an edit could affect |
| memories | Saved project decisions that apply |
| unmapped | Anything the survey couldn't reach, stated plainly |
Each connection names the tool that found it, so nothing in the map is a guess.
ModesLink to this section
Choose a mode with /marionette none|fast|assist|deep, or set marionetteMode in config:
| Mode | What runs | Speed and cost |
|---|---|---|
none | Index lookup only, no model | About 0.2 seconds, no tokens |
fast *(default)* | Index lookup, then one model call to pick what belongs on the map | Quick and cheap |
assist | Index lookup, then a short read-only survey to confirm | Slower |
deep | A full read-only survey driven by the model | Slowest, most variable |
The --steps and --time limits only apply to assist and deep, which run a survey loop. You can set defaults with marionetteBudget.steps and marionetteBudget.timeMs.
Which model runs itLink to this section
Set the Marionette's model in /router (taskRouter.marionette). If you leave it unset, it uses the research model configured in the router.
The Marionette only reads. It gets the same read-only tools as a research helper: language servers, the code map, impact analysis and memory search. If it fails, your prompt goes through unchanged, so it never costs you a turn.
Why not ask the agent to explore first?Link to this section
The main agent can already send a research helper to explore. The difference is timing. The Marionette always runs before the turn starts, with a clean context, and returns a short structured map instead of a long report. It also brings in saved project memories.
A research helper is still the right choice once the agent realizes mid-task that it needs to look at a whole subsystem. The Marionette covers the start of the task.