Skip to content

Agent Mode

Agent Mode gives a capable model a longer leash. With it on, the tool loop may run more rounds, and four more tools become available: bash (a shell in the project folder), web_search, web_fetch and download_file. In code mode, scripts may do everything a Python program can instead of only calling Whittl's small script API.

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

Changed in v2.6.0. Agent Mode used to decide much more: whether the planner ran, whether there was session memory, which loop a model got. Those are now decided for every model by its capability record, with Agent Mode on or off. What the toggle still decides is how long the loop may run and the tools above.

When to use it

Agent Mode is worth it when:

  • The scope is unclear upfront. "Add user authentication to this app" means a database, a login form, session handling and password hashing; the agent discovers the scope as it goes.
  • The task needs running and checking. With bash the agent can run your tests, read what fails, fix it and run them again, all in one prompt.
  • The model needs to look something up. The web tools let it read the documentation for a library it is unsure of, or fetch the icons you asked for, instead of guessing.

It is overkill when you know exactly what you want changed ("make the title navy"), or the change is one function in one file. A normal turn is cheaper and quicker for that.

Turning it on

Edit > Preferences > AI Generation > Agent Mode (experimental). It is off by default.

Agent Mode is not free

A long run on a premium model costs real money: a round on a large model is typically a few cents, and a hard task can take dozens of rounds. The status bar keeps a running total while a job runs; watch it the first few times. Prompt caching keeps most of a long run's input cheap on the backends that support it.

Rounds by tier

Every model's capability record gives it a tier, on every backend: Claude, OpenRouter, Gemini, DeepSeek and Ollama alike (how). The tier decides how far Agent Mode can stretch the loop:

Tier Rounds with Agent Mode on Rounds with it off
S 50 10
A 20 10
B 10 10

So on a tier-B model (small local models, mostly) Agent Mode adds the tools but not more rounds. A model with no reliable tool calling works through scripts instead (code mode); Agent Mode lets those scripts import the project's own modules and use the whole of Python.

The bash tool

bash runs a command in the project folder and returns what it printed. The agent uses it to run tests, inspect files and folders beyond what its other tools show, or try a quick snippet with python -c.

  • A deny-list refuses the dangerous before anything runs: elevated privileges (sudo), installing or removing packages (pip install, npm install, system package managers), recursive or forced deletes (rm -rf), disk tools, destructive git (push --force, reset --hard, clean -f), shutting the machine down, piping a download into a shell, and writing outside the project by absolute path. A refused command comes back to the agent with the reason, and for a package it is told to list it in requirements.txt instead.
  • Every command has a time limit: 15 seconds by default, at most 60. A command that runs over is stopped together with everything it started.
  • Output is capped at 8,000 characters per stream, so one chatty command cannot fill the model's memory.
  • On Windows it runs in the Windows shell, and Whittl itself handles grep, head, tail, cat and wc, which Windows does not have. Qt programs started from it run without opening a window.

A shell, not a sandbox

The deny-list stops the obvious mistakes. It is not a sandbox: the shell runs with the same access Whittl has, as you. Agent Mode is for models and tasks you would trust with a terminal in that folder.

The web tools

web_search and web_fetch let the agent look things up; download_file saves a file from the web into the project, such as icons or a font you asked for. Each call shows in the chat as it happens. Research and downloads have separate budgets per session (20 searches and pages, 40 downloads by default), set in Preferences > Web Research. The default search backend, DuckDuckGo, needs no key. Details on Web Research.

Safeguards that remain active

Agent Mode raises the ceiling; it does not remove the floor. Every guard on The Agent Loop still fires: six rounds with nothing new end the run, the same call three times ends it, four failed edits in a row end it, a reply stuck repeating itself is ended, and Stop stops immediately. The round limit above is enforced whatever the model says.

If the project has tests, they run after the agent finishes, and any failure its edits introduced is reported in the chat. Failures that were there before do not count against it. See Test Gate.

An example

Add a "Recent files" menu to a text editor app:

  1. Open the project and turn Agent Mode on.
  2. Pick a capable model, such as Claude Sonnet 5 or a tier-S model on OpenRouter.

  3. Send:

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

A typical run reads the existing File menu, finds where the submenu belongs, edits the menu code, adds a small class to keep the list, runs the app or its tests to check, fixes what fails, and reports what it changed. Follow-ups such as "now show a tooltip with the full path" land on an agent that remembers what it just did, on any model with session memory.

Troubleshooting

The agent keeps running the same command and failing

The guard ends a run that repeats the same call three times, but a command that changes slightly each time can slip past it for a while. Press Stop, then say more precisely what you want.

A long run cost more than expected

Break the task up: "add a login form", then "add a user model", then "wire them together", as separate prompts. Or use a tier-A model, whose cap is 20 rounds.

Agent Mode is on but nothing behaves differently

On a tier-B model Agent Mode adds tools but not rounds. Check the Models dialog: a model with the [Tools] chip, and ideally [Thinks] or [Long], gets more from it.

What's next