Agent mode
The agent can search the web, read and write files in a folder you picked, run commands and start programs. This chapter covers its tools, the workspace folder, approvals, Stop, background agents and loops.
What the agent is
In a plain chat the model can only write. In Agent mode it gets tools: it can search the web and fetch pages, read and write files in a folder you picked, run shell commands, take a screenshot, generate images and video through the Create lanes, run a saved workflow, and hand parts of a task to sub-agents. The model decides which tool to call; the app runs it, shows you what it did, and hands the result back to the model until the task is done.
Not every model can do this. A model needs to have been trained for tool calling, and the picker's "Agent" button is disabled with the tooltip "This model is not agent-compatible" for one that was not. The Models tab marks tool capable models in its legend. In Cloud mode every hosted model can drive the agent.
Start an agent chat
In a new, empty chat, click the "Agent" toggle in the strip above the message box. If you click it in a chat that already has messages, a box titled "New Chat Required" appears: "Agent Mode needs to be active from the start of a conversation to work properly. Start a new chat with Agent Mode enabled." Its button "New Agent Chat" does that for you.
A dialog titled "Where should the agent work?" opens. It has two choices. "Sandbox" is "Separate folder under ~/agent-workspace/, protected by the file tool path jail." and is the right choice for a first try. "Pick a folder…" lets you choose a real project folder: "Choose a real directory. The agent edits files in there directly, like the Coding Agent." You can add more folders with "Add another repo"; the first one is marked "Primary" and the others have a "Remove" button.
The checkbox "Remember as default. Future chats open here without asking." saves the choice. Once saved, the dialog shows "Every new agent chat opens in (path) without asking." with a "Forget it" link. "Save" confirms, "Cancel" leaves Agent mode off.
The dialog carries one sentence you should read before your first real task: "Workspace protection is a folder path jail, not a container or virtual machine. Commands run on this computer. Review tool requests before allowing them."
Type the task as you would to a person, with the outcome you want. For anything that takes more than a few tool calls the agent keeps a to-do list, shown live in the chat, and works through it. Every tool call appears as a card in the chat with its input and its result. The strip above the message box shows a badge with the workspace folder; its x has the tooltip "Leave this workspace. The agent asks again before it works anywhere."
The workspace folder and the sandbox
The file tools can only see the workspace folder and what is under it. That is the path jail: a path that resolves outside the folder is refused, including through symbolic links. The shell tool runs commands on your computer as your user, in that folder, and there is no container, no virtual machine and no network filter around it. So the protection is against the agent wandering into your documents by accident, not against a command you approved.
The sandbox is a folder under ~/agent-workspace, one per chat. Nothing there is special except that it starts empty, so a mistake cannot cost you a file you cared about.
Not every folder can be a workspace. The picker refuses a drive or filesystem root, your home folder and a mount container, and system or credential directories, with "That folder cannot be the workspace: (reason). The folder was not taken. Pick a project folder, not a drive root, a home directory or a system folder." A path that did not come through the app's own folder picker is refused as well: "Not an allowed workspace folder (only a folder you chose in LU's folder picker can be a workspace, pick it again to allow it): (path)". That last rule exists because a model can invent a path; only a folder you clicked on counts.
The tools
The agent carries these built in tools. Their names are what you see on the cards in the chat.
| Tool | What it does |
|---|---|
| todo_write | Keeps the agent's own to-do list for the task. |
| web_search, web_fetch | Searches the web and fetches a page. The search provider is set under Settings, Agent, Search Provider: Auto (SearXNG, then DuckDuckGo), Brave Search or Tavily; the last two have a key field ("Brave Search API Key", "Tavily API Key") next to them. |
| file_read, file_write, file_edit, file_list, file_search | Read, write, edit, list and search files inside the workspace. |
| shell_execute | Runs a command in the workspace folder. |
| screenshot | Captures the primary display and forwards the image to the model. A model that cannot read images gets only the size and file name. |
| image_generate, video_generate | Renders through the Create lanes, locally or hosted, whichever the app is in. |
| run_workflow | Runs a workflow saved under Settings, Agent, Agent Workflows. |
| delegate_task, check_tasks, message_agent | Starts a sub-agent for a part of the task, checks on it, sends it a message. |
| pr_resume | Given a GitHub pull request address, fetches its title, body, comments and diff through the gh command line tool, so the agent can continue a review. |
Sub-agents are bounded so a runaway task cannot spend the night: at most four run at once, they nest two levels deep, and each gets 10 tool calls and 5 steps unless you change "Sub-agent tool calls" and "Sub-agent steps" under Settings, Agent, Sub-agents ("0 = use the defaults").
Permissions and approvals
Every tool belongs to a category, and every category has a permission level under Settings, Agent, Agent Permissions: Blocked, Ask First or Auto. The defaults are Web Access and System Info on Auto, and Filesystem, Image Generation, Video Generation, Workflows, Terminal / Shell and Desktop Control on Ask First. "Reset to defaults" restores that table.
With Ask First, a dialog appears before the tool runs, showing the tool and its input, with "Approve" (Enter) and "Reject" (Esc). Read the input, especially for shell_execute: the command runs on your computer. The "Tools" button above the message box opens a per chat override with a row for each category (Web, System, Files, Shell, Screenshot, Image, Video, Workflows), so you can put one chat on Auto without changing the defaults.
A short tutorial appears the first time you use the agent; "Reset tutorial" under Agent Permissions brings it back.
Stop, background agents and loops
"Stop generation" on the send button stops the current model turn and the tool it was waiting for. Sub-agents that were already started keep running by design, so they can finish a delegated part of the work; the panel headed "Agents · N" at the side of the chat lists them, and "Stop every running agent" or "Stop this agent" ends them. In Cloud mode a sub-agent that keeps running keeps spending credits, so check that panel after a Stop.
A loop repeats the whole task until the agent declares it done or a cap is reached. The bar reads "loop", "pass N of cap" and "next in Ns" between passes; its "stop" ends the run and the pending pass. The cap is "Maximum /loop passes" under Settings, Agent, Coding Agent (0 = unlimited). A goal, shown in a bar labelled "goal", is the sentence the loop checks itself against.
MCP servers and workflows
MCP is a standard that lets you plug an outside tool server into the agent. Settings, Agent, MCP Servers adds one with a name and a command; the field is labelled "Command (only npx or uvx)", because the app starts servers only through those two launchers. The server's tools then appear next to the built in ones.
Agent Workflows, under the same settings tab, are saved sequences the agent can run with run_workflow.
When it goes wrong
The "Agent" button is greyed out. Tooltip "This model is not agent-compatible". Pick a model that the Models tab marks with the tools icon, or switch to Cloud.
"Cannot use "(path)" as the workspace: (reason). The folder was not taken. Choose one with "Pick a folder…" instead." The agent, a remembered default or a typed path pointed at a folder the rules refuse. Use the picker button and choose a project folder.
The agent calls a tool, the dialog appears, and nothing else happens. It is waiting for you. Press Enter to approve or Esc to reject. If you would rather not be asked in this chat, set the category to Auto under "Tools".
The agent loops on the same tool call. A small model, or a context window that is too small for the tool catalogue. The tool definitions alone take several thousand tokens of the context before the task begins, which is why Agent mode asks for up to 32,768 tokens; a model whose window is much smaller has little room left. Stop the run, pick a larger model or a larger context, and start a new agent chat.
Credits kept dropping after Stop (Cloud). Open the "Agents · N" panel and press "Stop every running agent". Background agents survive a Stop on purpose, see above.
A screenshot comes back as a size and a file name only. The model cannot see images. Use a vision model for tasks that need the screen.
Previous chapter: Chat. Next chapter: Code tab. Back to the handbook overview.