Troubleshooting

Find what you see in the table. If nothing matches, run the doctor. If you still need help, send a report.

Find your symptom

Run the doctor

lookout doctor checks what chats on a machine need: a signed-in provider, git and its identity, access to each project's remote, the commands projects require, the shell environment, capacity, disk and the sign-in to your account.

lookout doctor

The first line says ready, or how many problems it found. A line per check follows, then each problem on a line starting with !, with its fix:

vps-1: 1 problem
  Git        2.43.0; identity none; credentials github.com
  ! git has no identity, so commits fail: lookout git setup --name NAME --email EMAIL.

It exits with 1 when it finds a problem. --on vps-1 checks another machine, and --json prints the report as JSON. The JSON report ends with recent: the last 24 hours on that machine, grouped by the Lookout version that ran them. It counts how turns ended, errors by code, provider and account id, failed background passes and Task runs, declined requests and the ones another model answered, and how often the server stalled. Its hangs list the last five times the server stopped answering for 10 seconds or more: what it was in, how long it lasted, and whether it came back or was restarted. Its chats with the most unfinished turns list each kind's last two with what came after: the next turn's cause, how long it took and onto which model, or how long the chat has waited. Its rounds split each model's request time by phase: queued, waiting for headers, prefill, thinking, writing, failed tries and the waits between them. It names accounts and chats by id only. The doctor comes with the lookout command: to check a Mac that has only the app, run lookout doctor --on with the Mac's name from another machine of your account.

After the problems, lines starting with - are notices, which don't count as problems: the chats active in the last 24 hours whose memory index is over about 8,000 tokens, or whose deferred tool listing (the large connectors' tools, kept out of the tool list) is over 2 KB, each with its size. Both go with every request those chats send.

A Mac that slows down with plenty of memory in use

The doctor's Host line shows the swap in use, Lookout's own memory, the processes holding the most memory outside it (every user's, macOS's own services included) and the scratch root. A macOS service that should hold a few megabytes sometimes grows without end until it is restarted: fseventsd, which tracks file changes, once held 13 GB of a 16 GB Mac. When fseventsd, Spotlight's mds or mds_stores, or mdworker_shared holds more than 1 GB, the doctor lists it as a problem with the one command that restarts it, such as:

  ! fseventsd (pid 1830, root) holds 13.0 GB, a runaway that grows until it is restarted. Restart it: sudo kill -9 1830 (launchd starts it again at once; apps that watch files may need a restart to watch again).

Run that command yourself in Terminal: it asks for your password, and Lookout never runs it for you. sudo killall fseventsd is not enough. macOS starts the service again at once, so no restart of the Mac is needed. Another of macOS's services past 1 GB shows as a notice with no command.

What a chat sends with every request

lookout doctor --head CHAT shows a chat's newest head part by part: what goes to the model before the conversation, every request. CHAT is the chat's id or its first characters.

3f2a91c0-5d7e-4b8a-9c11-0e6f2d4b7a85 (claude-opus-5-5): head 97,434 bytes, 24,367 tokens (estimated, bytes / 4), as of 2026-10-21T12:41:58.066Z
                   bytes  tokens  share
  system prompt    5,001   1,251     5%
  rules           21,834   5,459    22%
    user             484     121     0%
    project       21,346   5,337    22%
  tools           28,293   7,080    29%
  environment     42,306  10,577    43%
    skills         2,758     690     3%
    memory        38,344   9,586    39%

Rules are your own rules and the project's. Tools split into Lookout's, each connector's and the deferred listing. The environment splits into the user info, the skills list, each memory index and the rest. Bytes are exact; tokens are estimated as bytes / 4, so a model's own count differs by a tenth or so. --json prints the same parts, and --on reads a chat on another machine.

lookout status says whether this machine is signed in and how your other devices see it.

The agent can't find a command

The agent's commands run with the environment your login shell sets up, which Lookout reads once, when it starts. After you install a tool:

1. Restart Lookout: quit the Mac app and open it again. On a server, restart the service as Set up git and tools on a server shows.
2. Run lookout doctor. Its Shell env line names your login shell and the folders it added to PATH.

If the doctor says the login shell gave no environment, your shell's startup files failed: fix them, then restart Lookout.

The browser isn't signed in

You opened Lookout in a browser and the page says This browser isn't signed in to this Lookout, while the server is running. The page on its own holds nothing: a browser gets in with a one time link, and this browser has not opened one yet, or its sign in is gone.

On the machine running Lookout, run:

lookout link

Open the link it prints in this browser. The link works once, for 10 minutes. The Mac app never needs it: its window is signed in already.

macOS says Lookout is damaged

You open the Mac app and macOS says Lookout is damaged and can't be opened. Lookout is not damaged: the app is not notarized yet, so macOS refuses apps it downloaded until you say this one is fine. Run this once in Terminal, then open Lookout again:

xattr -cr /Applications/Lookout.app

Find the logs

In the Mac app, choose Help › Show Logs in Finder. On a Linux server, run journalctl --user -u lookout -f as the user Lookout runs as. Files and folders lists every log.

Each line of the Mac app's server.log starts with the time it was written, and each start of the server adds a line naming its version. Past 20 MB the log moves to server.log.1 when the server next starts, so the two files hold the recent history.

Collect a report

When you ask for help, say what you did, what you expected and what happened, and send these three:

1. The chat: right-click it in the sidebar and choose Export. Lookout saves it as a .zip.
2. The logs: in the Mac app, Help › Show Logs in Finder, then server.log, update.log and renderer.jsonl. On a server, the service's log (see Find the logs).
3. The doctor's report: lookout doctor --json > doctor.json on the machine the chat ran on, or with --on and that machine's name from another one.

Email the report to:

[email protected]

The same address takes questions and feedback. In the Mac app, Help › Send Feedback starts the mail with the app's version in the subject; lookout --help ends with the address.