Agent Mode¶

Agent Mode is an opt-in setting that gives capable AI models a different runtime inside Whittl: the planner is skipped (the AI classifies its own intent), the tool loop runs unbounded up to 50 rounds, session memory persists across prompts, and a real bash tool becomes available for shell commands inside your project directory.

Think of it as the difference between asking a developer to change one line versus handing a developer the task and letting them work until it's done.

When to use Agent Mode¶

Agent Mode shines when the task has these characteristics:

The scope is unclear upfront. "Add user authentication to this app" means database, routes, login UI, session handling, password hashing — the agent discovers the scope as it goes.
Multiple related changes need to happen. Agent Mode works across files naturally; default mode generates or edits one "thing" at a time.
The task benefits from running and checking. Agent Mode can run your code, see errors, edit, re-run, verify — a tight feedback loop within one prompt.

Agent Mode is overkill when:

You know exactly what you want changed ("change the theme color to navy")
The change is one file, one function
Cost sensitivity is high and the task is simple

For targeted edits, default mode with its surgical editing is cheaper and faster.

Turning it on¶

Edit → Preferences → AI Generation → Agent Mode (experimental)

Agent Mode is not free

An agent running for 20+ rounds on Claude Sonnet can cost $1–3 per task. A round on a premium model is typically $0.05–$0.15. Agent Mode raises the round ceiling from 5 (default mode's auto-fix) to 20–50 depending on the model.

Whittl's safeguards (oscillation guard, read-only bailout, Stop button) still fire — but Agent Mode sessions CAN be expensive if you run several in a row. Watch the token/cost display in the status bar.

Model tiers¶

Not all models qualify for full Agent Mode. Whittl classifies each available model into one of three tiers based on its demonstrated agentic ability:

Whittl does not keep a list of blessed model names. It works out what the selected model can do and picks a round cap from that.

Claude, on its own backend, is always tier-S. It is the reference implementation for the agentic loop.
OpenRouter models are scored from the capability metadata OpenRouter publishes. Tool support is the baseline and scores 1. Explicit reasoning support adds 3, a 200K context window adds 2 and a 100K one adds 1, and tool_choice, parallel tool calls and structured outputs add 1 each. A model with no tool support scores zero.
Gemini, DeepSeek and Ollama, on their own backends, read as tier-B today. None of them publish the metadata the scorer needs. Reach those models through OpenRouter if you want them scored properly.

Score	Tier	Round cap with Agent Mode on	Session memory
5+	S	50	Yes, per project
2-4	A	20	No
0-1	B	10, the normal cap	No

Whittl also keeps a small deny-list for models whose tool use is unreliable in practice regardless of what their metadata claims. Gemma is on it.

The Agent Mode toggle is never greyed out. On a tier-B model it simply has nothing to unlock: the standard pipeline runs, with no session memory and no shell tool.

What changes under the hood¶

When Agent Mode is on AND the selected model is Tier-S/A:

Planner is skipped¶

Default mode runs a cheap AI classifier ("is this a code modification or a question?") before the main generation. Agent Mode skips this and lets the model decide its own next action inside the tool loop. Saves a round of API calls per prompt.

Unbounded tool loop¶

Default mode caps tool-use rounds at 5 for auto-fix and 7-10 for modifications. Agent Mode raises this to 50 (Tier-S) / 20 (Tier-A). The agent can edit, check syntax, run the app, read and search code, glob for files, search the web, and run bash repeatedly until it thinks the task is done. The full list is on The AI's Tools.

Session memory¶

Default mode treats each prompt as independent. Agent Mode remembers what the agent did on the previous prompt within the same project. Follow-ups like "now make that also work on startup" land on an agent that understands "that."

Session memory resets on:

Project switch
Explicit "clear chat" action
App restart

`bash` tool¶

Agent Mode unlocks a bash tool that runs shell commands in the project directory. The AI uses this for things like:

Running pytest to verify its changes
Running pip install to add a dependency
Inspecting the filesystem beyond what list_files shows
Running the actual app to see output

bash safety model

The bash tool has a three-tier safety model:

Whitelisted commands (ls, cat, grep, python --version, pip list, pytest, etc.) run without prompting.
Ask-before-run commands (pip install, anything that modifies the project) surface a confirmation prompt you have to click through.
Deny-listed commands (rm -rf, sudo, network operations, anything path-escaping) are blocked outright.

The whitelist/asklist/denylist is configured internally by Whittl and is not yet user-editable. It is deliberately conservative.

Web research tools¶

New in v2.5.0. Agent Mode also unlocks web_search and web_fetch, so the agent can look up an API, a library quirk or an error message instead of guessing. Each call shows in chat as it happens, a per-session budget of 20 calls keeps it bounded, and the default DuckDuckGo backend needs no key. If a task involves something the model is likely to be shaky on, say "research X first" in the prompt. Details on Web Research.

Test gate¶

If the project has tests, they run after the agent finishes and any failures its edits introduced are reported in chat before you move on. Pre-existing failures never count against it. See Test Gate.

Safeguards that remain active¶

Agent Mode raises the ceiling but doesn't remove the floor. All of these still fire:

Oscillation guard. If the agent bounces between the same two errors 3+ times across a sliding 6-entry window, the cycle aborts with a message. Tracked even across 50-round sessions.
Read-only bailout. If the agent spends too many consecutive rounds reading without editing, the cycle aborts and reports what it did land. The threshold scales with the tier: 5 rounds outside Agent Mode, 8 on tier-A, 12 on tier-S, because a real agent legitimately reads a lot before its first edit.
Failed-action bailout. Four consecutive failed edits with no successful one in between ends the cycle. A stream of failing edits used to keep the read-only guard alive forever.
Hard round cap. The tier-based cap (20 or 50) is enforced regardless of model state.
Stop button. Persists across rounds during an active agent cycle. Click once to cancel the queued round.
Error fingerprinting. Same error type + file + line repeated too often triggers early abort.

These exist specifically because Agent Mode is where runaway-cost scenarios would otherwise happen.

Running an Agent Mode task¶

Example: add a "Recent files" menu to a text editor app that doesn't have one.

Open the project in Whittl.
Toggle Agent Mode on.
Select a tier-S model (e.g. claude-sonnet-4-5).

Type the prompt:

Add a "Recent files" submenu under File. It should show the last 10 opened files, with most recent at top. Persist the list to ~/.myapp/recent.json. Clear button at the bottom.

Hit Generate.

The agent will typically:

Read the existing File menu code (read_code)
Locate where the submenu should slot in (search_code)
Edit the menu construction code (edit_code)
Add a new RecentFilesManager class (create_file)
Wire up signal connections
Run the app to verify (bash python main.py &) and check for errors
If errors surface, edit-and-retry up to the round cap
Report what it did and stop

Cost on Sonnet for a task like this: typically $0.20–$0.60. Runs in 30–90 seconds.

Running multiple prompts in one session¶

Session memory means follow-ups work naturally:

User:   Add a Recent files menu under File. [Agent does the thing.]
Agent:  Done. Added Recent files with 10-item MRU list persisted to ~/.myapp/recent.json.

User:   Now make it also track the files in each recent entry's preview.
Agent:  [Agent knows "it" = the Recent files menu, "preview" = files in the main editor.
         Modifies the existing RecentFilesManager to include a preview snippet.]

The agent sees the full session history and your previous prompts as part of its context. You don't have to re-specify context you've already established.

Troubleshooting¶

Agent won't stop, Stop button isn't responsive

The Stop button cancels queued rounds, and since v2.5.0 a stopped run is reported as stopped rather than being mistaken for a truncated reply and auto-continued. If you see a run that will not stop on v2.5.0, force-quit Whittl (it will not corrupt your project) and report a bug.

Agent keeps running the same command and failing

The oscillation guard should fire after 3+ repeats but occasionally the error shape changes slightly and the guard misses it. Click Stop, then reword the prompt with more specifics about what you want.

Agent took 47 rounds and my credit balance dropped a lot

This is rare but real on hard tasks with Tier-S models. Two mitigations:

Use Tier-A (20-round cap) for tasks you suspect are complex but don't require Opus-tier reasoning.
Break the task into smaller pieces. Instead of "add user authentication," try "add a login form → add a user model → add session handling → wire them together" as four separate prompts.

Agent Mode is on but nothing behaves differently

Your current model is tier-B, so there is nothing for the toggle to unlock. Check the Models dialog for a [Tools] chip, and prefer a model that also shows [Thinks] or [Long]. On the Gemini, DeepSeek and Ollama backends every model reads as tier-B; route through OpenRouter instead.

What's next¶

Choosing a Backend — which backend's model tiers you care about
Auto-fix Rules — the underlying safeguard system that's reused in Agent Mode
Skills System — how Agent Mode builds on Whittl's compounding knowledge layer