---
title: Agents
description: Named agents with their own folder, memory and instructions, teams that message each other, routines on a schedule, and chats an agent starts.
canonical_url: https://lookout.arcadia.is/docs/agents
type: guide
section: Use Lookout
last_updated: 2026-11-16
related:
  - https://lookout.arcadia.is/docs/memory
  - https://lookout.arcadia.is/docs/rules
  - https://lookout.arcadia.is/docs/connectors-and-skills
  - https://lookout.arcadia.is/docs/chats
---

> Every page of these docs: https://lookout.arcadia.is/llms.txt

# Agents

Named agents with their own folder, memory and instructions, teams that message each other, routines on a schedule, and chats an agent starts.

An agent is a named coding agent that lasts: it has a description, standing instructions, an avatar, its own folder
and its own memory, and the same tools as a chat in a project. Agents sit under **Agents** in the switch at the top of
the sidebar (`⌥⌘1`). Agents you put in the same section know each other and message each other, so a section works as a
team; an agent knows one outside its section only once you [introduce](https://lookout.arcadia.is/docs/agents#introductions) it.

You create and use agents in the Mac app. Each agent runs on one machine: the Mac that made it, while that Mac is on
and awake, or a server of yours that you turned agents on for, around the clock
([Run agents on a server](https://lookout.arcadia.is/docs/agents#hosts)). A machine that runs Lookout from the CLI (`lookout up`) has no agents
until you turn them on there.

## Create an agent

1. In the sidebar, with **Agents** showing, click the **+** (New agent) at the top, after the tabs (on **Projects**, that button is **New chat**).
2. A small step shows the character and the name picked for it, and its **Model**: the one you chose there last time,
   else the one Home starts a chat on. Type another name, pick another model or a **Fallback** it moves to when that
   model's plan is used up, or change nothing, then press Enter or **Create**. The agent opens in its chat.
3. Tell it what it is for. It saves that to its profile, and the chat shows the change. You can also write it yourself
   with [Edit profile](https://lookout.arcadia.is/docs/agents#profile). Until the first message, the chat offers three ways to start (a daily
   summary, watching something, a standing role): each fills the message box and sends nothing.

To start an agent on a project, open the project's menu in the sidebar and choose **New agent for this project**. The
agent can work in that project's folder as well as its own, and takes the project's name when it is free.

## Run agents on a server

An agent on your Mac stops while the Mac sleeps. To keep one running, turn agents on for a server you added to your
[machines](https://lookout.arcadia.is/docs/machines), such as a VPS:

- From your Mac: `lookout capacity --on vps-1 --agents on`.
- On the server, when you install it: `lookout up --agents-host`.

Lookout restarts on the server once its running chats reach a safe point, and from then on it runs agents. Only you can
turn this on or off: an agent asked to do it is refused.

To create an agent there, click **New agent** at the top of the sidebar with **Agents** showing, and pick the server under
**New agent on** (**This Mac** makes one here, as before). The agent, its folder, memory, chats and routines live on that server. Then:

- **One sidebar for every machine.** Your Mac's sidebar lists your agents on this Mac and on every server that runs
  agents. An agent on a server says the server's name under its own when nothing else is going on. Click it and its
  chat opens on that server, whichever machine the window shows.
- **One section, whichever machine.** A section is its path: **Northwind / Legal** on your Mac and on a server is one
  section in the sidebar, holding the agents of both, and those agents are one [team](https://lookout.arcadia.is/docs/agents#team). Point at a
  section to see which machines hold it.
- **An offline machine says so.** While a machine is asleep or offline, its agents stay listed, dimmed, with
  "studio-mini is offline", and open again once it is back. A machine that is offline is listed under **New agent on**
  but can't take a new agent until it answers.
- **Notifications reach you with the window closed.** When an agent on any of your machines messages you, or finishes
  something you'll want to see, your Mac notifies you even if Lookout's window is closed. Clicking the notification
  opens that chat.

- **Names are yours across machines.** No two of your agents share a name, whichever machine runs them.
- **Your time zone travels.** A routine you or the agent set up there runs at your time, not the server's, and keeps
  the zone it was made in when you travel.
- **It works where it runs.** Chats it starts run on the server unless it names another of your machines, your Macs
  included.
- **Agents message across machines.** An agent can message one of your agents on another machine by name, as it does
  one beside it. If that machine is offline, the message waits and goes once it is back, and the reply comes back to
  the chat that asked.

## Move an agent to another machine

An agent can move between your Mac and your servers that run agents, in either direction. Open its row's menu and pick **Move to vps-1** (or **Move to This Mac** for an agent on a server). Lookout shows how much moves
with it first: its folder, memory, routines and chats.

- **It finishes first.** From the moment you click **Move**, the agent takes no new work here: its routines don't fire,
  messages to it wait, and you can't write to it. A turn it is in the middle of runs to its end first.
- **Its row shows the move.** Its card under the pointer reads **Moving to vps-1** with how far it got, then names the
  new machine. Its next turn there is told that it now runs on another machine, in another folder.
- **Cancel until it lands.** **Cancel move** in its menu keeps it where it is, as it was.
- **Only one machine runs it.** It runs on the machine it moved to; the copy it left is deleted. A machine that was
  off during the move deletes its copy when it comes back, without running it.
- **Chats on a machine that was off.** If another machine holding the agent's chats was off during the move, those
  chats there still answer to the machine the agent left. The agent is told which ones, and its chat list marks each
  **not moved yet**, with the command that hands them over again: `lookout handoff CHAT... --to AGENT --on MACHINE`.
- **What stays behind.** Projects it works on aren't copied: on the new machine it starts without them, and you add
  them there.
- **Routines catch up.** A routine due while it moved follows the usual rule for a missed time
  ([When Lookout is off](https://lookout.arcadia.is/docs/agents#routine-missed)).

### Export to a file

**Export to file** in an agent's menu saves the whole agent (folder, memory, routines, chats) as one
`.lookout-agent` file, sealed with your account's key: it opens only on your own devices. **Import agent** in the
**Agents** menu brings it back onto this Mac, for example when the machine it ran on is gone. The agent then runs on
this Mac; if the machine that had it comes back, it keeps that copy archived and read-only, and never runs it.
Removing a device from your account changes the key, so a file exported before then no longer opens: export it again.
The file holds the names of the agent's secrets, never their values: those come from your account when you import it.

## Edit an agent's profile

An agent's profile sits beside its chat. In the agent's chat, open the side panel (the panel button at the top
right, or **⇧⌘R**): it has three tabs, **Profile**, **Files** and **Memory**. The first time it opens on
Profile, and after that where you left it. **Edit profile** in the agent's menu (right-click it in the sidebar) opens
the Profile tab. Chats in your projects have no Profile tab.

At the top are its avatar, its **name** (up to 32 characters) and its **description** (one line, up to 140
characters: what your other agents see), with **Pause**. Click the name or the description to change it in place.
Below, each setting is one line that says its value; click it to open it, and opening one closes the one open.

| Group | Settings |
|---|---|
| **Models** | **Model**: the model its chat runs on and its effort, the same picks as in its chat. **Fallbacks**: up to four models, in order, each a model and effort picker of its own (a model you add starts at the agent's own effort, as near as that model's levels go): when the model's plan is used up, the turn goes on with the first one that has room, for that turn only. None by default: an agent with none uses **Settings › Chat › Fallback models for agents without their own** (empty unless you set it), and with neither it waits for the reset. **Allowed models**: see [Controls](https://lookout.arcadia.is/docs/agents#controls) |
| **Behavior** | **Instructions**: standing orders the agent always sees, the `AGENTS.md` file in its home. You and the agent both edit them, and its edits show in the field as it makes them; they load within the 60,000 characters a chat's rules share (see [Size limits](https://lookout.arcadia.is/docs/rules#limits)). **Projects**: the projects it works on; its chats see their folders beside its home. **Add a project** lists the others, and **New project** at its end opens a folder as a project, as the sidebar does, and adds it at once. **Section**: the section it is filed in, by its path, or **No section**; it opens the list **Move to** shows ([Organize agents](https://lookout.arcadia.is/docs/agents#organize)). **Introductions**: the agents outside its section it was introduced to, each with its section and how and when, and **Remove** ([Introductions](https://lookout.arcadia.is/docs/agents#introductions)). **Memory**: whether it learns from its chat and reads your Everywhere memory. **Show work**: its chat shows its thinking, each step and the files each turn changed in the conversation. Off by default; it changes only how its chat looks, and the agent never hears of it. **Conversation**, last: when it started and how many times it was summarized, and **Start over** |
| **Tools** | Each opens its list, and **Profile** goes back. **Connectors**: its connectors. **Secrets**: the secrets you gave it, by name. See [Give an agent a secret](https://lookout.arcadia.is/docs/agents#secrets). **Logins**: its site logins, by site and username. See [Give an agent a site login](https://lookout.arcadia.is/docs/agents#logins) |
| **Limits and access** | **Limits**: see [Limits](https://lookout.arcadia.is/docs/agents#limits). **Only you edit it**: see [Controls](https://lookout.arcadia.is/docs/agents#controls) |

There is no Save button. A field saves when you leave it or press **Enter** (**⌘Enter** in Instructions), and
**Esc** puts back what was there. A pick and a switch save at once. The agent hears of a change at its next step, except Show work.
If the agent changed its instructions while you edited them, your edit and its change are both kept when they touch
different lines. When they touch the same lines, Instructions shows the agent's text above yours: **Use mine** saves
yours over it, **Discard mine** keeps the agent's.

An agent also changes its own name and description, and those of the agents it knows (its team and the agents
introduced to it), when it judges it right: when you ask it,
or when what they say no longer holds. Its standing instructions live in `AGENTS.md` in its folder, and it edits
that file when you change what it is for. See [Set up an agent](https://lookout.arcadia.is/docs/agents#set-up-an-agent).

Click the agent's avatar at the top of the tab to pick its character, or upload a photo. **Change avatar** in its
menu opens the tab with the picker open.

## Give an agent a secret

An agent takes its credentials from its secrets, by name, and is told not to read your Keychain, a browser's saved
passwords or a credentials file itself. One that needs an API key or a token asks you, in its chat, to add it
under **Secrets** in its **Profile** tab, by the environment variable's name, or brings it in itself without reading
it (below). Open **Secrets**, click **Add secret**, and in the dialog type the name (such as `GITHUB_TOKEN`) and the
value, then click **Save**. You can add one before the agent asks, the same way.

- **Where the value goes.** To the machine the agent runs on, and into your account sealed with your account's key.
  It is never in the chat, in what the model reads, or in a log.
- **Who has it.** That agent only. Its commands, the commands it leaves running and its routines' checks get it as an
  environment variable. Your other agents and the chats in your projects don't.
- **In output.** Where a command prints the value, the chat and the agent read `[secret:NAME]` instead, in every
  chat on that machine. This catches the value as it is and the usual encodings of it (URL, JSON, shell and HTML
  escapes, base64, also when a tool wraps it into lines, hex), not a value a command has changed (reversed, cut,
  split across lines, hashed, or shown in a screenshot). If one shows anyway, the agent is told to say so.
- **In its profile.** **Secrets** in the **Profile** tab says how many it has and opens them by name, one line
  each, with **Add secret** at the top. Each one's menu has **Replace**, which asks for the new value in a dialog, and **Remove**. One marked
  **Missing** has no value on the machine the agent runs on: **Replace** sets it.
- **When it moves.** Its secrets go with it to the new machine, through your account.
- **Saved from a page.** When the agent's browser finds a key a site shows, the agent can ask to keep it: a card asks
  **Save as NAME?**, names the site, says how many characters the value has and whether it replaces a secret of that
  name. **Save** keeps it like one you added; **Not now** keeps nothing. The value goes from the page to the agent's
  secrets without the agent reading it; Lookout holds it only until you answer, and a restart of Lookout loses it.
- **Typed into a page.** The agent types a secret into a field by its name, never its value. The first time on a site,
  a card asks **Type NAME?** with **Allow once**, **Always on this site** and **Not now**. The site is the field's own,
  never one the agent names, and **Always on this site** holds until the secret is replaced.
- **Brought in from its Shell.** `lookout secret put NAME` in the agent's commands reads a value without printing it:
  a command's output piped in, one key of a `.env` or JSON file (`--from-file`, `--key`), or a macOS Keychain item
  (`--from-keychain`: it reads only an item in your login keychain that macOS already lets the system's `security`
  tool read without asking, and refuses every other, so in normal use no dialog appears; it can't promise that for an
  item that changes in the instant between its check and its read). The same **Save as NAME?** card says the value comes from the
  agent's Shell and, when the command named a file and key or a Keychain item, shows each in quotes under "It says
  where the value comes from": that is the command's word, which Lookout can't check. A path, key, item or account
  holding a quotation mark, a control or invisible character, or more than 200 characters (1,024 for a path) is
  refused, and nothing asks you. The card says how many characters the value has and whether
  it replaces one; **Save** keeps it like one you added, **Not now** keeps nothing and stops that agent asking for that
  name for 10 minutes. The command tells the agent only saved, declined or waiting for you. A chat in your projects
  has no secrets, so there it is refused. See [CLI](https://lookout.arcadia.is/docs/cli#secret-put).

A secret is 8 characters to 8 KB, and an agent holds up to 50. Agents on one machine run as the same user: this keeps
a secret out of another agent's commands, and it does not wall the agents off from each other.

## Give an agent a site login

When an agent's browser reaches a sign-in page it has no password for, a card above the composer asks you: **Save
credential for apply.example.org with Jarvis**, with the username it typed and a password field. The card is a real
sign-in form for that site, so your password manager can fill it. **Save** keeps it for that agent and that exact
site, **Use once** types it in and forgets it, **Skip** says no. A one-time code card asks for the code each time and
never keeps it.

- **Each fill asks.** When the agent fills a saved login, a card asks **Fill login for apply.example.org as
  you@example.org?** with **Allow once** and **Deny**. Turn on **Auto fill** in the card, or on the login in its
  **Profile**, and that login fills without asking. A login that was edited since the card asked fills nothing, and an
  edit you didn't make yourself turns Auto fill off again.
- **What fills.** The browser types the login's username and password into the site's sign-in form, also when the
  site asks for the username on one page and the password on the next: one card covers both pages. A username field
  it can't fill (one that is read-only for another account, or a login saved without a username) is named to the
  agent, which asks you for that alone.
- **Only that site.** A login fills only on the exact address it was saved for: `https://`, the same host and port. A
  look-alike address, another subdomain or plain `http` gets nothing (`http://localhost` works, for testing).
- **Where the password goes.** Typed into the page by the browser, never into the chat, what the model reads, a log
  or a command. Where output shows it anyway, it reads `[secret:login]`; a password under 8 characters only where it
  stands as a word and mixes letters with digits or symbols, or digits with symbols. Letters count as one kind
  whatever their case, and a password holding a space is never hidden, so a short plain one (`Admin`, `MySQL`, `1234`,
  two words) is not hidden in output, since hiding it would hide that word in every chat. On your Mac it is stored encrypted with a key Lookout keeps in your Keychain, so it fills while the
  Lookout app is open. On a server without the app, it sits in that machine's private files, like every key it holds.
  In your account it is sealed with your account's key.
- **When nobody is there.** A subagent or a routine that needs a login gets no answer at once; the card waits in the
  agent's chat for a day, and its next run fills once you answer.
- **A 2FA key, if you choose.** A login can also keep the site's two-factor key: the setup key or `otpauth://` address
  the site shows when you turn on an authenticator app. Add it in the login's **Edit** or in **Add login**, or with
  **Add a 2FA key** on the card that saves the login. When the site asks for a code, the browser types the current
  one; the agent never sees the code or the key, and the key is never shown again, only **Replace** and **Remove**.
  The key stays on the machine where you saved it and never goes into your account: on your Mac it is sealed like
  the password, and on a server without the Mac app it is kept in that machine's private files, not sealed. When the
  agent moves to another machine, its 2FA keys are deleted, and there it asks you for the codes as before. A login
  with a key always asks: each sign-in raises **Jarvis wants to sign in to apply.example.org as you@example.org** with
  **Use login** and **Not now**, and one click covers that one sign-in on that site and tab for at most five minutes:
  the username, the password once, and codes for a minute after the first. Auto fill stays off for it, and a subagent
  or a routine that needs it gets no answer. The click stops an agent from signing in with Lookout's own tools
  without you. It is not a wall: agents run with full access to the machine, so a program that reads Lookout's own
  files is not stopped by it.
- **In its profile.** **Logins** in the **Profile** tab opens each by site and username on one line, with **Auto
  fill** (**2FA** in its place for a login with a key), **Edit** and **Remove**, and **Add login** at the top opens a
  dialog that saves one before the agent asks.
- **Passkeys.** An agent's browser keeps its own passkeys beside its logins. While you drive its **Browser** tab, a
  site's "Add a passkey" asks **Save passkey** in the pane, and its passkey sign-in asks **Use passkey**. When the agent
  signs in with one, a card asks **Use the passkey for the site as you@example.org?**, unless its **Auto fill** is on.
  A site that wants a passkey the agent doesn't hold fails at once, so its other ways in show, and **Add a passkey** on
  a login's menu opens the site's page that adds one. The passkey's key stays in Lookout's store, like a password.
- **Passkeys on your Mac, phone or security key.** While you drive, **Use iCloud, phone or security key in Chrome**
  opens the page in a Google Chrome window on the same browser profile, where Chrome's own passkey sheet offers your
  iCloud Keychain passkeys, a phone through its QR code, or a security key over USB. Agents using this browser wait
  while it is open. Close the window or press **Done**, and the page comes back in the Browser tab, signed in.

An agent holds up to 50 logins. Answering a login card from another machine's window comes later: that window says
where to answer.

## Its folder, memory and rules

Each agent has its own folder, `~/.lookout/agents/<id>/`, and everything it owns lives there: its working folder
(`home`), its memory, its transcripts, the checkpoints its turns take, and its photo. Its project memory is
private to it and stays on the machine it runs on; your [Everywhere memory](https://lookout.arcadia.is/docs/memory) is shared with every chat
and agent, on every one of your machines ([On every machine](https://lookout.arcadia.is/docs/memory#sync)). A memory the agent wrote that you
share Everywhere keeps its name as the one who saved it. It reads the [rules](https://lookout.arcadia.is/docs/rules) of its own
folder and of each project it works on, and hears of a changed rules file at its next step.

The side panel of its chat shows both. **Files** lists its folder, under **Home**, and opens a file
in the panel; it never lists your projects' folders. The agent works in its home, so a file it saves without naming a
folder lands there and shows up in Files; until then Files says the home is empty, with **Show in Finder** in the app. A file the agent linked into its folder opens from where it
points; a linked folder outside it says so instead of listing it. **Memory** lists what the agent remembers: search it, **Add** a
memory, click one to change its words in a dialog, **Forget** it with the trash beside it, or share it with every chat by choosing **Everywhere** under
**Applies**. The folder button shows the memory files as they are stored.

**Routines**, in the Profile under **Instructions**, says how many are on and when the next one fires, and opens the
prompts it runs on a schedule, each with a switch to turn it on or off ([Routines](https://lookout.arcadia.is/docs/agents#routines)); **Profile**
goes back. What the agent has at work shows under its row in the sidebar, from any of its chats: its
[subagents](https://lookout.arcadia.is/docs/subagents) and the chats its routines run in, what needs you first, then the newest; past three, a
row lists the rest in place. A chat's row there holds what that chat has at work in turn, one step further in. What
it ran is in search: press **⌘K**, then **⌘]** twice for **Work**, its chats' subagents by day, newest
first, with **Show older** for more.

**Connectors**, in the Profile's **Tools**, lists the
connectors its own folder declares in `.lookout/mcp.json`, as the machine it runs on sees them: **Add connector** writes
one there, and one waiting shows **Trust**, which names the exact command or URL and where it runs before anything
does. Only you add or trust them, from any of your devices; the agent can't trust its own. Open a connector with its
arrow to set **Caller identity**, a **Client ID** and **Scope**, **Copy public key** or **Rotate** it, choose **On** or
**Off** for each of its tools for this agent alone, and see its latest **Activity**; what its server last answered
waits there too. A remote connector that needs you shows one button at its end: **Sign in** when its server offers a
browser sign-in, or **Add API key** when it takes a key ([Sign in](https://lookout.arcadia.is/docs/connectors-and-skills#sign-in),
[keys](https://lookout.arcadia.is/docs/connectors-and-skills#keys)). A
key is stored on the machine the agent runs on and never shown again, so set it in Lookout on that machine. An agent's chat has no
Changes tab: click **Worked** on its message to see what a turn changed.

Each agent is one row in the sidebar and one conversation, which runs for as long as you keep the agent: it summarizes
older parts as it grows, and its memory keeps what it learns. A side task goes to a subagent, a routine or a chat the
agent starts, never to a second chat with the agent. Click the agent's name at the top of its chat to open the panel.

## Talk to an agent

Click the agent to open its chat, which reads like a conversation in messages: your messages on the right, the
agent's on the left. While it works, the agent's character stands where its reply will land, with what it is doing in
a few plain words, such as **Looking through files** or **Messaging Bud**, then its reply arrives in that place. To see how it got
there, choose **View steps** from a message's menu: the steps between that message and the next open in place, and
close again with their arrow or Esc. **Worked for 24s** beside the turn's last message shows every stretch of steps of the
turn, closed, with the last one open. When a turn stopped or failed, **Worked** shows where it stopped without
pointing. The files a turn changed are part of its steps too: their card ends the turn's last steps. Turn on **Show
work** in the agent's [profile](https://lookout.arcadia.is/docs/agents#profile) to keep each stretch of steps as a quiet line, such as **Worked
for 2m 3s, 9 steps**, between the messages it came between, the changed files card under the reply. A line of a long
stretch stays at the top while you read its steps; click it to close them. While it works, its newest four steps sit
under its newest message, with **5 earlier steps** above them to open the rest and its running thought in its last
three lines (click it to read the whole thought); its character sits beside the step it is on, with that step's time
once it passes 30 seconds; when its next message lands they fold into their line. With Show
work off, **View steps** beside the working character shows the same. Reading higher up while the agent works, the
button at the bottom shows its character and how many messages arrived, such as **2 new**. When you come back to a
chat, a **New** line marks where its messages start that you haven't seen, and the button says **New** until that
line has been on screen. Each turn's steps include what Lookout told
the model, such as **Told** that its tools changed or that it
now runs on another model. When a turn stops, for example on a used-up plan, the panel over the message box says why
and offers **Continue on**; click its title for the details (the provider's own words, the model, when the plan
resets). Once you pick a move or close the panel, a row in the chat says where the turn stopped. A retry that fails the
same way stays one row, whose details say how often it failed. **Continue on**'s button names the best move, **Continue on** the first model that can
go on when the plan is spent, or **Retry** after a provider failure, and its arrow lists the models the agent can
run now, its fallback models first, each with what is left of its plan (**Per token** for a model billed per token)
and the effort it runs at, then **Wait for the reset**, which lets the turn go on by itself once the plan resets. The
same turn goes on where it stopped, and the chat keeps the model you picked, as a pick in its message box does; the
agent's own model in its profile stays as it was.

A message you send to an agent whose plan is used up doesn't stop there: it goes on with a fallback model that has
room, or waits and goes on by itself once the plan resets, and its reply notifies you when it lands. While it waits
the panel keeps **Continue on** and **Stop waiting**, and **Retry now** tries once at once on the same model: if the
plan still says no, it waits again until the new reset. Signing in another account of that provider wakes it at once:
the wait stops naming the old reset, and the chats waiting on that plan go on there one at a time, each one still
waiting reading **In line: its plan has room**.
A wait longer than 30 minutes, or one with no known reset, notifies you at once so you can pick another model.

An agent keeps one conversation for as long as it exists and rereads it on every turn, so it keeps it lean: it hands
bulk reading (a long file or log, many files), research and side questions to a subagent that brings back only what
matters, and keeps long material in a file in its folder rather than in the chat. Its replies are short chat messages.

An agent's message box is one line: **+**, the text, the model with its effort (its menu holds the models, the effort
slider and the model's variant; `⌘E` goes straight to the slider), the microphone and Send. Its **+** menu (or ⌘/)
lists **Multitask** with its switch, then **Machine** (where the
agent runs, and **Move to** another machine) and **Connectors**, then **Mode** and the commands. **Mark all as read** in the agent's menu clears the unread mark on
every chat of the agent; it is unavailable when none are unread.

**Start over**, in its chat's menu at the top or under **Conversation** in its profile, deletes the conversation and
begins a fresh one. The agent keeps its name, memory, folder, routines and connectors. It asks first, and it can't be
undone.

## Work as a team

A section is a team: each agent filed directly in it knows the others filed there, archived ones aside, by name and
description, on any of your machines (one on another machine is listed with that machine's name). Sections nest ([Organize agents](https://lookout.arcadia.is/docs/agents#organize)), and a section inside another is a team of its
own: an agent in **Northwind/Legal** is on Legal's team, not Northwind's, and a section that holds only other sections
makes nobody teammates. An agent in no section has no team, so a new agent, which starts in no section, introduces
itself to nobody. An agent is not told about your agents outside its section: two sections can each have an agent for
the same kind of work without either agent wondering which one is meant. When the team
changes (you move an agent into the section, by dragging it or with **Move to**, move one out, archive or delete one,
or a teammate's name or description changes), the agents in it hear the whole team as it is now at their next step,
and each one's chat shows one row, **The team changed**, that opens to who is on the team now. Each teammate is listed
with its own id, so a new agent that takes a deleted one's name reads as a different agent.

An agent can message a teammate or an agent introduced to it, ask one for a result, and message you, all with
**Steer**, the tool it also steers its chats with. Any of your chats in a project reaches any agent the same way:
ask it to message the agent by name or by its id (`agt_...`), on any of your machines, and the answer comes back to that
chat. If the agent's machine is offline, the message waits and the chat tells you which machine; the agent gets it
when that machine is back, and its answer comes to the chat then. A message that needs no reply, such as a heads-up,
starts no turn: it shows in the other agent's or chat's conversation as soon as that one is idle, its next turn of
any kind reads it, yours included, and it isn't asked to answer it. In its chat you see:

- **Asked**, **Messaged** or **Replied to** and the other agent's name when it sends, with the message's state, such as
  **waiting for reply**, or **answered** when the reply went to another chat (a reply that comes to this chat
  has its own row right below). One reply to several questions in a row answers each of them. Hover a row to see the
  first lines of the message (of a row with several, the newest and how many there are); click it to open every message
  between the two in the chat's place, at that message: a chat only they write in, the other agent on the left and this
  one on your side, each run under its sender's face and name. Its top bar's menu stops the conversation while it
  runs, and resumes or dismisses one that was held; **Back** returns to the chat where you were. When the agent asked another and ended its turn without a word to you, the chat ends with
  one quiet line, such as **Waiting for Jarvis**, the same words as its row in the sidebar.
- **Message from** or **Reply from** and the sender's name at the top of a turn another agent started, or a chat, an
  app over MCP or a script through the `lookout` CLI (with its glyph). Everything the agent writes in that turn shows,
  without marking the chat unread. Only what you type in a Lookout window reads as yours.
- The other agent's name and **couldn't answer** at the top of a turn, when an agent it asked couldn't answer, for
  example on a used-up plan. The agent hears why and can tell you, or ask another agent.
- A message it sends you as its own reply, with **Notified you** under it and a notification: the agent's name over
  the message's first line.

A notification comes only from a turn that needs you: your own turn's reply, an answer you were waiting for that
another agent passed on, a message to you, or a failure someone must act on, such as **Bud couldn't answer Hazel** over
the provider that needs a new sign-in. One conversation notifies at most once in five minutes, and a wait that
continues on its own notifies nobody.

An agent's row in the sidebar says what it waits on: **Waiting for you** (a question for you to answer in the composer; a reply that ends on a question shows its first line, unread), **Couldn't answer** and the
agent it couldn't answer, **Held with** another agent, what it is doing while it works, **Waiting for** a model and
when that model's plan resets, or how many messages wait for it. Otherwise it shows the first line of what the agent
last said to you, as many whole sentences of it as fit, else its first sentence up to a comma, else as many whole
words as fit, never a cut word (a hover shows all of it, and the row opens the chat); only when its last turn said nothing
to you while it waits does it say **Waiting for** the other
agent (or **Waiting on 2 chats**). A subagent or a chat it started that works on after its own turn has ended shows on
its own row under the agent's, never as the agent's own work. Its eyes
follow: busy while its own turn works, asleep while it waits for a plan or is paused, sad after a failure until you read its
chat (its pill over the open chat stays sad until the next turn). With the sidebar
dragged narrow, the avatar's tooltip says the same.

In an agent's chat, type `@` to point at another agent; pointing at one outside its section introduces it. Messages
from other agents never enter a turn you started: they wait, shown over the message box, and arrive when the turn ends.

### Introductions

An agent sees itself, its team and the agents introduced to it, and nothing else of your agents: a name, an id or a
chat of any other agent is refused as not found, with a note that you introduce agents across sections, and never a
list of who exists elsewhere. An agent in no section starts with nobody.

- **You mention it.** Type `@` and the agent's name in an agent's chat, or pick it from the list `@` opens (this Mac's
  agents; a typed name finds one on your other machines too). The turn that carries your message tells the agent who it is: its
  name, id, section, description and, when it runs on another machine, that machine. From then on the agent reaches
  it in all of its chats. A name that fits more than one of your agents introduces none, and the agent is told to ask
  you which one you mean.
- **It writes first.** An agent that receives a message from another is introduced to the sender, so it can write back
  later, not only reply. A reply to a message always reaches its sender, introduced or not.
- **Before introductions.** Agents that had exchanged messages before this version are introduced to each other once,
  so the conversations they had keep working.

The **Introductions** row of the agent's profile lists them, each with its section and how and when it came; **Remove**
takes one away, and the agent no longer reaches that agent until you mention it again or it writes. Removing one
doesn't stop the other agent from writing: that is its own introduction, in its own profile. In a terminal,
`lookout introductions AGENT` lists them and `lookout introductions AGENT remove OTHER` removes one; an agent can neither
add nor remove one itself. Your sidebar, your mentions, the `lookout` CLI in a terminal and an MCP client acting for you
still see every agent, and so does a chat of yours in a project.

This is a default view that keeps each agent's context lean, not a security boundary: an agent still has full access to
your Mac, as every chat does.

When an agent's plan's usage limit is used up while it works on another agent's message, it waits and continues on
its own when the plan resets. Its chat says **Waiting for** the model's plan and when it resets, with nothing for you
to do; the panel over the message box offers **Continue on** another model that can run now, never one of the plan it
waits on (one on a provider billed per token says so: **Continue on Haiku 5.5, billed per token**), or **Stop
waiting**. The agent that asked hears when, and tells you if the wait is long and you were waiting for the answer. When the agent passing an
answer on to you is the one waiting, its chat draws you once for a long wait, and again when the answer arrives. When an agent can't answer
at all, because its provider needs a new sign-in or a request failed, the
agent that asked hears why. **Retry** in the agent's chat continues the same turn now, or **Continue on** another model, which
the chat then keeps, and its answer still goes to the agent that asked. Picking another model for the agent while it
waits moves the wait to that model: the turn goes on now when that model's plan is open. **Stop** ends the wait: the
agent that asked hears that no answer is coming, and anything else it sent meanwhile is not sent. When what waited was
another agent's answer, the agent that answered isn't woken for it: it hears at its next turn.

## Routines

A routine is a prompt an agent runs on a schedule, in its chat: a morning summary, a weekly review, a reminder at a
time. It can also run when a script of the agent's fires it, the moment something changes
([When a script fires it](https://lookout.arcadia.is/docs/agents#routine-script)). Ask the agent in words, for example "every weekday at 9, read my overnight messages and tell me what needs me",
or "remind me at 17:00 to send the invoice". It sets the routine up and says back the schedule in words with its next
fires, so you can check it understood. Asked to change a sentence of one, it edits that passage of the prompt, not the
whole. Ask for one "but keep it paused" and it is set up switched off, never live for
a moment: the agent says when it would fire, so you can check the schedule before you switch it on. You can also add
one yourself: open the side panel in any chat with the agent,
click **Routines** in its **Profile**, then **New routine**, and fill in the dialog. A chat you start yourself has routines too, up to 20 (a one-shot stops counting once it has run) that fire in
that chat ([Keep watching something](https://lookout.arcadia.is/docs/chats#routines)).

A schedule is one of:

| Schedule | Fires |
|---|---|
| `every 30m`, `every 2h` | every 30 minutes, every 2 hours |
| `every 1d at 18:00`, `every 2d at 09:00` | every day (or every 2 days) at that time |
| `daily 09:00`, `weekdays 09:00` | every day, or Monday to Friday, at that time |
| `cron 0 9 * * 1` | a cron expression: minute, hour, day of month, month, day of week |
| `at 2026-10-12 09:00`, `at 17:00`, `in 2h` | once, then never again |

A routine may fire as often as every minute; one that fires often belongs in a chat of its own (below), and with a
[check first](https://lookout.arcadia.is/docs/agents#routine-check) a fire that finds nothing costs nothing. An agent has at most 50 routines.
Times are in your Mac's time zone when the routine was set up, and stay in it when you travel,
unless the routine follows another clock (a reset at 00:00 UTC, a deadline in another zone), whose zone it keeps and
the Profile tab names beside it. A time that a daylight saving change skips fires when the change is over, and a time
that happens twice fires once.

When a routine fires, the agent works on its prompt in its chat, quietly: a row such as **Routine Morning summary**
starts the turn, and the chat is not marked unread. When the run finds nothing you need to read, the agent can end it
without a reply: the row then says **nothing to report**. To hear back every time, say so in the routine's prompt ("always report back"). You hear from it when the
agent messages you, or when the run
fails (a notification such as **Routine "Morning summary" failed** over the reason; a failure again right after
doesn't notify again, unless the routine runs only once). A failed run tries again by itself, as a run of its own: a
routine that runs once up to four more times, after 5, 15, 30 and 60 minutes, and a recurring one once, after 5
minutes, unless its next time comes first. While Lookout knows its model's plan is used up, a fire or a try waits
for the reset instead of starting a turn that would fail, and a run that failed on a used-up plan that named its reset
tries again just after that reset, without counting toward those tries. A routine that runs once waits up to a day
past its time; a recurring one still waiting at its next time skips the waiting fire, and the next one takes over.
The agent is told of each failure at once, as its kind and the provider that reported it (the provider's own words stay
in the routine's chat, where you can read them). If the agent is busy with your own message, the
routine runs when that turn ends. If its last run is still going, the fire is skipped.

### Its own chat

A routine that runs often, such as a watch on your pull requests every 10 minutes, belongs in a chat of its own. Choose
**Its own chat** under **Runs in**, or ask the agent for one "in its own chat". Each time it fires, the agent works in
that chat, which keeps its own history and leaves the agent's chat clean; you find it under the agent in the sidebar,
named after the routine. What the agent replies there is posted in the agent's chat under a **Routine** row (click the
row to open the routine's chat), without a turn there and without marking the chat unread. A chart or diagram the
reply shows comes with it, as that run drew it. A turn that ends with
nothing to say posts nothing, even when the agent wrote a line on the way, so a routine can stay quiet until something
needs you. The agent reads the posted reports the next time
it works in its chat.

Each fire there, whether its schedule, a script or a webhook started it, also tells the agent what its other chats did
since the routine last ran: the messages they sent, the
chats they archived or started, and the sites they used in the browser. A reply the agent typed into a web inbox from
its own chat then reads as its own work in the routine's chat, not as someone else's.

A routine in its own chat can also run the agent's [chats](https://lookout.arcadia.is/docs/agents#chats): it sees every chat the agent started or was handed,
from whichever of its chats, and steers them as the agent's chat would. A chat it starts reports back to the routine's
chat, or straight to the agent's chat when the routine says that is where its end belongs, and the agent's chat can
steer that one too. To pass something on to the agent's chat, such as how a chat it
started ended, the routine's chat messages the agent itself: the message lands in the agent's chat as one from the
routine, by the routine's name, and the agent starts on it as on any message. Another chat of the agent can do the
same; a message to itself from the agent's own chat is refused.

A routine's chat grows from fire to fire. **Start over**, in that chat's menu at the top, gives the routine a fresh chat
on the old one's model, effort, mode and quota setting. What runs in the old chat stops, and the chats it started
report to the new one, which is shown any question of theirs still unanswered. The old chat stays archived with its
history; a message to it is refused, naming the new chat, until you restore it.

The agent can start its own routines' chats over too, when you or a routine's prompt ask it to. From its own chat or
another routine's chat, that happens at once, as yours does. From the routine's chat itself, nothing stops: the agent
finishes what it is doing there, its reply is posted in the agent's chat as usual, and then the fresh chat takes over.
If Lookout restarts in between, it starts the chat over once it is back.

### Check first

A routine can run a command before each time it fires, in the agent's folder, at no token cost: under **Check first**,
type a command such as `gh pr list --search review-requested:@me`, and choose when the prompt runs: **when its output
changes**, **when it prints anything**, **when it succeeds** (exit 0) or **when it fails**. Otherwise the fire ends
there, at no cost. When it runs, the agent sees what the command
printed. A check stops after 60 seconds. **Run now** runs the check too, and then the prompt whatever the check said.
A change counts as handled only once a turn ran to its end on it: when the turn fails or is stopped, the next fire
wakes on the same output again, and the agent is told the run before it failed.

### When a script fires it

A routine can run when something changes instead of on a schedule: a log prints an error, a build fails, a file lands
in a folder, a mail comes in, a page changes. The agent writes a script that notices the change and fires the routine,
and wakes with the routine's prompt only then, with no check every few minutes meanwhile. Ask the agent in words, for
example "when the nightly build fails, tell me which test broke", or choose **When a script fires it** under **Runs** in
**New routine**.

A script fires it with one command, from anything that runs on the agent's machine: a command the agent runs, a script
it starts, cron, a git hook.

```sh
lookout trigger "Build failed" --data "build 41 failed: test_checkout"
```

`--data` is the event's data, text or JSON, at most 64 KB; `--data -` reads it from stdin. A program that isn't a shell
script posts the data to Lookout on that machine instead, with the routine's own token:

```sh
curl -s -H "X-Lookout-Trigger: $LOOKOUT_TRIGGER_BUILD_FAILED" --data-binary @report.json "$LOOKOUT_TRIGGERS_URL/<routine id>"
```

The agent's commands have both in their environment: `LOOKOUT_TRIGGER_` and the routine's name in capitals and digits
(`Build failed` is `LOOKOUT_TRIGGER_BUILD_FAILED`), and `LOOKOUT_TRIGGERS_URL`. A token fires its one routine, and only
from that machine: Lookout refuses it from another machine, refuses another routine's token at this one, and the agent's
chat never shows it (output that prints it reads **[stored credential hidden]**). From a terminal of your own, name the
agent: `lookout trigger "Build failed" --agent Wren`.

Each fire is an event, read as a webhook's is: the agent wakes with the routine's prompt and the event's data, marked as
data a script sent, not your words. **Check first** gets each event's data on its input, so `grep -q FAILED` with **when
it succeeds** lets only the failures through, at no token cost. One turn reads up to 10 events or 32 KB, and the rest
wait for the next; events that come together are read in one turn, and nothing runs while none come. Lookout sets no
limit on how often a script fires one; a [limit](https://lookout.arcadia.is/docs/agents#limits) you set on the agent still holds.

**Keep running** names a command Lookout keeps running for the routine, a watcher such as
`tail -n 0 -F logs/app.log | grep --line-buffered ERROR`: each line it prints fires the routine with that line as its
data, so a watcher needs no `lookout trigger` at all. Lookout starts it in the agent's folder, starts it again when it
exits (after a second, doubling up to 5 minutes while it keeps exiting), stops it while the routine or the agent is
paused, and starts it again when Lookout starts. The routine's row shows how many events came today and the last one,
and the command's state: running since when, or exited and starting again, with its last error line. **Copy trigger
command** in the routine's menu copies the line a script fires it with.

What `lookout trigger` and a POST hear back:

| Answer | Means |
|---|---|
| 202 | Taken. |
| 401 | No token, or one that fires no routine on this machine. |
| 403 | Another routine's token, or a call from another machine. |
| 404 | No such routine, or not one a script fires. |
| 409 | The routine is paused. |
| 413 | The data is over 64 KB. |
| 429 | The agent reached a limit you set. |
| 503 | The agent is paused or moving to another machine: fire again later. |

### When a webhook arrives

A routine can run when another service sends it an event instead of on a schedule: an alert, a finished deploy, a
form someone filled in. In **New routine**, choose **When a webhook arrives** under **Runs**, then how the sender signs
its events:

- **The sender's public key**: paste its Ed25519 key (`whpk_` and its 32 bytes in base64).
- **A secret**: Lookout makes one when you save and shows it once, with **Copy**, for you to give the sender. **New
  secret** in the routine's menu makes another, and the old one keeps working for a day.

**Copy webhook URL** in the routine's menu, or **Copy** beside its **Webhook URL** under **Edit**, gives you its
address. Senders post to it in the
[Standard Webhooks](https://www.standardwebhooks.com/) format (`webhook-id`, `webhook-timestamp`,
`webhook-signature`), with a body of at most 64 KB. It works for an agent on this Mac or on a server, and no port opens
on either: the event reaches the agent's machine over the connection it already keeps with your Lookout account.

Each event is a run. The agent reads events as data a webhook sent, not as your words, beside the routine's prompt; one
turn takes up to 10 events or 32 KB, and the rest wait for the next. **Check first** gets each event's body on its
input, so `jq -e '.severity == "high"'` with **when it succeeds** lets only the high ones through, at no token cost. The
routine's row shows its last event and how many came today. Only you set one up or change it, never the agent, and its
secret never reaches the agent's commands or its chat.

What a sender hears back:

| Answer | Means |
|---|---|
| 202 | Taken. |
| 200 | An event with that `webhook-id` was already taken in the last day. |
| 400, 401 | The timestamp is more than 5 minutes off, or the signature doesn't match. |
| 429 | Too many: 20 events already wait, the routine's 120 an hour are reached, or the agent's own limit is. |
| 503 | The agent is paused, or its machine is offline: try again later. |
| 404, 410 | The routine is switched off, or was deleted. |

### When Lookout is off

Routines run while Lookout runs on your Mac and the Mac is awake. If the Mac slept or Lookout was closed when one was
due, it runs once when Lookout is back, late, for all the times it missed, unless its next time is close anyway. A
routine set for once runs when Lookout is back within a day of its time. A routine's turn cut off by a crash continues
by itself once Lookout restarts.

A time a routine missed or skipped is not lost on the agent: the routine's next run, or else the agent's next turn in
its chat, says which times it missed and why (its chat was waiting for the network, waiting for its plan, busy in a
turn, the agent was paused, Lookout was restarting, or Lookout was off), with what its check printed the last time. When the agent lists its
routines, or sets one up or changes one, it also hears when it last fired, how many times it was skipped since, and
what the last run cost (how much it read, in which chat), so it can move a frequent routine into a chat of its own. A
routine keeps its last 20 runs that fired apart from the times its check found nothing, so a quiet check never pushes
them out.

Each routine under **Routines** is one line: its name, its schedule in words and when it fires next, with a second
line only when its last run failed or it waits (for its plan, or for a failing check). Its switch pauses or resumes it at once, and it stays that way when Lookout restarts: a paused routine
skips its times rather than saving them up. Its menu has **Run now**, **Edit** (a dialog with its name, prompt, schedule, where it runs
and its check) and **Delete**. Click a routine's row in the agent's chat, such as **Changed routine Morning summary**,
to open its routines. Pausing the agent, or **Pause all agents**, skips its routines too.

### Memory review

Every agent comes with a routine called **Memory review**, switched off. It checks the agent's own memories against
the present: each one not saved or confirmed in the last 7 days, oldest first, against the files, commands and
settings it names. A memory that still holds is confirmed, one that changed is corrected, two that say one thing
become one, and one that is gone or done is forgotten; what can't be checked from the agent's machine stays as it is.
It never changes a memory you wrote, and never your Everywhere memory. It runs in a chat of its own and posts a short
report in the agent's chat; a run with nothing to report posts nothing. **Run now** in its menu reviews every memory
at once; its switch runs it each Monday at 9:00, and a week with nothing due costs no tokens. Each change it makes is
kept under **Forgotten** in [Settings › Memory](https://lookout.arcadia.is/docs/memory#settings) for 30 days, where **Restore** puts the earlier
version back. Delete it and it doesn't come back.

## Start chats from an agent

An agent can start whole chats of its own in your projects, hear what becomes of them and steer them, the way an
orchestrator does over [MCP](https://lookout.arcadia.is/docs/mcp). Ask it in words, for example "start two chats with worktrees for these two
tasks, one per task". It has three tools for this:

- **Delegate** starts a chat in a project, named or given as a folder (a folder inside a project's repository joins
  that project), on this Mac or another of your [machines](https://lookout.arcadia.is/docs/machines), or the one with the most room. It can pick
  a model and give the chat its own [worktree](https://lookout.arcadia.is/docs/worktrees), started from a branch it names; a chat it starts in a
  folder another chat is changing gets one [anyway](https://lookout.arcadia.is/docs/worktrees#shared). It can ask the chat
  to end by submitting a structured result, and say what happens when a plan runs out: wait for its reset, or move to
  a fallback model on your list. It can attach files from its own machine for the chat to read with its first
  message: never from Lookout's own state (its own folder aside) and never a credential (a key, a sign-in, an env or
  secrets file, a file holding a token, or a link to one), and known secret values are scrubbed out before a file
  leaves the machine. With no project named, it works in the agent's first project (Profile, Projects), on
  another machine in that machine's project of the same repository or name. A lane names a line of work: the agent's
  next prompt on the same lane goes to the chat it already started there, attachments included. That chat keeps its
  project, folder, machine and worktree, so asking for another is refused; another model, effort, mode or plan policy
  moves the chat first, and the result says what changed.
- **Sessions** lists the chats it started and how each is doing, reads one in depth (its state, todos and last reply,
  and the end of its conversation when it asks for it), or reads one chat's changes: the
  files it changed with their stats, then the diffs, for the whole chat, its last turn or its uncommitted work. It
  also lists the models with what is left of each plan, your machines and your projects.
- **Steer** sends a follow-up to one of those chats, runs its last turn again after a failure, a cut or a stop (on
  another model when a plan is used up, or once the plan resets: the chat waits and goes on by itself), stops it, archives it once it
  has finished, or merges its [worktree](https://lookout.arcadia.is/docs/worktrees#merge) branch into your project's current branch. Without
  stopping a chat, it can move it to another model and effort from its next turn, and set what it does when a plan
  runs out (wait for the reset, or go on with fallback models from the agent's list); the chat's settings notice
  names the agent. It also sets how many
  chats of a project it works on run at once, on each of your machines, when you ask it to speed up or slow down, and
  carries the agent's messages to your other agents and to you ([Work as a team](https://lookout.arcadia.is/docs/agents#team)).

These chats are the agent's, not one chat's: its own chat and a routine's own chat see and steer the same ones. The
agent doesn't poll. When a chat it started finishes, waits on you or fails, the chat that started it hears so at its
next turn (the agent's chat, for a chat handed to it, or once the starting chat is gone), which starts by itself and
quietly: its chat shows a row, such as **Fix smoke e2e finished**, and the agent decides what comes next. Click the
row (or press Enter on it) to read that chat's last reply right there, with **Open chat** to go to it; Esc closes it.
Chats that end together are one row, such as **2 finished, 1 failed**, which opens to each. A chat archived before
the agent heard it finish, such as a lane chat Lookout archives once its landing closes the lane, is still told, once;
one the agent archived itself is not. A chat whose
turn ends while its own work still runs (a background command, a watch, a subagent, a workflow) is working in the
background, not finished: the agent hears from it once that work ends and the chat settles again; after 30 minutes,
its next turn for any reason is also told that the chat still works in the background. Only what the agent can act on
starts a turn by itself: an end, a failure, a question, a worktree an archive kept. What needs nothing from it rides
along its next turn: a worktree its archive removed, its own stops, and a chat that waits at a plan's limit when
another of its chats already waits on that plan, or the limit resets within 30 minutes. A chat
an update or a restart pauses is no news: it resumes by itself, and the agent hears of it only when it finishes, or if
it hasn't resumed two minutes after its machine is back. A Steer to a chat whose machine is updating waits for it, or
says there is nothing to do. A chat on another machine is heard even when the link between the machines drops or
either restarts: that machine keeps the news until the agent's machine takes it, and Sessions keeps listing the chat
as unreachable, with its last known state, until the machine answers again. A machine that is gone for good leaves
the agent's lists once you remove it in **Settings › Devices**. The chats it starts are ordinary chats of their project; hovering one shows **Started by**
the agent and the lane, an open one leads its top bar with the agent and every chat between, each a click back to its chat, and the chat's first message
says **From** the agent.
In the agent's chat these steps name what happened, such as **Stopped lk-fix-509** or **Retried lk-fix-509**.
A destination on another machine is named with it, such as **on build-vps**. When Lookout knows the destination,
its name offers to open it after checking that the chat can be read there. Unknown destinations and machines
removed from the account have no link; a deleted local chat loses its link after the check. A remote chat whose
state this window does not hear shows no done mark or made-up duration, only what started it and where.
An old link with a recorded remote machine can offer **Open on build-vps** when that machine is still in the
account. If that machine cannot answer or has left the account, the page says so.
In that remote view, attaching files and dictation are unavailable rather than writing them to this machine, and a
workflow run's controls act on the chat's machine or say why they are unavailable.
A stop caption names who stopped the turn when that source was recorded; an unknown source reads **Stopped**.
While they work, the agent's row in the sidebar says **Waiting on 2 chats**.

Only a chat with work in flight counts there (a turn running or waiting on its plan, a start in line, a workflow run
going): a chat that never ran a turn doesn't, and **Sessions** names it plainly, as an idle workflow host with how many
runs it hosted, or as never started. Handed such a chat, the agent hears of it at once.

You can also give an agent a chat it didn't start: a chat's menu, **Hand to**, and the agent (or **Hand by lane
prefix** beside it, to hand every chat whose lane starts with a prefix, on the machine you pick, in one pass), or
`lookout handoff CHAT --to AGENT` in a terminal. It joins the agent's **Sessions**, the agent hears it once it settles and steers it from
then on, and its row leads with the agent's avatar (**Handed to** the agent on hover). Any other agent that held the
chat is told it went elsewhere. A [connected app](https://lookout.arcadia.is/docs/other-apps) can hand over any of your chats
(`lookout_handoff`), on another of your machines too, so a session that ends leaves its work with an agent.

How an agent works with chats:

- Its words lead a chat, which then follows them as it follows yours, only in the chats it started or that were handed
  to it, and it never takes a chat by itself. They always show its name. A send to any other chat of yours, or to
  another agent, is a message from the agent; a subagent's is a
  message too, named as that chat's subagent. Its stop, retry, archive, merge and answer act on any chat when asked,
  recorded under its name.
- A chat it started or was handed can ask it a question while it keeps working: the agent reads it at its next step
  and answers with a message, and its chat shows the question, its choices and the answer as one row. The chat's line
  says **Asks a question** until the agent reads it.
- It answers a plain question a chat asks (the card then reads **Answered by** the agent),
  but never an approval (more workers): that waits for you under **Needs you**, where every
  question shows at once. Whoever answers first wins.
- One turn (your message's, or one Lookout starts on its own) may start or steer as many chats as **Agents without
  asking** allows ([Settings › Chat › Subagents](https://lookout.arcadia.is/docs/subagents#model), 24 unless you change it). Past that, a card
  asks you whether to allow more.
- It archives only a finished chat, never one still running. A message or retry it sends to an archived chat brings
  the chat back, when Lookout or an agent archived it, such as a lane chat Lookout archives once its landing closes the
  lane; one you archived stays archived, and the agent is told to ask you.
- It lands a chat's work only on your project's current branch ([Land the work](https://lookout.arcadia.is/docs/worktrees#merge)). A conflict
  changes nothing: the chat itself is told, with the conflicting lines, and repairs it in its worktree. Whether landing
  is how work reaches a project is up to that project's rules, which the agent reads; there is no switch to set. The
  worktree and its branch stay after a landing.
  Nothing it does deletes or rewinds a chat. When it archives a chat, that chat's worktree is removed only when it
  is safe to remove, as when you archive one ([Worktrees](https://lookout.arcadia.is/docs/worktrees)). **Stop conversation** in
  Agent activity also stops the chats that conversation started and those handed to its agents.
- It can set how many chats of a project run at once on a machine, up or down or to no cap, as you can in the
  project's [settings](https://lookout.arcadia.is/docs/settings#project). Each change is recorded under the name of whoever made it. Every
  other project setting, its worktree commands included, is yours.

## Watch and stop a team

The Agents actions, `⋯` at the end of the sidebar's switch while **Agents** shows, hold the controls:

- **Agent activity** lists the conversations between your agents, newest first, from the **Last hour**, **Today** or
  the last **7 days**, each with its state, such as **Live**, **Held** or **Stopped**. **Show messages** draws one as a
  chat. **Stop conversation** stops a live one; **Resume** or **Dismiss** settles one that was held or stopped.
- **Pause all agents** pauses every agent on every machine of your account that runs agents: what they run stops,
  and messages wait. A machine that was off reads it before its agents start anything. Your own messages still run.
  **Resume all agents** lets them go.

**Pause** in an agent's Profile tab does the same for that agent alone: its turns that you didn't start stop, with its
subagents, background commands and the chats it started. **Resume** in the bar over its message box lets it go on.

## Limits

An agent has no limits until you set them: **Limits** in its Profile tab reads **No limits**, or the ones set. Open it
and choose **Add a limit**:

- **Per turn**, in tokens or dollars: a turn stops at its next request past it, yours too. **Continue once** goes on
  with a fresh turn's limit; **Change limits** opens them.
- **Per day**, in tokens or dollars, by your time zone: past it, nothing the agent starts by itself runs until
  midnight. Messages to it wait and its routines are skipped. Your own messages still run.
- **Per hour**: turns the agent starts by itself in any hour.

Each limit set has its field and a button that removes it.

Dollars count only requests a provider bills per token. **Today** shows what it spent so far. A chat the agent starts
carries its limits, on whatever machine runs it. Only you set them: an agent can't change its own limits or resume
itself.

## Controls

These settings in an agent's Profile tab save at once, and only you can change them:

- **Only you edit it** (under **Limits and access**): no agent, this one included, can change its name or
  description, and it can't set up, change, pause or delete its routines. It still reads them, and you edit them
  as before.
- **Learn from its chat** (under **Memory**): off, Lookout saves nothing it learns from the agent's chat to memory. On by
  default.
- **Read Everywhere memory** (under **Memory**): off, the agent's chat is not shown your Everywhere memory. Its own
  memory stays. On by default.
- **Allowed models**: the models its chat, its subagents and the chats it starts may run on. **Any model** by default;
  its own model stays on the list. Switching one of those chats to a model off the list is refused, and a turn on one stops
  before it sends anything, saying which models are listed. To keep an agent off a model you don't want it on, list
  only the ones it may use.

Only you export or import an agent: an agent can't, so an old file can't bring back what you changed since.

### Set up an agent

Any agent can set up another on the same machine: tell it what the new agent is for, for example "set up @Librarian
to keep our docs in order", and it writes that agent's name, description and the standing instructions in its
folder's `AGENTS.md`. Agents also keep each
other's profiles current on their own judgment (a teammate left, a role moved), and your instructions to them say how
you want that done. The agent that was changed hears at its next turn who changed what. Its models, limits, lock and
memory switches stay yours, and with **Only you edit it** on, no agent changes it.

A machine can be kept to its agents too: `lookout capacity --on vps --agents-only on --agents-max 1` refuses any other
new chat there and a second agent ([Machines](https://lookout.arcadia.is/docs/machines)).

Conversations have no automatic message-count, back-and-forth or volume cap by default. Agents can keep coordinating
without you. **Stop conversation**, **Pause** and **Pause all agents** still hold their work, as do limits you
explicitly set. A banner over the agent's message box says why, with **Dismiss** and **Resume** for a held conversation.
A restart releases messages held only by the former automatic caps; it leaves your stops, pauses and limits in place.

## Organize agents

Sections nest to any depth, so the group can read like a company: **Northwind** holding **Executives**,
**Engineering** and **Legal**, and **Forward deployed** holding a section per customer. The agents filed directly in a
section are a [team](https://lookout.arcadia.is/docs/agents#team).

- **New section** in the group's menu adds a section at the top, and **New section inside** in a section's menu adds
  one in it; either opens its name to type. Two sections can share a name only in different places, and a name holds
  no `/`.
- Inside a section, its own agents come first, then the sections in it, each level one step in. Past four levels the
  rows stop stepping in, and the pointer on a section shows its whole path, such as
  **Northwind / Forward deployed / Contoso**. At the top, sections come first and the agents in no section last.
- **Drag** an agent or a section onto a section's name to move it into that section. Drop it on the upper or lower edge
  of a row to put it just before or after that row, in that row's section. Drop it on the agents in no section to take
  an agent out of its section, or to bring a section to the top. A section never goes into itself or a section inside
  it.
- **On every machine at once.** Renaming, moving or deleting a section does it on each of your machines that holds
  it, and an agent filed in a section its machine doesn't have yet gets that section there. If one of those machines
  is offline, Lookout asks first: its copy keeps the old name or place, and shows as a section of its own, until you
  do the same there once it is back. A moved agent lands in the section of the same path on its new machine, with its
  team.
- A section's menu has **New agent here**, **New section inside**, **Rename**, **Move to**, **Move up**, **Move down**
  and **Delete section**. **Move to** lists the sections in order, each with the path of the section it sits in, under
  a field that finds one by name or path; **Top level** moves it to the top.
- **Move to** in an agent's menu is the same list, with **No section** and **New section**, and so is **Section** in
  its [Profile](https://lookout.arcadia.is/docs/agents#profile).
- **Delete section** loses nothing: its agents and the sections inside it move up into its parent, or to the top,
  after what is there. A section whose name a section there already has takes the next free one, such as
  **Engineering 2**.
- Click a section's name to fold it; this device remembers which are folded. A folded section counts the agents in it,
  the sections inside it included, and shows the dot of the most urgent one: **needs you** first, then working.
- **Pin** keeps the agent in the row of avatars at the top of the group, up to six. Right-click an avatar there for
  its menu and **Unpin**. **Pin** in its chat's menu pins the agent too.
- **Archive** hides the agent and takes it off its team; **Show archived** lists archived agents again.
- **Delete agent** deletes its conversation and its folder. Projects it works on, and their folders, are kept.

## Related

- [Memory](https://lookout.arcadia.is/docs/memory.md): What Lookout remembers across chats, for you and for each project, and how to see and change it.
- [Rules](https://lookout.arcadia.is/docs/rules.md): The instruction files a chat reads from each of its folders, how an edit reaches a running chat, and the ignore files that keep the agent out of paths.
- [Connectors and skills](https://lookout.arcadia.is/docs/connectors-and-skills.md): Give the agent more tools with connectors (the official ones are in the Marketplace), playbooks with skills, and both together with plugins.
- [Chats and projects](https://lookout.arcadia.is/docs/chats.md): Projects hold your folders and their chats, and the message box sends, queues, steers and stops the agent's work.
