Use Lookout
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 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). A machine that runs Lookout from the CLI (lookout up) has no agents
until you turn them on there.
Create an agent
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, such as a VPS:
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:
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.
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 |
| 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). 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). Introductions: the agents outside its section it was introduced to, each with its section and how and when, and Remove (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. Logins: its site logins, by site and username. See Give an agent a site login |
| Limits and access | Limits: see Limits. Only you edit it: see 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.
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.
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.
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 is shared with every chat
and agent, on every one of your machines (On every machine). A memory the agent wrote that you
share Everywhere keeps its name as the one who saved it. It reads the 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); Profile goes back. What the agent has at work shows under its row in the sidebar, from any of its chats: its 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,
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 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), 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:
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.
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). 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).
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 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: 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.
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:
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 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:
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 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 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. Ask it in words, for example "start two chats with worktrees for these two tasks, one per task". It has three tools for this:
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 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:
Watch and stop a team
The Agents actions, ⋯ at the end of the sidebar's switch while Agents shows, hold the controls:
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:
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 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).
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.