---
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.itoowasinarcadia.com/docs/agents
type: guide
section: Use Lookout
last_updated: 2026-10-22
related:
  - https://lookout.itoowasinarcadia.com/docs/memory
  - https://lookout.itoowasinarcadia.com/docs/rules
  - https://lookout.itoowasinarcadia.com/docs/connectors-and-skills
  - https://lookout.itoowasinarcadia.com/docs/chats
---

> Every page of these docs: https://lookout.itoowasinarcadia.com/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 in the **Agents** group of the sidebar, above
Projects. Agents you put in the same section know each other and message each other, so a section works as a team.

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.itoowasinarcadia.com/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, click **New agent** (the `+` beside **Agents**).
2. The agent opens in its chat, with a name picked for it.
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.itoowasinarcadia.com/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.itoowasinarcadia.com/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 **+** beside **Agents** in the sidebar 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.
- **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.** It reads **Moving to vps-1** with how far it got, then shows up under the new machine's
  name. 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.itoowasinarcadia.com/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.itoowasinarcadia.com/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.itoowasinarcadia.com/docs/rules#limits)). **Projects**: the projects it works on; its chats see their folders beside its home. **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.itoowasinarcadia.com/docs/agents#secrets). **Logins**: its site logins, by site and username. See [Give an agent a site login](https://lookout.itoowasinarcadia.com/docs/agents#logins) |
| **Limits and access** | **Limits**: see [Limits](https://lookout.itoowasinarcadia.com/docs/agents#limits). **Only you edit it**: see [Controls](https://lookout.itoowasinarcadia.com/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 another agent's, 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.itoowasinarcadia.com/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 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. 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, hex), not a value a command has changed (reversed, cut, split across lines, hashed, or shown in a
  screenshot).
- **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.

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.
- **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. 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.
- **In its profile.** **Logins** in the **Profile** tab opens each by site and username on one line, with **Auto
  fill**, **Replace** and **Remove**, and **Add login** at the top opens a dialog that saves one before the agent asks.

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.itoowasinarcadia.com/docs/memory) is shared with every chat
and agent, on every one of your machines ([On every machine](https://lookout.itoowasinarcadia.com/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.itoowasinarcadia.com/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.itoowasinarcadia.com/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.itoowasinarcadia.com/docs/subagents) and the chats its routines run in, three at most, what needs you first. 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.itoowasinarcadia.com/docs/connectors-and-skills#sign-in),
[keys](https://lookout.itoowasinarcadia.com/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.itoowasinarcadia.com/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 **+** menu 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**. 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 keeps four controls: **+**, the text, the microphone and Send. Its **+** menu (or ⌘/) lists
**Model** with its effort (the models and the effort slider under them, `⌘E` straight to the slider), the model's
variant and **Multitask** with their current values, 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 in it knows the others in it, archived ones aside, by name and description. An agent
in no section has no team, so a new agent, which starts in no section, introduces itself to nobody. 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 another, ask one for a result, and message you, all with **Steer**, the tool it also steers its
chats with. It messages an agent outside its team too, by name, when the work needs it: two leads coordinate
directly, for example before a heavy job on a machine they share. 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 see every message between the two as a chat, opened at that message, the
  other agent on the left. 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. Everything the
  agent writes in that turn shows, without marking the chat unread.
- 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**). Its eyes
follow: busy while it works, asleep while it waits for a plan or is paused, sad after a failure. With the sidebar
dragged narrow, the avatar's tooltip says the same.

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

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. 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 5 that fire in
that chat ([Keep watching something](https://lookout.itoowasinarcadia.com/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 fires at most every 15 minutes in the agent's chat, or every 5 minutes in a chat of its own (below), and an
agent has at most 50. Times are in your Mac's time zone when the routine was set up, and stay in it when you travel; 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 its model's plan is used up, the try waits until the plan is back.
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.

A routine in its own chat can also run the agent's [chats](https://lookout.itoowasinarcadia.com/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.

### 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.

### 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, 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.

## 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.itoowasinarcadia.com/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.itoowasinarcadia.com/docs/machines), or the one with the most room. It can pick
  a model and give the chat its own [worktree](https://lookout.itoowasinarcadia.com/docs/worktrees), started from a branch it names; a chat it starts in a
  folder another chat is changing gets one [anyway](https://lookout.itoowasinarcadia.com/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, 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 (on another model when a plan is used
  up or after a stop, 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.itoowasinarcadia.com/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.itoowasinarcadia.com/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 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, or after 30
minutes, told that it is still working in the background. 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. 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, a click back to the agent's chat, and the chat's first message
says **From** the agent.
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.itoowasinarcadia.com/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 reach you in your name only in the chats it started or that were handed to it, and it never takes a chat
  by itself. 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.
- 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.itoowasinarcadia.com/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.
- It merges only into your project's current branch. A conflict leaves your checkout as it was: the agent is told to have the chat
  resolve it in its worktree first. Whether merging is how work lands in 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 merge.
  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.itoowasinarcadia.com/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.itoowasinarcadia.com/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** group's menu, the button beside its `+`, holds 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.itoowasinarcadia.com/docs/machines)).

Lookout holds a conversation by itself when two agents keep messaging back and forth without other work, or when it
passes 10 messages between agents since you last wrote in it. After unusual message volume across your agents, it
pauses them all. A banner over the agent's message box says why: a held conversation reads **Held with Bud** and why,
with **Dismiss** and **Resume**, the same row as under the conversation itself; the pause offers **Resume**.

## Organize agents

- **New section** in the group's menu adds a section; **Move to** in an agent's menu files it there. The agents of a
  section are a [team](https://lookout.itoowasinarcadia.com/docs/agents#team).
- **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.itoowasinarcadia.com/docs/memory.md): What Lookout remembers across chats, for you and for each project, and how to see and change it.
- [Rules](https://lookout.itoowasinarcadia.com/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.itoowasinarcadia.com/docs/connectors-and-skills.md): Give the agent more tools with connectors, playbooks with skills, and both together with plugins.
- [Chats and projects](https://lookout.itoowasinarcadia.com/docs/chats.md): Projects hold your folders and their chats, and the message box sends, queues, steers and stops the agent's work.