---
title: "AI agents"
description: "Connect Claude Code, Claude Desktop, Codex, Cursor or any MCP client to Lilo, let agents browse in a Space of their own, and approve what they do."
sidebar:
  order: 11
---

Lilo has no AI of its own. If you turn agent control on, the agents you already use on your Mac can open tabs in Lilo, read pages and act on them, in a Space kept apart from yours. This page takes you from a fresh install to an agent that browses for you, and explains what each approval allows. An agent you talk to in a Lilo conversation works differently: it is a program running on your Mac with your account's access to files and commands, and it browses in your own Space and profile. See [Talk to your agents in Lilo](#talk-to-your-agents-in-lilo).

Agents reach Lilo through `lilo-mcp`, a small MCP server inside the app bundle. When Lilo is in your Applications folder, its path is:

```text
/Applications/Lilo.app/Contents/MacOS/lilo-mcp
```

## Turn on agent control

Agent control is one setting for all of Lilo, not per profile. The setup turns it on if you answered **With my agents** or **For developing** to **How will you use Lilo?**, and leaves it off if you answered **For browsing** or skipped the question. While it is off, Lilo accepts no agent.

1. **Open Settings**

    Choose **Lilo > Settings…** or press <kbd>⌘,</kbd>.

2. **Open the Agents section**

    In the sidebar, under **Tools**, choose **Agents**.

3. **Turn on Let agents use Lilo**

    Under **Agents using Lilo**, turn on **Let agents use Lilo**. Two more settings appear below it: **Ask before sending, paying, deleting or publishing** (on by default) and **Always allowed**, the sites where agents act without asking.

:::note
Some messages from `lilo-mcp` call this section "Settings > AI agents". In the Settings window it is named **Agents**.
:::

## Connect your agent

Once agent control is on, **Apps that can use Lilo** shows a tile for each supported app that Lilo finds on your Mac: Claude Code, Claude Desktop, Codex and Cursor. Click **Connect** on a tile and Lilo writes that app's MCP configuration for you, keeping every other server already in it. The tile then reads **Configured. Lilo asks you the first time it connects.**

To set an app up by hand, use the configuration for your client below.

**Claude Code**

Run this in Terminal:

```sh
claude mcp add --scope user lilo -- /Applications/Lilo.app/Contents/MacOS/lilo-mcp
```

**Connect** runs the same command, after removing any earlier `lilo` server from your user scope.

**Claude Desktop**

Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "lilo": {
      "command": "/Applications/Lilo.app/Contents/MacOS/lilo-mcp"
    }
  }
}
```

Quit and reopen Claude to load it.

**Codex**

Add this table to `~/.codex/config.toml`:

```toml
[mcp_servers.lilo]
command = "/Applications/Lilo.app/Contents/MacOS/lilo-mcp"
```

**Cursor**

Add the server to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "lilo": {
      "command": "/Applications/Lilo.app/Contents/MacOS/lilo-mcp"
    }
  }
}
```

**Other MCP clients**

Any client that starts a local MCP server over standard input and output works. In **Agents**, find **Other agents** and click **Copy Configuration**: Lilo copies an `mcpServers` entry like the one for Claude Desktop, with the path of the Lilo you are running.

If Lilo cannot read an existing configuration file (a comment or a trailing comma in a JSON file, for example), it leaves the file alone and tells you what to add yourself.

## Allow the agent the first time

The first time an agent connects, Lilo shows a dialog titled with the agent's name, such as **Claude Code wants to control Lilo**, with the path of the program behind the connection. It lists what you allow:

- Open tabs in its own folder of the Agents Space
- Read the pages it opens
- Act in them with your sign-ins

While **Ask before sending, paying, deleting or publishing** is on, the dialog adds: "It asks before sending, paying, deleting or publishing."

Choose **Allow** (<kbd>⌘↩</kbd>) or **Don't Allow** (<kbd>Esc</kbd>). The question waits up to ten minutes, so the agent does not time out while you come back to your Mac.

Lilo remembers **Allow** for that program, not for the name the agent gives: a signed app is known by its signature, so its updates keep the approval; an unsigned one by its path. After **Don't Allow**, the agent's tool calls fail until you reconnect it and allow it.

To take an approval back, find the app's tile in **Apps that can use Lilo** and click **Remove**. The agent's connection closes and it has to ask again.

## Try it

Ask your agent something like "Open example.com in Lilo and tell me what the page says." A short session looks like this, from the agent's side:

1. `tabs_context_mcp` lists the tabs of its folder. Called with `createIfEmpty`, it starts a new folder with one empty tab.
2. `tabs_create_mcp` answers `Created new tab. Tab ID: 2`.
3. `navigate` to `https://example.com` answers `Navigated to https://example.com/ - Example Domain`.
4. `get_page_text` returns the page's title, address and text.

Every tool, with its parameters, is listed in [MCP tools](/reference/mcp-tools).

## Where agents work

An agent you connect from another app opens its tabs in an **Agents Space**, one folder per task, never among your own tabs. Each agent sees only the tabs of its own folders.

By default those tabs run in **Agents**, a throwaway profile with no cookie, sign-in or history of yours. Lilo wipes it when agent control starts and when the last agent working in it leaves. When a session ends, its folders and tabs close. If a window shows the Agents Space at that moment, they stay in view until Lilo cleans the Space up later. An agent can also open `isolated` tabs, which live in a Private Space of its own and share no cookies with its other tabs.

An agent can ask to borrow one of your profiles, to act with its sign-ins. Lilo asks you first, for example **Claude Code wants to use the profile Work** ("It moves its tabs there, to act with that profile's sign-ins."). You allow each profile once per agent. Its folders then move to that profile's own Agents Space. Going back to the Agents profile needs no question.

## What Lilo asks before an agent acts

While **Ask before sending, paying, deleting or publishing** is on, Lilo stops an agent before it:

- clicks, or presses Enter on, a button, link or form whose label or form address contains one of a fixed list of English and French words, such as "send", "pay", "buy", "order", "delete", "transfer", "publish" or "sign up", inside frames too;
- sends a request other than GET or HEAD with the cookies of one of your profiles.

The first check is a best-effort match on the control's wording, not on what it does, and it looks only at buttons, links, form inputs and elements with the role of a button, link or menu item. A click on any other element, such as a custom control built from a `div`, goes through whatever its label, and so do a label that is not on the list ("Submit", "Confirm", "Remove"), a label in another language, an icon with no name, and Enter in a message box. [Agent safety](/about/agent-safety#how-lilo-recognizes-a-consequential-action) lists the words and the gaps.

The question appears under the address bar, for example: **Claude Code** wants to click "Delete account" in Example Domain (example.com). The agent waits for your answer. You can choose:

- **Allow Once**: this action only.
- **Always Allow on This Site**: this action, and from now on every such action on that site and its subdomains. The site is added to **Always allowed**, where you can remove it.
- **Don't Allow**: the action does not happen.

If you do not answer within 45 seconds, the action does not happen either. The agent gets an error it can act on, such as `The user did not allow clicking "Delete account" on example.com: ask them to do it or to allow it`.

Whatever the setting, Lilo asks every time before an agent hands a page one of your files (`file_upload`, `upload_image` with a file path, or a `network_mock` rule that serves a file), and that prompt has no "always" answer.

## What an agent cannot do

An agent connected from another app cannot:

- See or act on your own tabs. It works only in its folders of an Agents Space.
- See or act on one of your Private Spaces.
- Use the sign-ins of one of your profiles before you allow that profile.
- Hand a page one of your files without asking you, every time.

An agent in a Lilo conversation is different: it browses in a folder of your own Space rather than an Agents Space, with your sign-ins without being asked, and it runs on your Mac with its own file and command tools (see [Talk to your agents in Lilo](#talk-to-your-agents-in-lilo)). Its browser tools still reach only the tabs of that folder.

What no agent is stopped from doing:

- **Reading your files.** `navigate` opens a `file://` address in the agent's own tab, and the agent can read the file, or a folder's listing, without any prompt. The upload prompt covers only handing a file to a page.
- **Running its own code.** The questions above cover clicks, Enter and requests. They do not cover code the agent runs in its tabs through `javascript_tool` or `devtools_command`: an agent working in one of your profiles can act there with your sign-ins. A `run` program runs in a blank page of its own, with no sign-ins, and the tools it calls ask as they would alone.
- **Writing cookies.** The `cookies` tool can set a cookie for any domain in the agent's profile without asking.

The prompt is a safety net for well-behaved agents, not a sandbox. [Agent safety](/about/agent-safety) explains the reasoning.

## If the agent cannot connect

The agent's tool calls fail with a message that starts with `[needs_user]` when only you can fix the problem. They name the agent as it names itself, such as `claude-code`. The most common ones:

| The agent reports | What to do |
| --- | --- |
| `Lilo is not accepting agents: in Lilo, turn on Settings > AI agents > Let agents use Lilo, then reconnect the lilo MCP server.` | Turn on **Let agents use Lilo**, then restart or reconnect the MCP server in your agent. |
| `Lilo is waiting for the user to allow claude-code: …` | Answer the connection dialog in Lilo, then ask the agent to try again. |
| `Lilo has no window to ask the user to allow claude-code in: …` | Open a Lilo window, then ask the agent to try again. |
| `The user did not allow claude-code to control Lilo: …` | You chose **Don't Allow**. Reconnect the MCP server in your agent and choose **Allow**. |
| `Lilo is not responding: quit and reopen Lilo, then reconnect the lilo MCP server.` | Quit and reopen Lilo, then reconnect. |

If Lilo is not running when an agent starts `lilo-mcp`, it opens Lilo in the background. More fixes are in [Troubleshooting](/guides/troubleshooting#an-agent-cannot-connect).

## Talk to your agents in Lilo

Lilo can also host conversations with agents that speak the Agent Client Protocol, such as Claude Agent, Codex, Gemini CLI and Copilot. Lilo still ships no model and holds no API key: it starts the agent's own program, which signs in to your own account.

1. **Turn conversations on**

    In **Settings > Agents**, under **Conversations**, turn on **Conversations with your agents**. It is off by default.

2. **Ask an agent**

    Choose **File > Ask an Agent** or press <kbd>⇧⌘A</kbd> from any page. The page you are reading comes along; type `@` to add tabs, folders, a screenshot or files.

A conversation is a folder of the Space you start it in, with the agent's tab first and the pages it opens under it. It never starts in a Private Space.

A conversation agent is not kept apart the way a connected agent is:

- **It runs on your Mac.** Lilo starts it in the working folder you pick for the conversation: **No Folder**, the first choice, gives it a folder of its own in Lilo's support folder, and **Choose folder...** takes any folder; in a repository where another conversation's agent is working, it gets a git worktree of its own. The folder is where it starts, not a limit on what it can reach. It reads and edits files and runs commands with its own tools, with your user account's access. Only the agent's own permission questions limit that; they appear in the conversation as **Allow this action?**, and when the agent offers them, **Always Allow** (<kbd>⌥↩</kbd>) or **Never Allow** in the **Allow** button's menu stops the questions for that kind of action. By default Lilo sends agents that accept a replacement prompt Lilo's own (**System prompt**, under **Conversations**). Its default text tells the agent it has full access to your machine and to act instead of asking for confirmation when a request is clear, except before an action that cannot be undone and reaches beyond your Mac, unless you already asked for it. You can edit that text, or choose **Agent's own** to keep the agent's prompt, which asks before more of its actions.
- **It browses with your sign-ins.** You started it, so Lilo asks no connection question: its pages load with the profile of the Space the conversation is in, with your cookies and sign-ins, and stay in that profile; move the conversation to a Space of another profile and its next tabs open there.
- **In the browser, it reaches only its folder.** Its browser tools reach only the tabs in its conversation's folder and the `isolated` tabs it opens. What you attach to a message reaches it too: a tab as its page text (up to 50,000 characters), a folder as the text of its tabs, a selection as its text, a screenshot as an image, a text file of 100,000 bytes or less whole, and any other file as a link. The questions before acting described above apply to its browser tools, with the same limits.

Its browser tools work only while **Let agents use Lilo** is on. For a task that should not see your sign-ins, connect the agent from another app instead. You can also ask it to use `isolated` tabs, but that is a request to the agent, not a setting: nothing makes it do so. [Agent safety](/about/agent-safety#agents-in-a-lilo-conversation) has the details.

Agents installed with `npx` or `uvx` need Node.js or uv on your Mac. An agent idle for ten minutes stops, and picks its session up again when you come back.