Use Lookout
Chats and projects
Projects hold your folders and their chats, and the message box sends, queues, steers and stops the agent's work.
A project is a repository (or a folder) the agent works in, with any extra folders you add in its Project settings. Every chat belongs to one project, and the sidebar lists your projects with their chats under them. Scratch, one shared project for chats that need no folder of yours, is always its first row. Its chats start with memory off, and a project's settings can turn memory on or off for its own chats (Memory per project).
Start a chat
To start a chat in a project you already have, click + on its row in the sidebar.
A new chat is named by the opening words of your first message, whole, until Lookout names it from that message and the first reply, a moment after the reply starts. A name you give it with Rename is never replaced.
Open a folder
A project is identified by its repository, not by a folder's path. When you open a folder (Open folder, the sidebar's New project under the projects, lookout exec, or a delegate over MCP):
Open folder shows the macOS folder panel. It starts in the folder you last picked from, or at the path you typed into the picker's search, and its New Folder button makes one to open. In a window on another machine, Lookout lists that machine's folders itself, and the picker has New folder too.
To make a checkout a project anyway, choose Open as its own project in the picker, or Move to its own project in the menu of a chat that works in one: the chat moves with it. LOOKOUT_SCRATCH_ROOTS (folders separated by commas) replaces the temp and lane roots; set it empty and no folder opens in Scratch.
Write a message
| To | Do this |
|---|---|
| Send | ⏎ |
| Start a new line | ⇧⏎ |
| Bring back a prompt you sent | ↑ on the first line, once per prompt: this chat's newest first, then the project's other chats'. ↓ goes forward, and past the newest (or Esc) brings back what you had typed. Only the text comes back, not attachments |
| Mention a file, folder, chat, project or skill | Type @ (Context) |
| Send a skill with the message | Type / and its name anywhere, as in "then use /visualize", and pick it from the list (Use a skill) |
| Point at exact lines of a file | Select them in a diff or a preview and press ⌘L (Add lines) |
| Attach an image or a file | Paste it, drop it anywhere on the chat, or click + › Image or File. It can be the whole message |
| Save a note to memory | Start the message with #, or #! for a note every project sees |
| Change the mode | ⇧Tab (Modes) |
| Dictate, on a Mac | Click Dictate (the microphone) and speak, or hold ⌃M and release to insert. ⏎, ⌃M or Insert dictation inserts the text, Esc or Discard throws it away. The text goes to the chat you recorded in, even after you switch chats. A take that ends with the word in Settings › Chat sends, and the word is left out. Right-click the microphone for Recent dictations (Mac app) |
| See every command and mode | Click +, or press ⌘/ |
The + menu lists the modes, then Image, File, Remember something and, in a chat, Connectors and Compact context. Type / at the start of a message for commands; anywhere else / lists skills:
The model and its effort are one control in the message box beside Send, such as Opus 5.5 Max, in a coding chat and an agent's alike; its menu lists the models with the effort slider under them, and ⌘E opens it on the slider.
Send while the agent works
While the agent works, a message you send waits for it, one of two ways:
In a coding chat, Settings › Chat › When you send decides which (Queue by default). In an agent's chat a message steers by default: an agent's turn can run for half an hour, and it reads your message at its next step instead of after the turn. While the agent works, the empty message box says which way a message goes (Steer Hazel, Steer the agent or Queue a follow-up), and the send button's tooltip says it whole (Steer, read at the agent's next step or Queue, runs when the agent finishes) with what ⌘⏎ does instead. Press ⌘⏎ instead of ⏎ to send one message the other way, in either kind of chat.
Waiting messages sit above the message box: one is a single line, Queued and its words; more sit under N queued. Once a message has waited a minute, its line ends with how long: Queued 12 min for a lone one, 12 min (or Steer, 12 min) under N queued. Each line shows as many whole sentences as fit, else the first one up to a comma, else whole words; never a cut word. Click one (or press ⏎ on it) to read it whole, with Copy, Edit, Remove, and Steer at the next step while the agent works; Esc closes it. Drag a message to reorder it. From an empty message box, press ↑ to reach the last one; then E edits it, S steers it, ⌫ removes it, and ⌥↑ or ⌥↓ moves it.
Edit puts the message in the message box, and its line says Editing and ends in Discard. The check where send was (⏎) saves it in its place; Discard or Esc leaves it as it was.
Queued messages run one per turn. A queue holds up to 100 messages.
Messages you send while Lookout pauses for an update or a restart wait in the queue and run together, in the order you sent them, as soon as it is back. A message you send after that never runs ahead of them.
Stop the agent
Press Esc with the message box empty, or click the stop button: while a turn runs it takes Send's place when the message box is empty, and sits beside Send once you type. With no turn running, Send stays Send.
A failed turn pauses the queue the same way (Paused, the last turn failed), and so does Lookout restarting unexpectedly while messages wait (Paused after a restart).
Stop everything in a project
When a plan is burning or a change went wrong, the project's menu (its row in the sidebar) has Stop all in this project. Every chat of that project with something running stops whole: its turn, its background subagents, a question it was waiting on. A toast says how many chats it stopped, and other projects keep running.
Stop all and hold does the same and also holds the project's new work until you choose Resume project from the same menu: delegated turns from an outside orchestrator are refused with the code project_paused, and agent chats in the project stay idle. Your own messages still run.
Try again after an error
When a turn fails, the chat says why and offers what can be done:
If Lookout stopped while a turn was running, the turn reads Interrupted. Click Continue to pick it up where it stopped.
Edit and resend a message
Resending removes every later message in the chat. If files changed since that message, Lookout asks Revert files to this message?: Revert files puts your files back as they were then, and Keep files (⇧⏎) leaves them as they are.
Answer the agent's questions
The agent can stop to ask you something. Its question appears above the message box with numbered options.
Your answer then shows right after the question as a message you sent: the option's name, the options you checked, or the words you typed, one line for each question. A message you send while the question waits answers it the same way. The question's own row keeps what was asked.
Have a chat message another
Ask a chat to talk to another of your chats or agents, in words ("ask the rootway chat whether the mesh is up") or by
mentioning it with @. It finds the chat by its title or lane, sends the message, and carries on; the answer arrives in
the chat that asked when the other one replies. Both chats show the message: the sender's as the command it ran, the
receiver's as a message From the sending chat.
Keep watching something
A chat you started yourself can keep an eye on something for you between your messages: ask in words ("watch PR 1919's checks and tell me when they change", "remind me at 9 tomorrow"). The agent sets up a routine: a prompt that starts a turn in that chat on a schedule, as often as every minute, often after a check, a command that runs first and costs nothing, so the turn runs only when its output changed. A routine keeps going across your messages and across a restart of Lookout, unlike the agent's watch on a command, which your next message ends (the command keeps running).
Charts, diagrams and briefs
The agent can answer with a chart, a diagram or a layout (a brief or a status card: an agenda, progress, a few
numbers, a checklist), drawn in the chat. It knows the skill, so asking in plain words can be
enough; /visualize anywhere in your message (at the start, or "maybe using /visualize?") sends the skill with it, so
the agent answers with one. A follow-up in the same chat draws a new one, and the earlier chart stays as it was. A
Mermaid or Vega-Lite block the agent writes in any reply draws as a chart too.
The agent writes each one as a Vega-Lite, Mermaid or layout file under .lookout/visuals/ in the project and checks it
draws before it shows it, in every mode; the check also tells it how the chart will read in the chat (labels hidden for
lack of room, its own labels overlapping, a diagram too wide to read), so it can fix that first. A chart the check
could not finish (it ran out of time, or the checker stopped) is not shown, and the agent is told why. A chart grows with its
rows and wraps long names instead of cutting them, and a chart the agent deletes no longer shows. A chart's menu opens
it large (at the window's size, with its spec, data files and what the check found), copies or saves the image, copies
the source or the data, and shows the data as a table; a layout draws in the app's
own look in both themes, and its menu copies it as text or copies its spec.
Math and chemistry
LaTeX in a reply renders as math: $x^2$ or \(x^2\) inside a sentence, and display math between two $$ lines,
between \[ and \], or in a math code block, with environments such as aligned, cases and pmatrix.
Chemistry renders through \ce{2H2 + O2 -> 2H2O} and units through \pu{-285.8 kJ/mol}. Prices stay text, so "$5
and $10" reads as written. A formula that doesn't parse shows its source as code, copying a formula copies its LaTeX,
and find in a chat passes over formulas.
Find in a chat
Press ⌘F and type. ⏎ and ⇧⏎ step through the matches; ⌘G, ⇧⌘G and F3 do too. Folded steps that hold a match open, and so does a row such as lk-withholding-m2 finished whose reply holds one. Esc closes the bar.
Search every chat
Press ⌘K, or click the magnifier at the top of the sidebar, and type. Search finds chats by title, what was said in any chat, projects, commands and settings. The filters All, Chats, Work, Messages, Projects and Actions narrow it; ⌘[ and ⌘] step through them. A result under Messages opens its chat at that message. Work lists what the open chat started, newest first by day, then the subagents working in other chats; a result opens its page. Before you type, the chats that need you come first, under Needs you: the ones the sidebar's Needs you lists.
The side pane
⇧⌘R, or the panel button at the top right, opens the side pane beside the chat. It holds tabs: Changes and Files in a project's chat, Profile, Files and Memory in an agent's, and the agent's browser when it opens a page. + (⌘T) opens another (type a path there to open that file), ⇧⌘[ and ⇧⌘] step through them, and a tab's ×, a middle click or ⇧⌘W closes it; with every tab closed, the pane offers one of each kind. Tabs narrow as more open; the ones that no longer fit wait in the menu beside +, where each shows or closes. Expand (⇧⌘M) lays the pane over the whole window with the chat as its first tab. Each chat keeps its own tabs.
A terminal in the chat's folder
+, then Terminal, or ⌃`, opens your own login shell in a tab of the side pane, in the chat's folder: a project's folder or the chat's worktree, an agent's own folder in an agent's chat. It starts as you, with your shell's profile and nothing of Lookout's: no agent's secrets, no session. Its tab is named after the program running in it. Open as many as you need, up to 12 at once. A terminal keeps running while you look at another chat or close the pane, so a dev server you started stays up. Closing its tab ends its shell and what that shell runs; quitting Lookout ends every terminal. One that ended says so, with New terminal to start another in its place.
The terminal is yours alone. No agent sees what it shows or what you type, and no chat, log or file keeps it. Only the app's own window reaches it: a chat on another machine, the lookout command and other apps have none.
Browse the project's files
Press ⇧⌘R to open the side pane and choose Files. It lists the chat's folder as a tree, without files and folders whose names start with a dot, and without the paths your ignore files leave out (Keep the agent out of files). Click a file to preview it: images, video and audio show in place, Markdown shows rendered (Source shows its text), and code shows with line numbers. The preview follows the file as the agent changes it. A folder shows its first 2,000 items and says so when it holds more; a linked file opens from where it points, and a linked folder outside the chat's folder says so instead of listing it. In a chat with an agent, Files lists the agent's own folder instead.
Add lines to a message
Select lines in the side pane's Changes diff, in a file's preview in Files, or in the code of a file the agent read, and click Add to chat under them (over them when there's no room below), or press ⌘L. Or point at a line and click the + over its number; on a change's header, + adds the whole change. The message box gets a pill at its caret, such as src/cart/total.ts:12-18.
Organize the sidebar
Right-click a chat, or press ⇧F10 on it, for its actions: Rename (F2, or double-click the chat), Pin, Highlight, Mark read or Mark unread, Move to its own project (a chat working in a checkout of another project's repository), Move to another project, Copy path, Copy ID, Export, Archive, Archive all below and Delete chat (⌘⌫).
Right-click a project for New chat, Mark all as read, Edit icon, Copy path, Connectors and skills, Move up, Move down, Project settings and Remove project. Mark all as read clears the unread dot on every chat in the project, including ones past N more and a folded project's dot. It is unavailable when no chat in the project is unread. Removing a project deletes its chats from Lookout and keeps its folder on disk.
The sidebar shows one of two trees at a time, Agents or Projects: pick one in the switch at the top of the
sidebar, or press ⌥⌘1 or ⌥⌘2. The one you don't see shows a mark after its name when something there waits on you,
finished unread or is working; rest the pointer on it to see those chats and open one. From the keyboard, press Space on
it: ↑ and ↓ move through the chats, ⏎ opens one, Esc closes the list and leaves you on the switch. Opening a
chat, from anywhere, brings its tree forward. ⌘1 to ⌘9 open the first nine rows of the tree you see, top to bottom
(on Agents the pinned agents first, an agent's row opening its chat), and ⌥↑ and ⌥↓ open the row above or below the
open chat's, passing over an agent whose machine is offline. On Agents, a chat of an agent's that has no row of its own
counts from its agent's row.
Projects actions, the ⋯ at the end of the switch's row while Projects shows, has Open folder and then:
A folded project shows the most urgent mark of its chats in place of the time of its latest chat. Both count only the chats the project lists when you unfold it: an archived chat, or one Started by me leaves out, never marks it, and reopening its folder or changing its settings doesn't move its time. A chat past N more that runs, waits on you, failed or finished unread stays listed above N more.
A chat waits on you, and its dot says Needs you, only while a question card it asked waits for your answer in the composer (a launch of more subagents than your allowance asks this way too). A reply that just ends on a question is not waiting: like any finished turn it shows the unread dot until you read it.
A chat whose subagent waits for a spent plan to reset keeps its working mark in the sidebar, the subagent under it too, and the subagent's row in the chat says until when on a hollow ring. It needs nothing from you: the subagent goes on by itself. So does a chat another app started with a wait for its plan (MCP tools): the mark stays until the reset, then the turn goes on. A chat whose turn stopped because the plan ran out, or because the provider kept limiting requests past Lookout's retries, shows the same mark, as its stop row reads as a wait; the red alert is for a turn that failed. Unlike a waiting subagent, that turn doesn't go on by itself, so the chat stays under Needs you until you read it, the way an unread dot clears: open the chat, or choose Mark read in its menu. The chat itself still says the turn failed and offers its retry, and a later failure brings the mark back.
A chat whose own turn has ended while its subagents still work keeps its working mark, and they show under its row, three at first, then how many more are working, a row that lists the rest in place. A chat that started other chats says Waiting on 3 chats while they work. Stop all work in a chat's actions stops its turn, its subagents and the chats it started that still work.
A chat another app started whose turn only waits on its own work (a long command, a pause, a subagent) for more than 20 seconds keeps its working mark, and says what it waits on under its last step: it doesn't count against the machine's limits while it waits. When the wait ends it goes on by itself, once there is room again (Waiting to go on names the limit until then). It lists under Running.
Hover a chat another app or an agent started to see who, and its lane key. An open one started by another app names it in its top bar, after the project; one another chat or an agent started leads its top bar with that chat, a click away.
A title too long for its row takes the room of the chat's time, which the chat's hover card shows instead.
Archive a chat
Press ⇧⌘E, or choose Archive from the chat's actions. The chat leaves the sidebar.
If the chat has its own worktree, Lookout asks whether to remove it too. Remove if safe removes its folder and its branch when nothing in the folder is uncommitted. Commits not merged into your branch yet are kept in the repository first, under a ref of the chat's own, and the folder comes back on them when you use the chat again. With uncommitted work the chat archives anyway and Lookout says why the worktree stayed, then checks it again every hour and removes it once that is safe. Keep it leaves the worktree as it is, and the hourly check leaves it too. An archive you didn't make (an agent's, another app's, or Archive idle chats) removes a worktree by the same rule without asking (Remove a worktree).
Archived chats are in Settings › Archive: search them, select some, then Restore or Delete forever. Keep archived chats is Forever by default; with 90 days or 30 days, a chat archived longer than that is deleted for good, with the files only it used. Chats whose folder is gone decides a chat whose project folder was moved or deleted: Keep, the default, keeps it until you delete it; Purge with the others deletes it past the limit too, and a project whose folders are all gone goes with its last chat, unless its folder still holds memory files. A restored chat keeps its messages and its subagents' transcripts, but its subagents can no longer be continued (Continue a subagent).
Archiving puts the chat's work away: a turn it is running stops, and so do its subagents and the commands it left running or watches. While it is archived nothing starts it again: a command that ends, a line it watched for or another chat's news waits. A message or a retry you send to it brings it back to the sidebar and runs. One an agent or another chat sends brings it back only when Lookout or an agent archived it, not when you did.
To archive idle chats on a schedule, open the project's Project settings and set Archive idle chats. Pinned chats stay put, and so does a chat with anything still running, until it ends.
Export a chat
Choose Export from the chat's actions. Lookout saves a .zip of the whole chat: every message and tool result, the changes it made to files, its usage, its images, plans and subagent runs, and a README that says what is where. The export holds file contents and command output from your project.
Delete a chat
Press ⌘⌫ on the chat in the sidebar, or choose Delete chat from its actions, then confirm. The chat and its history are deleted, and files in the project stay as they are. If the chat has its own worktree, Lookout asks whether to remove it too: Remove if safe follows the archive's rule and keeps the chat when the worktree isn't safe to remove, saying why; Keep it deletes the chat and leaves the worktree.