agent-lookout 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Changes that a user of Agent Lookout would notice, newest first.
 
+## 0.2.7 - 2026-10-07
+
+Remind again every few minutes while a session keeps waiting, and read a README rewritten for people and coding agents.
+
+### Added
+
+- Remind again while it waits, under Remind me of a long wait in Time rules. Turn it on, and a session that still waits is reminded of again each time the minutes you set pass, 30 unless you change them, from 5 to 1,440: with a reminder after 10 minutes and again every 30, at 10 minutes, 40 minutes, 1 hour 10 minutes and so on. Each goes by the same channels as the first, as a notification, an email and a webhook post, and says how long the session has waited by then, as in "checkout-flow has waited 40 minutes for permission". None comes once the wait is answered or the session ends. Quiet hours hold them like any notice: a wait still open when they end is told of once, and one answered in them is one item of the summary, however many came due. After the computer has slept, one comes, not one for each interval missed. It is off until you turn it on. [Time rules](docs/GUIDE.md#time-rules) has the details.
+- A webhook post for a repeat has `repeat` beside `reminder: true`. It counts the intervals since the first reminder's time, so after a sleep it can skip numbers. `longWait` in `GET /api/settings`, in `POST /api/settings/time-rules` and in each snapshot's `timeRules` can have `repeat`, as `{ "on", "minutes" }`. A settings file without it reads as before, with no repeat.
+
+### Changed
+
+- The README is rewritten for people and for coding agents, with install three ways and a prompt to hand an agent, and a new install guide, [docs/INSTALL.md](docs/INSTALL.md), takes the details.
+- About sources, in Sources, now names every way Agent Lookout can send something off this computer: email, the webhook, pull requests through your own `gh`, other machines through your own `ssh`, and the Mac app's daily check for a newer version.
+- A long wait reminder that falls due in quiet hours, for a session told of before they began, now holds its wait as any notice is held: if the wait is answered before they end, it is an item of the summary. Before, it was left out.
+
 ## 0.2.6 - 2026-10-07
 
 Set rules that answer Claude Code's permission prompts for you, run Agent Lookout on Windows, and see a prompt you answered leave Needs you at once.

package/PRIVACY.md

@@ -290,7 +290,7 @@ It holds none of Claude Code's own wording and no tag. As in the page's, what a
 
 ### Reminders and summaries
 
-With the [time rules](docs/GUIDE.md#time-rules) on, the page and the server make two more kinds of notification, in the same two ways and by the same switches. A reminder of a long wait has the session's name as its title, with the machine's name for a session on another machine, and as its text how long it has waited and for what, with what it is asking after it, as in "Has waited 10 minutes for permission: Run: npm test". On the page it takes the place of the wait's own, with its tag. The summary made when quiet hours end has "While quiet" as its title, and as its text the names of the sessions that waited, finished, failed or ended while they held, each with the machine's name for a session on another machine, with how long each waited, as in "checkout-flow waited 25 minutes and billing-webhooks finished". It holds nothing a session was asking. The page's has the tag `agent-lookout:while-quiet`, and stays until you clear it. During quiet hours neither the page nor the server makes any notification.
+With the [time rules](docs/GUIDE.md#time-rules) on, the page and the server make two more kinds of notification, in the same two ways and by the same switches. A reminder of a long wait has the session's name as its title, with the machine's name for a session on another machine, and as its text how long it has waited and for what, with what it is asking after it, as in "Has waited 10 minutes for permission: Run: npm test". On the page it takes the place of the wait's own, with its tag. With Remind again on, the same reminder is made again at each interval while the session still waits, with how long it has waited by then, on the page each taking the place of the last, and none once the wait is answered or the session ends. The summary made when quiet hours end has "While quiet" as its title, and as its text the names of the sessions that waited, finished, failed or ended while they held, each with the machine's name for a session on another machine, with how long each waited, as in "checkout-flow waited 25 minutes and billing-webhooks finished". It holds nothing a session was asking. The page's has the tag `agent-lookout:while-quiet`, and stays until you clear it. During quiet hours neither the page nor the server makes any notification.
 
 The server shows them only while notifications are on, and only for the events switched on, and it learns both from the dashboard. Each request a dashboard page makes says, in the `X-Agent-Lookout-Notifications` header, which events are on when that page's choice is on and the browser allows notifications, and `off` otherwise. The server keeps the last thing a page said, in memory, for as long as it runs, and never writes it to disk. Before any page has said anything it is off, unless `AGENT_LOOKOUT_NOTIFICATIONS=on` was set when Agent Lookout started, which turns it on for a session starting to wait. A page that says `off` after that turns it off all the same. The header is listened to only on a request that passes the checks described under [Network](#network), so a page at another address cannot set it.
 
@@ -317,7 +317,7 @@ An email is plain text. Its subject is the session's name followed by the reason
 - the agent, such as Claude Code or Codex, or the agent a status file names
 - one line saying Agent Lookout sent it and how to stop these emails
 
-With the [time rules](docs/GUIDE.md#time-rules) on, two more kinds of email can be sent. A reminder of a long wait is the email of a wait with a subject that says how long it has waited, such as "checkout-flow has waited 10 minutes for permission", and a line on how often reminders come. The summary sent when quiet hours end has the subject "While quiet:" followed by the first few sessions' names and what happened, and in its body, one line for each session that waited, finished, failed or ended while they held, with how long it waited and from when, or when it finished, failed or ended, at most 50, and a line on where quiet hours are set. A summary holds the sessions' names alone, nothing of what they were asking and no folder.
+With the [time rules](docs/GUIDE.md#time-rules) on, two more kinds of email can be sent. A reminder of a long wait is the email of a wait with a subject that says how long it has waited, such as "checkout-flow has waited 10 minutes for permission", and a line on how often reminders come. With Remind again on, the same email goes again at each interval while the session still waits, saying how long by then, and holds nothing more than the first. The summary sent when quiet hours end has the subject "While quiet:" followed by the first few sessions' names and what happened, and in its body, one line for each session that waited, finished, failed or ended while they held, with how long it waited and from when, or when it finished, failed or ended, at most 50, and a line on where quiet hours are set. A summary holds the sessions' names alone, nothing of what they were asking and no folder.
 
 It holds no folder path, no prompt, none of Claude Code's own wording for the wait, no link, no image, nothing that reports back when it is opened and, unless you set `AGENT_LOOKOUT_EMAIL_ASKING=on` (below), nothing of what a waiting session is asking. Its headers are the ones the mail library writes for every email: From, with the name Agent Lookout and the sender's address, To, Subject, Date, Message-ID, and three that say it is plain text in UTF-8. A session's name and its folder's name are cut to 80 characters, and anything in them that would end a line becomes a space, so nothing in a name can add a header or a recipient.
 
@@ -340,7 +340,7 @@ For each email Agent Lookout looks up the server's name, opens a connection to i
 
 ### When
 
-`AGENT_LOOKOUT_EMAIL_EVENTS` names the events that are emailed, from `needs-you`, `finished`, `failed` and `ended`, and is `needs-you` alone unless you set it. An email is sent for a wait that begins after Agent Lookout started, once it has lasted the delay, which is one minute unless `AGENT_LOOKOUT_EMAIL_AFTER` says otherwise, if the session is still waiting then. A wait answered before then sends nothing, and so does a session that was already waiting when Agent Lookout started. Each wait sends one email at most, apart from reminders. With the long wait reminder on, a wait is also reminded of once it has waited the rule's minutes, unless its email went only after that. That includes a wait already open when Agent Lookout started, if it had not waited that long yet. Each change to the minutes while it waits can bring one more, once it has waited the new number. With the others set, an email is sent as soon as a session is seen to finish, fail or end, and none for a session that had already finished or failed when Agent Lookout started. An email that could not be sent is not tried again. At most 20 are sent in any hour, whatever they are for. Past that, none goes until the hour has passed. Claude Code sessions and sessions from a status file can be seen waiting; a Codex session never can, so it never sends one for a wait.
+`AGENT_LOOKOUT_EMAIL_EVENTS` names the events that are emailed, from `needs-you`, `finished`, `failed` and `ended`, and is `needs-you` alone unless you set it. An email is sent for a wait that begins after Agent Lookout started, once it has lasted the delay, which is one minute unless `AGENT_LOOKOUT_EMAIL_AFTER` says otherwise, if the session is still waiting then. A wait answered before then sends nothing, and so does a session that was already waiting when Agent Lookout started. Each wait sends one email at most, apart from reminders. With the long wait reminder on, a wait is also reminded of once it has waited the rule's minutes, unless its email went only after that. That includes a wait already open when Agent Lookout started, if it had not waited that long yet. Each change to the minutes while it waits can bring one more, once it has waited the new number. With Remind again on, a wait still open is reminded of again each time the interval passes after that, and never once the wait is answered or the session ends. After the computer has slept, or when quiet hours end, one email goes, not one for each interval missed. A wait already past the minutes when Agent Lookout started is reminded of at the next interval. With the others set, an email is sent as soon as a session is seen to finish, fail or end, and none for a session that had already finished or failed when Agent Lookout started. An email that could not be sent is not tried again. At most 20 are sent in any hour, whatever they are for. Past that, none goes until the hour has passed. Claude Code sessions and sessions from a status file can be seen waiting; a Codex session never can, so it never sends one for a wait.
 
 The button and the switches for notifications in Settings do not turn emails on or off, or choose what is emailed. To stop them, start Agent Lookout again without `AGENT_LOOKOUT_EMAIL_TO`.
 
@@ -385,7 +385,7 @@ It holds:
 - `at`: when it happened, as a time in UTC: when the wait began, or when Agent Lookout saw the session finish, fail or end.
 - `waitedSeconds`, for a wait only: how long it had waited when it was posted.
 
-With the [time rules](docs/GUIDE.md#time-rules) on, two more kinds of post can be sent. A reminder of a long wait is the post of a wait, with the line saying how long it has waited, such as "checkout-flow has waited 10 minutes for permission", and one more field, `"reminder": true`. The summary sent when quiet hours end looks like this:
+With the [time rules](docs/GUIDE.md#time-rules) on, two more kinds of post can be sent. A reminder of a long wait is the post of a wait, with the line saying how long it has waited, such as "checkout-flow has waited 10 minutes for permission", and one more field, `"reminder": true`. With Remind again on, the same post goes again at each interval while the session still waits, saying how long by then, with one field more, `"repeat"`, a count of the intervals since the first reminder's time, which can skip numbers after a sleep. The summary sent when quiet hours end looks like this:
 
 ```json
 {
@@ -443,7 +443,7 @@ Each post goes to the one address in `AGENT_LOOKOUT_WEBHOOK_URL`, and to no othe
 
 ### When
 
-`AGENT_LOOKOUT_WEBHOOK_EVENTS` names the events that are posted, from `needs-you`, `finished`, `failed` and `ended`, and is `needs-you` alone unless you set it. A post goes for a wait that begins after Agent Lookout started, once it has lasted the delay, which is one minute unless `AGENT_LOOKOUT_WEBHOOK_AFTER` says otherwise, if the session is still waiting then. A wait answered before then sends nothing, and so does a session that was already waiting when Agent Lookout started. Each wait sends one post at most, apart from reminders. With the long wait reminder on, a wait is also reminded of once it has waited the rule's minutes, unless its post went only after that. That includes a wait already open when Agent Lookout started, if it had not waited that long yet. Each change to the minutes while it waits can bring one more, once it has waited the new number. With the others set, a post goes as soon as a session is seen to finish, fail or end, and none for a session that had already finished or failed when Agent Lookout started. A post that could not be sent is not tried again. At most 20 posts are tried in any hour, whatever they are for, counted apart from emails. Past that, none goes until the hour has passed. These are the rules emails follow, and the two share one copy of them.
+`AGENT_LOOKOUT_WEBHOOK_EVENTS` names the events that are posted, from `needs-you`, `finished`, `failed` and `ended`, and is `needs-you` alone unless you set it. A post goes for a wait that begins after Agent Lookout started, once it has lasted the delay, which is one minute unless `AGENT_LOOKOUT_WEBHOOK_AFTER` says otherwise, if the session is still waiting then. A wait answered before then sends nothing, and so does a session that was already waiting when Agent Lookout started. Each wait sends one post at most, apart from reminders. With the long wait reminder on, a wait is also reminded of once it has waited the rule's minutes, unless its post went only after that. That includes a wait already open when Agent Lookout started, if it had not waited that long yet. Each change to the minutes while it waits can bring one more, once it has waited the new number. With Remind again on, a wait still open is reminded of again each time the interval passes after that, and never once the wait is answered or the session ends. After the computer has slept, or when quiet hours end, one post goes, not one for each interval missed. A wait already past the minutes when Agent Lookout started is reminded of at the next interval. With the others set, a post goes as soon as a session is seen to finish, fail or end, and none for a session that had already finished or failed when Agent Lookout started. A post that could not be sent is not tried again. At most 20 posts are tried in any hour, whatever they are for, counted apart from emails. Past that, none goes until the hour has passed. These are the rules emails follow, and the two share one copy of them.
 
 The button and the switches for notifications in Settings do not turn posts on or off, or choose what is posted. To stop them, start Agent Lookout again without `AGENT_LOOKOUT_WEBHOOK_URL`.
 
@@ -539,7 +539,7 @@ To keep nothing on disk, start Agent Lookout with `AGENT_LOOKOUT_HISTORY=off`. I
 
 ### The settings file
 
-Agent Lookout keeps the [time rules](docs/GUIDE.md#time-rules) and the [permission rules](docs/GUIDE.md#permission-rules) you set in Settings in `~/.agent-lookout/settings.json`, beside the history, or in the file `AGENT_LOOKOUT_SETTINGS_FILE` names, so they hold with no dashboard open and after a restart. It holds those rules and nothing else of Agent Lookout's: whether each time rule is on, the minutes before a reminder, the hours before a session is stale, and the times and days of quiet hours with the switch for the summary, and each permission rule in its order, with an ID Agent Lookout gave it, its decision, its tool and, for Bash, the command you wrote. It holds nothing about a session. A command you write in a rule is in the file as you wrote it, so leave out of a rule anything you would not keep in a file.
+Agent Lookout keeps the [time rules](docs/GUIDE.md#time-rules) and the [permission rules](docs/GUIDE.md#permission-rules) you set in Settings in `~/.agent-lookout/settings.json`, beside the history, or in the file `AGENT_LOOKOUT_SETTINGS_FILE` names, so they hold with no dashboard open and after a restart. It holds those rules and nothing else of Agent Lookout's: whether each time rule is on, the minutes before a reminder and, once you set it, whether it goes again and the minutes between, the hours before a session is stale, and the times and days of quiet hours with the switch for the summary, and each permission rule in its order, with an ID Agent Lookout gave it, its decision, its tool and, for Bash, the command you wrote. It holds nothing about a session. A command you write in a rule is in the file as you wrote it, so leave out of a rule anything you would not keep in a file.
 
 Agent Lookout reads it as it starts and again just before each change, and at each poll, every 2 seconds, it looks at the file's size and times to read it again when another copy of Agent Lookout, such as the Mac app beside `npx agent-lookout`, has written it. It writes it only when you change a rule in Settings, through `POST /api/settings/time-rules` or `POST /api/settings/permission-rules`, which the dashboard's page sends, and which another program on this computer can send too, as [Network](#network) says. It writes the file whole: to a new file of mode 600, so only your user can read or change it, in the same folder, which then takes the old one's place, and makes the folder with mode 700 when it is not there. It neither reads nor writes through a link, at the file's name or the folder's, and reads no file larger than 64 KB. Anything else the file holds, such as a later version's settings, is written back as it was. A file it finds but cannot read, such as one larger than 64 KB or one it may not read, it never writes over: a change is not saved until the file is mended or removed. Permission rules it cannot read whole, such as a later version's, are no rule at all: none of them answers anything, Settings says so, and they stay in the file as they were until you change a permission rule, which writes the list again with the rules Settings shows. Until you change a rule, nothing is written and no folder is made. To go back to every time rule off and no permission rule, delete the file while Agent Lookout is stopped.
 

package/README.md

@@ -1,133 +1,67 @@
 # Agent Lookout
 
-Agent Lookout shows the AI agent sessions on your Mac, Linux or Windows computer in one browser page, and which need you.
+Shows the AI agent sessions on your computer in one browser page, and which need you.
 
-It finds Claude Code and Codex sessions with no setup, and the sessions of any other agent that writes a small status file. It never starts a session. It stops one only when you press Stop and confirm, and answers a Claude Code permission prompt only when you press Allow or Deny, or by a permission rule you set, with its Claude Code plugin installed: it never acts on its own. By default Agent Lookout itself sends nothing anywhere. Start it with `npx agent-lookout`, or download the [Mac app](#mac-app).
+[![npm](https://img.shields.io/npm/v/agent-lookout)](https://www.npmjs.com/package/agent-lookout) [![CI](https://img.shields.io/github/actions/workflow/status/Olanetsoft/agent-lookout/ci.yml?branch=main&label=CI)](https://github.com/Olanetsoft/agent-lookout/actions/workflows/ci.yml) [![License](https://img.shields.io/npm/l/agent-lookout)](LICENSE) ![Node.js](https://img.shields.io/node/v/agent-lookout)
 
-[Install](#install) · [Guide](docs/GUIDE.md) · [Privacy](#privacy) · [Roadmap](https://github.com/Olanetsoft/agent-lookout/milestones) · [Website](https://agent-lookout.vercel.app)
+It finds Claude Code and Codex sessions with no setup, and any agent that writes a status file. It never starts a session, stops one only when you press Stop and confirm, and answers a permission prompt only on Allow, Deny or a rule you added.
+
+By default Agent Lookout sends nothing anywhere. The one exception: the Mac app's daily check on GitHub for a newer version, which Settings turns off. Email, a webhook, pull requests through your `gh` and other machines over your `ssh` stay off until you set them up. [Privacy](#privacy)
+
+[Install](#install) · [Download for Mac](https://github.com/Olanetsoft/agent-lookout/releases/latest) · [Guide](docs/GUIDE.md) · [Privacy](#privacy) · [Changelog](CHANGELOG.md) · [For agents](#for-coding-agents) · [Roadmap](https://github.com/Olanetsoft/agent-lookout/milestones) · [Website](https://agent-lookout.vercel.app)
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Olanetsoft/agent-lookout/main/docs/images/dashboard-day.png">
-  <img alt="The Overview. One session waits for permission in the Needs you panel, beside the Last hour chart. Below are the Sessions list, Events and Timeline." src="https://raw.githubusercontent.com/Olanetsoft/agent-lookout/main/docs/images/dashboard-night.png">
+  <img alt="The Overview. In the Needs you panel, checkout-flow has waited over 4 minutes for permission, with a Jump button, above bars of how long sessions waited and counts of working, idle and stale sessions. The Last hour chart is beside it. Below are the Sessions list, the Events log and the Timeline." src="https://raw.githubusercontent.com/Olanetsoft/agent-lookout/main/docs/images/dashboard-night.png">
 </picture>
 
-## What it does
-
-| Part                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Needs you](docs/GUIDE.md#needs-you)                              | Lists the sessions waiting for permission or for an answer, longest wait first, each with a timer. For Claude Code it also says what the session is asking, such as `Run: npm test`.                                                                                                                                                                                                                                                                                                                                                                                |
-| [Sessions](docs/GUIDE.md#sessions)                                | Lists the other sessions by status, by repository or on a board, each with its folder and git branch. Click one to see its details.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| [Jump](docs/GUIDE.md#jump)                                        | Takes you to a Claude Code session. It opens it in VS Code, selects its tmux pane, or on a Mac brings its Terminal or iTerm2 tab to the front.                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| [Stop](docs/GUIDE.md#stop-a-session)                              | Ends a Claude Code session's process when you press Stop in its details and confirm. The conversation is kept. Sessions left running, idle for a day or more, can be ended together after a confirmation.                                                                                                                                                                                                                                                                                                                                                           |
-| [Resume](docs/GUIDE.md#resume-a-session)                          | Copies the command that continues a Claude Code session that has ended, `cd` to its folder and `claude --resume` with its ID, for you to run in a terminal. It runs nothing itself.                                                                                                                                                                                                                                                                                                                                                                                 |
-| [Allow and Deny](docs/GUIDE.md#answer-a-permission-prompt)        | Answers a Claude Code permission prompt from the dashboard, with the Agent Lookout plugin installed in Claude Code. It shows the whole command first, and the prompt in the session still works.                                                                                                                                                                                                                                                                                                                                                                    |
-| [Permission rules](docs/GUIDE.md#permission-rules)                | Decide once how a Claude Code permission prompt is answered: always allow, always ask or always deny, by tool and, for Bash, by command, such as `npm test:*`. An allow rule answers only one plain command you could allow by hand, and never one that begins with `sudo`, `env`, `sh`, `bash` or another program on [the list](docs/GUIDE.md#permission-rules) that runs a command. A rule for a package manager names its subcommand, such as `npm test:*`, and a prefix trusts every word after it. The Events log records each answer. None until you add one. |
-| [Notifications](docs/GUIDE.md#notifications)                      | Tell you when a session starts waiting and, if you choose, when one finishes, fails or ends. Off until you turn them on. On a Mac they keep coming after you close the tab, once a page with them on has been open.                                                                                                                                                                                                                                                                                                                                                 |
-| [Time rules](docs/GUIDE.md#time-rules)                            | Remind you of a long wait, set how long a session is idle before it is stale, and hold everything back during quiet hours, with one summary when they end. Off until you turn them on.                                                                                                                                                                                                                                                                                                                                                                              |
-| [Pull requests](docs/GUIDE.md#pull-requests)                      | Shows a session's pull request on github.com and its checks, through your own `gh`, and marks a branch whose checks are failing. Off until you turn it on.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| [Email](docs/GUIDE.md#email) and [webhook](docs/GUIDE.md#webhook) | Send the same events to one email address, or to one webhook such as a Slack channel's, for when you are away. Off until you set them up.                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| [`agent-lookout status`](docs/GUIDE.md#in-the-terminal)           | Prints which sessions need you, for a terminal, a tmux status line or a script.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| [`agent-lookout mcp`](docs/GUIDE.md#for-your-agents)              | Lets an AI agent ask which sessions need you. Its tools only read.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| [Status files](docs/GUIDE.md#your-own-agents)                     | Show any other agent, including one you wrote, when it writes one small JSON file for each session.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-
-The Overview also has a chart of the last hour, a log of events, a timeline, and how long sessions waited on you today and over the last 7 days, day by day, with the sessions that waited longest. What they show is kept on this computer for 8 days, so a restart does not empty them. Press `/` to search every session. Sources says what Agent Lookout reads for each agent. [The screen](docs/GUIDE.md#the-screen) covers each part.
-
-## Supported agents and systems
-
-| Agent           | Setup                                                    | How it finds sessions                                                                                                                  | Shows when it needs you      | Jump                                                         |
-| --------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------ |
-| Claude Code     | None                                                     | Reads `~/.claude/sessions` every 2 seconds, runs `claude agents` every 30 seconds, and reads the end of a waiting session's transcript | Yes                          | In VS Code, in tmux, or in a Terminal or iTerm2 tab on a Mac |
-| Codex           | None                                                     | Reads `sessions`, `thread-writer-locks` and `session_index.jsonl` in `~/.codex` every 2 seconds, and runs nothing                      | No                           | No                                                           |
-| Any other agent | It writes a [status file](docs/GUIDE.md#your-own-agents) | Reads `~/.agent-lookout/sessions` every 2 seconds                                                                                      | When its file says `waiting` | No                                                           |
-
-Claude Code sessions are found whether they run in a terminal, in VS Code or in the desktop app.
-
-A Codex session never shows as needing you. Codex's files do not record when it is waiting for your approval, so one that is waiting for you shows as working. Once it has written nothing for 5 minutes, its row says how long it has been quiet, which is the sign to look. Codex support has been checked with the Codex desktop app, and not yet with the Codex CLI or its IDE extension. [What each agent can report](docs/GUIDE.md#what-each-agent-can-report) has the full table.
-
-Agent Lookout is developed and tested on macOS. On Linux, CI runs every test and starts the app there. On Windows, it runs the tests, less those of what Windows does not have, such as POSIX signals and Unix sockets, and starts the app there. No one has used it on a Linux or Windows desktop yet. Two things are macOS only: notifications with no dashboard tab open, and Jump to a Terminal or iTerm2 tab. On Windows, Stop, Allow and Deny, the permission rules, Resume and Jump to a tmux pane are not there either. [On Linux](docs/GUIDE.md#on-linux) and [On Windows](docs/GUIDE.md#on-windows) have the rest.
+_One session has waited over 4 minutes for permission. Jump takes you to it in VS Code._
 
 ## Install
 
-### Mac app
-
-Download the disk image for your Mac from the [latest release](https://github.com/Olanetsoft/agent-lookout/releases/latest): the one that ends in `mac-arm64.dmg` for Apple silicon, or `mac-x64.dmg` for Intel. Open it and drag Agent Lookout to Applications. The app needs no Node.js.
-
-It is not signed with an Apple Developer ID yet, so the first time you open it, macOS says “Agent Lookout” Not Opened. Press Done, then open System Settings › Privacy & Security and press Open Anyway. [Desktop app](docs/GUIDE.md#desktop-app) has the steps.
-
-Its icon in the menu bar shows how many sessions need you, with the window open or closed, and a click lists them: choose one to open it.
-
-Kept in Applications, it updates itself: about once a day it asks GitHub whether a newer version is out, and installs it when you press Install and Restart. Settings turns the daily check off. The app opens no port, so `agent-lookout status` and `agent-lookout mcp` cannot reach it. For those, start it with npx as well, and turn notifications on in only one of the two, or you get each one twice.
+Start it with npx or the Mac app. Add the Claude Code plugin to either one to answer permission prompts from the page.
 
 ### With npx
 
-1. Check what you have.
-
-   ```sh
-   node --version
-   claude --version
-   claude agents --help
-   codex --version
-   ```
-
-   `node --version` prints `v22.12.0` or later. `claude --version` prints a version number followed by `(Claude Code)`, and `claude agents --help` prints a line that starts with `Usage: claude agents`. `codex --version` prints `codex-cli` followed by a version number.
-
-   You need Node.js, and Claude Code, Codex or both. A command for a program you do not use prints `command not found`: carry on. Agent Lookout never runs `codex`, so the Codex desktop app needs no CLI. Without `claude agents` the rest works, but Claude Code's finished and failed background jobs are not listed.
-
-2. Start it. It keeps running until you press Ctrl+C, so leave this terminal open.
-
-   ```sh
-   npx agent-lookout
-   ```
-
-   The first time, npm names the package and asks `Ok to proceed? (y)`. Press Enter. npm downloads under 2 MB and keeps it in its cache. Then Agent Lookout prints:
+You need Node.js 22.12 or newer, and Claude Code, Codex or both.
 
-   ```text
-   Agent Lookout is running at http://127.0.0.1:4777
-   It listens on this machine only. Press Ctrl+C to stop.
-   ```
-
-   To run it in the background instead, run `nohup npx --yes agent-lookout > agent-lookout.log 2>&1 &`. What it prints then goes to `agent-lookout.log`.
-
-   If it prints `Port 4777 is already in use`, another program has that port. Run `npx agent-lookout --port 4778` instead, and use 4778 in the next two steps. `agent-lookout status` and `agent-lookout mcp` then need `--url http://127.0.0.1:4778`, as [In the terminal](#in-the-terminal) says.
-
-3. Check that it answers. If `npx agent-lookout` holds your terminal, use a second one.
+```sh
+npx agent-lookout
+```
 
-   ```sh
-   curl -s http://127.0.0.1:4777/api/health
-   ```
+The first time, npm asks `Ok to proceed?`. Then it prints:
 
-   It prints `{"ok":true,"version":"0.2.1"}`, or a later version number.
+```text
+Agent Lookout is running at http://127.0.0.1:4777
+It listens on this machine only. Press Ctrl+C to stop.
+```
 
-4. Open <http://127.0.0.1:4777>. Your sessions appear within a few seconds. If none do, see [No sessions appear](docs/GUIDE.md#no-sessions-appear). If you used `npm run dev` before, turn notifications on again here: the browser keeps them for each address. To update later, run `npx agent-lookout@latest`, which also makes sure npx does not reuse an older copy it keeps.
+Open http://127.0.0.1:4777. Your sessions appear within a few seconds. To check it from another terminal:
 
-If a step prints something else, [When something goes wrong](docs/GUIDE.md#when-something-goes-wrong) says what to do for the common problems.
+```sh
+curl -s http://127.0.0.1:4777/api/health
+```
 
-To stop it, press Ctrl+C in its terminal. If it runs in the background, `lsof -nP -iTCP:4777 -sTCP:LISTEN` shows its process ID under `PID`, on macOS or on Linux with `lsof` installed. Put your port in place of 4777 if you chose another. `kill` followed by that number stops it. On Windows, `netstat -ano | findstr :4777` shows the process ID in its last column, and `taskkill /F /PID` followed by that number stops it.
+It prints `{"ok":true,"version":"…"}`. If the port is in use, add `--port 4778`. If nothing appears, see [No sessions appear](docs/GUIDE.md#no-sessions-appear). [With npx](docs/INSTALL.md#with-npx) covers running it in the background, stopping it, updating it and a global install.
 
-To start it again, run `npx agent-lookout`. `npx agent-lookout --open` also opens the page in your browser, and `--port` chooses another port. [Start it with one command](docs/GUIDE.md#start-it-with-one-command) has the options.
+### Mac app
 
-Each time, npx asks npm's registry whether a newer version is out, as it does for any package it runs. To start it without that, install it once and run it by name:
+Download `Agent-Lookout-<version>-mac-arm64.dmg` for Apple silicon, or `Agent-Lookout-<version>-mac-x64.dmg` for Intel, from the [latest release](https://github.com/Olanetsoft/agent-lookout/releases/latest), open it and drag Agent Lookout to Applications. It needs no Node.js. It is not signed with an Apple Developer ID yet, so the first time you open it, go to System Settings › Privacy & Security and press Open Anyway.
 
-```sh
-npm install -g agent-lookout
-agent-lookout
-```
+Its icon in the menu bar shows how many sessions need you. It checks for a newer version about once a day and installs it when you press Install and Restart. [Mac app](docs/INSTALL.md#mac-app) has the steps.
 
-### From the repository
+### Claude Code plugin
 
-To run it from a clone, as you would to work on its code:
+With Agent Lookout running, the plugin lets you press Allow or Deny on a Claude Code permission prompt from the page. In Claude Code, run:
 
-```sh
-git clone https://github.com/Olanetsoft/agent-lookout.git
-cd agent-lookout
-npm install
-npm run build
-npm start
+```text
+/plugin marketplace add Olanetsoft/agent-lookout
+/plugin install agent-lookout@agent-lookout
 ```
 
-`npm start` prints the same two lines as `npx agent-lookout`. After a `git pull`, run `npm install` and `npm run build` again. `npm run dev` starts it at <http://localhost:5173> with the development tools used to work on its code, as [CONTRIBUTING.md](CONTRIBUTING.md) describes.
+The prompt in the session still works, and whichever is answered first wins. Without Agent Lookout running, Claude Code asks as usual. Not on Windows. [plugins/agent-lookout/README.md](plugins/agent-lookout/README.md) says what the hook does, and [PRIVACY.md](PRIVACY.md#the-claude-code-plugin-and-permission-prompts) what it sends.
 
-## Install with your agent
+### Install with your agent
 
 A coding agent such as Claude Code or Codex can start it for you. Give it this prompt:
 
@@ -139,110 +73,203 @@ It should print "Agent Lookout is running at http://127.0.0.1:4777".
 If it prints anything else, or says the port is in use, stop and tell
 me what it printed.
 
-Do not use sudo, and do not set up email or a webhook. You are done
-when curl -s http://127.0.0.1:4777/api/health prints {"ok":true and a
+Do not use sudo, and do not set up email, a webhook, pull requests
+or other machines. You are done when
+curl -s http://127.0.0.1:4777/api/health prints {"ok":true and a
 version number. Tell me what it printed.
 ```
 
 An agent's background command can end when its session does. If the page then says Agent Lookout has stopped updating, run `npx agent-lookout` yourself.
 
-## In the terminal
+To run it from a clone, see [From the repository](docs/INSTALL.md#from-the-repository).
+
+## What it does
 
-`agent-lookout status` prints which sessions need you, from the Agent Lookout that is running, without opening the browser:
+| Part                                                                                                         | What it does                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [Needs you](docs/GUIDE.md#needs-you)                                                                         | Lists the sessions waiting for permission or an answer, longest first, with what a Claude Code session asks.                                     |
+| [Sessions](docs/GUIDE.md#sessions)                                                                           | Lists the rest by status, by repository or on a board, with folder and branch. `/` searches every session.                                       |
+| [Jump](docs/GUIDE.md#jump)                                                                                   | Takes you to a Claude Code session in VS Code, its tmux pane, or its Terminal or iTerm2 tab.                                                     |
+| [Stop and Resume](docs/GUIDE.md#stop-a-session)                                                              | Stop ends a Claude Code session, or those left running, after you confirm. Resume copies the command that reopens it.                            |
+| [Allow and Deny](docs/GUIDE.md#answer-a-permission-prompt)                                                   | Answers a Claude Code permission prompt from the page, with the plugin. [Rules](docs/GUIDE.md#permission-rules) you add can answer some for you. |
+| [Notifications](docs/GUIDE.md#notifications) and [time rules](docs/GUIDE.md#time-rules)                      | Tell you when a session waits, remind you of long waits and keep quiet hours. Off until turned on.                                               |
+| [Pull requests](docs/GUIDE.md#pull-requests), [email](docs/GUIDE.md#email), [webhook](docs/GUIDE.md#webhook) | Show a session's pull request on github.com and its checks, through your `gh`, and email or post events to one address. Off until set up.        |
+| [Another machine](docs/GUIDE.md#another-machine-over-ssh)                                                    | Shows the sessions of another machine running Agent Lookout, through your `ssh`. Off until you name one.                                         |
+| [Your own agents](docs/GUIDE.md#your-own-agents)                                                             | Shows any other agent that writes one small JSON file per session.                                                                               |
+
+The Overview also charts the last hour and how long sessions waited on you, from history kept on this computer. [The screen](docs/GUIDE.md#the-screen) covers each part.
+
+## Supported agents and systems
+
+Claude Code and Codex need no setup. Any other agent writes one small JSON file per session to `~/.agent-lookout/sessions`. [Your own agents](docs/GUIDE.md#your-own-agents).
+
+<!-- Checked against the adapters by tests/integration/collector/adapters/adapter.test.ts -->
+
+| Agent        | Needs you | Jump   | Quiet for | Stop   | Answer |
+| ------------ | --------- | ------ | --------- | ------ | ------ |
+| Claude Code  | Yes       | Partly | No        | Partly | Partly |
+| Codex        | No        | No     | Yes       | No     | No     |
+| Status files | Partly    | No     | Partly    | No     | No     |
+
+A Codex session waiting for approval shows as working. After 5 minutes its row says how long it has been quiet. [What each agent can report](docs/GUIDE.md#what-each-agent-can-report) gives the reason for every Partly and No.
+
+|                                            | macOS | Linux | Windows |
+| ------------------------------------------ | ----- | ----- | ------- |
+| Dashboard, `status`, `mcp`, email, webhook | Yes   | Yes   | Yes     |
+| Jump to VS Code                            | Yes   | Yes   | Yes     |
+| Jump to a tmux pane                        | Yes   | Yes   | No      |
+| Jump to Terminal or iTerm2                 | Yes   | No    | No      |
+| Stop, and ending sessions left running     | Yes   | Yes   | No      |
+| Allow and Deny, permission rules           | Yes   | Yes   | No      |
+| Resume                                     | Yes   | Yes   | No      |
+| Notifications with no tab open             | Yes   | No    | No      |
+| Mac app and menu bar                       | Yes   | No    | No      |
+
+Developed and used on macOS. On Linux and Windows, CI runs the tests and starts the app, and no one has used it on those desktops yet. [On Linux](docs/GUIDE.md#on-linux) · [On Windows](docs/GUIDE.md#on-windows)
+
+## In the terminal
 
 ```sh
 npx agent-lookout status
 ```
 
-It prints, for example:
-
 ```text
 2 need you · 3 working · 2 idle
 checkout-flow    Waiting for permission  4m 12s
 search-indexing  Asked you a question    31s
 ```
 
-It exits with 0 when nothing needs you, and 1 when a session does. It exits with 2 when Agent Lookout is not running, cannot be read or has read no agent yet, as in its first seconds. A mistyped command also exits with 2. It takes `--count` for the number alone and `--json` for JSON. A tmux status line or a shell prompt runs it every few seconds, so for those install it with `npm install -g agent-lookout` and run `agent-lookout status`: npm then does not ask its registry each time. In a clone, run `npm run --silent status`.
-
-It asks `http://127.0.0.1:4777`, then `http://localhost:5173`. If Agent Lookout runs on another port, give its address with `--url`, as in `npx agent-lookout status --url http://127.0.0.1:4778`, or set `AGENT_LOOKOUT_URL`. [In the terminal](docs/GUIDE.md#in-the-terminal) shows it in a tmux status line and a shell prompt.
-
-## For your agents
+It exits with 0 when nothing needs you, 1 when a session does, and 2 when Agent Lookout is not running or not ready. `--count` prints the number alone, `--json` prints JSON, and `--url` asks another port. [In the terminal](docs/GUIDE.md#in-the-terminal) shows it in a tmux status line and a shell prompt.
 
-`agent-lookout mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server. It lets an AI agent ask which sessions are running and which need you, so one agent can keep track of the others. Its three tools, `list_sessions`, `sessions_needing_you` and `sources`, only read: none of them can stop a session. It asks the Agent Lookout that is running, and starts nothing.
+## MCP server
 
-To add it to Claude Code for all your folders, run this once:
+`agent-lookout mcp` lets an AI agent ask which sessions need you. Its three tools, `list_sessions`, `sessions_needing_you` and `sources`, only read, and the agent's app usually hands their answers to its model. To add it to Claude Code for every folder:
 
 ```sh
 claude mcp add --scope user agent-lookout -- npx -y agent-lookout mcp
 ```
 
-`-y` lets npx start it without asking, since the app gives it no terminal to answer in. Each time the app starts the server, npx asks npm's registry whether a newer version is out. To avoid that, install it once with `npm install -g agent-lookout`, and use `agent-lookout mcp` in place of `npx -y agent-lookout mcp`. In a clone, run the command in the `agent-lookout` folder with `"$PWD/bin/agent-lookout.mjs" mcp` in place of it.
+<details>
+<summary>Other apps that take MCP servers</summary>
 
-`claude mcp list` then lists `agent-lookout`. Codex, and any other app that takes MCP servers, can start the same command, `npx -y agent-lookout mcp`. If Agent Lookout runs on another port, put `--url http://127.0.0.1:4778` after `mcp`. [For your agents](docs/GUIDE.md#for-your-agents) has the JSON form, and what to do when the app cannot find Node, as when Node was installed with nvm. [Privacy](#privacy) says where its answers go.
-
-## Settings you can change
+```json
+{
+  "mcpServers": {
+    "agent-lookout": { "command": "npx", "args": ["-y", "agent-lookout", "mcp"] }
+  }
+}
+```
 
-Settings are environment variables. Put one in front of the command it applies to:
+</details>
 
-```sh
-AGENT_LOOKOUT_CLAUDE_FEED=off npx agent-lookout
-```
+[For your agents](docs/GUIDE.md#for-your-agents) covers a global install, Node installed with nvm, and another port.
 
-| Setting                          | What it does                                                                                                                                                                      |
-| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AGENT_LOOKOUT_PORT`             | The port `npx agent-lookout`, `agent-lookout` and `npm start` listen on, 4777 unless set. `agent-lookout --port` does the same. It does not change where `status` and `mcp` look. |
-| `AGENT_LOOKOUT_URL`              | The address `agent-lookout status` and `agent-lookout mcp` ask, such as `http://127.0.0.1:4778`. Set it where those commands run, not where Agent Lookout starts.                 |
-| `AGENT_LOOKOUT_NOTIFICATIONS=on` | On a Mac, shows notifications of waits from the moment it starts, with no dashboard tab open.                                                                                     |
-| `AGENT_LOOKOUT_CLAUDE_FEED=off`  | Never runs the `claude` command. Sessions come from Claude Code's session files alone.                                                                                            |
-| `AGENT_LOOKOUT_WAITING_TEXT=off` | Never opens a Claude Code transcript. A waiting session shows its reason alone, here and on another machine read over SSH.                                                        |
-| `AGENT_LOOKOUT_HISTORY=off`      | Keeps the Events log and the charts in memory only, so they start empty each time. Nothing is written to `~/.agent-lookout/history`.                                              |
-| `AGENT_LOOKOUT_STOP=off`         | Takes away Stop and the ending of sessions left running. No session is ever stopped from Agent Lookout.                                                                           |
-| `AGENT_LOOKOUT_ANSWER=off`       | Takes away Allow and Deny and the permission rules. No socket is opened for the plugin, and no permission prompt is answered from Agent Lookout.                                  |
+## Settings
 
-[The guide](docs/GUIDE.md#settings-you-can-change) lists every setting, those for [email](docs/GUIDE.md#email) and the [webhook](docs/GUIDE.md#webhook) among them. The theme and the page's notifications are in the dashboard's Settings view.
+Settings are environment variables, put before the command, as in `AGENT_LOOKOUT_PORT=4778 npx agent-lookout`. Each of `AGENT_LOOKOUT_STOP=off`, `AGENT_LOOKOUT_ANSWER=off`, `AGENT_LOOKOUT_CLAUDE_FEED=off` and `AGENT_LOOKOUT_HISTORY=off` turns one thing off: Stop, Allow and Deny with the rules, running `claude agents`, and history on disk. The theme, notifications and rules are in the page's Settings view. [Settings you can change](docs/GUIDE.md#settings-you-can-change) lists every setting.
 
 ## Privacy
 
-By default Agent Lookout itself sends nothing anywhere: no telemetry, no analytics, no crash reports and no account. The one exception is the Mac app, which asks GitHub about once a day whether a newer version of it is out and sends nothing about your sessions: Settings turns that off, [Updates (Mac app only)](PRIVACY.md#updates-mac-app-only) says what it sends, and `npx agent-lookout` and the repository never check. Its fonts and scripts are bundled, so the page loads nothing from the internet. It keeps the Events log and the counts behind the charts on this computer, in `~/.agent-lookout/history`, so they are still there after a restart: for 8 days and up to 20 MB, with each session's name and status changes and no folder path, prompt or anything a waiting session is asking. Clear history in Settings deletes them, and `AGENT_LOOKOUT_HISTORY=off` keeps them in memory only. [PRIVACY.md](PRIVACY.md) lists everything it reads, runs, keeps and can send.
+By default Agent Lookout sends nothing anywhere: no telemetry, analytics, crash reports or account. The one exception is the Mac app, which asks GitHub about once a day whether a newer version is out, sends nothing about your sessions, and stops when you turn it off in Settings. `npx agent-lookout`, `npm start` and `npm run dev` make no such check.
+
+Each of these is off until you set it up:
 
-- Pull requests are off until you start Agent Lookout with `AGENT_LOOKOUT_PULL_REQUESTS=on`. Then it runs your own GitHub CLI, `gh`, which sends GitHub the owner and name of a session's repository and the name of its branch, with `gh`'s own login, so Agent Lookout never sees a token. It asks at most once every 2 minutes for each repository and branch, only for a remote on github.com and never about the default branch. [`gh`](PRIVACY.md#gh) says what it reads and keeps.
-- Email and the webhook are off until you set them up. Then each goes only to the one address you name, and email goes through the mail server you name. A message holds the session's name, what happened and when, how long a wait has lasted, and the names of its folder, app and agent. It holds no path and no prompt, unless you also turn on what a waiting session is asking, below.
-- Started with `npx agent-lookout`, npm contacts its registry: to download the package the first time, and each time after to ask whether a newer version is out. That is npm's own traffic, not Agent Lookout's. Installed with `npm install -g agent-lookout` and started as `agent-lookout`, npm is not involved.
-- It runs Claude Code's own `claude agents` command, which may contact Anthropic the way Claude Code normally does. `AGENT_LOOKOUT_CLAUDE_FEED=off` stops it running that command.
-- While a Claude Code session waits for you, it reads the end of its transcript to show what it asks, such as `Run: npm test`. It forgets that line when the wait ends. The line stays on this machine unless you start Agent Lookout with `AGENT_LOOKOUT_EMAIL_ASKING=on` or `AGENT_LOOKOUT_WEBHOOK_ASKING=on`, which put it in the email or post for that wait, or another computer names this one in `AGENT_LOOKOUT_REMOTES` and reads its sessions over SSH. It can hold a command, a web address or a file's full path. No answer of `agent-lookout mcp` holds it. `AGENT_LOOKOUT_WAITING_TEXT=off` turns it off.
-- Codex's session files hold your conversations. Agent Lookout reads them for when each turn started and ended, and for a few details such as the session's folder. It keeps none of your prompts, Codex's replies or the commands Codex ran.
-- With the [Agent Lookout plugin](docs/GUIDE.md#answer-a-permission-prompt) installed in Claude Code, each permission request, the tool and its input, which for a new file is the whole file, goes from Claude Code to Agent Lookout over a socket in `~/.agent-lookout` that only you can open. Agent Lookout keeps what it shows of it in memory until the prompt is answered, and never writes it down or sends it on. The [permission rules](docs/GUIDE.md#permission-rules) you add are kept in `~/.agent-lookout/settings.json`, and the Events log keeps, for each request a rule answered, the tool and the rule, never the command.
-- `agent-lookout mcp` does nothing until you add it to an agent's app. That app usually hands its answers, with your session names, folders and branches, to its model, which for most agents runs on the vendor's servers. [The MCP server](PRIVACY.md#the-mcp-server) says what an answer holds.
-- Other machines are read only once you name them in `AGENT_LOOKOUT_REMOTES`. Then it runs your own `ssh` to each, which signs in with your config and agent, and asks the Agent Lookout running there for its sessions, sending nothing of this computer's. While it is connected, other programs and user accounts on this computer can reach Agent Lookout there through its tunnel, as they can reach it here. [Another machine over SSH](PRIVACY.md#another-machine-over-ssh) says what is read.
-- Jump to a Terminal or iTerm2 tab needs macOS to let the program you start Agent Lookout from control that app. macOS asks once, and what you allow covers anything else you run from that program. Choose Don't Allow and only that Jump stops working. `AGENT_LOOKOUT_TERMINAL_JUMP=off` turns it off.
+- Email and the webhook, each to the one address you name.
+- Pull requests, through your own `gh`, with `AGENT_LOOKOUT_PULL_REQUESTS=on`.
+- Other machines, through your own `ssh`, named in `AGENT_LOOKOUT_REMOTES`.
+- The MCP server, whose answers the agent's app hands to its model.
+- The Claude Code plugin, which reaches Agent Lookout over a socket in `~/.agent-lookout`.
 
-It listens on a loopback address only, `127.0.0.1`, or `::1` if you set `AGENT_LOOKOUT_HOST`, and refuses any other, so other computers cannot reach it. It turns away requests from websites open in your browser. It has no password. While it runs, other programs and other user accounts on this computer can read it. They can also turn the notifications it shows on or off, change the time rules and the permission rules, do what the Jump button does, clear the history, stop a Claude Code session as the Stop button does, and answer a permission prompt it is holding as Allow and Deny do. The Mac app opens no port, so there only its own window can. A program running as you can still change its rules, by writing `~/.agent-lookout/settings.json`, which the app takes up at its next poll. It writes to no agent's files. It changes three things outside itself, and only when you ask. When you press Jump, it brings a tmux pane, or a Terminal or iTerm2 tab, to the front. When you press Stop and confirm, it ends that Claude Code session's process. When you press Allow or Deny, or a permission rule you added matches, it answers that one permission prompt, and rewrites nothing and saves no rule in Claude Code. `AGENT_LOOKOUT_STOP=off` takes Stop away, and `AGENT_LOOKOUT_ANSWER=off` takes Allow, Deny and the permission rules away.
+Other programs make their own traffic. `npx` asks npm's registry for the package. `claude agents`, which Agent Lookout runs, may contact Anthropic as Claude Code does, and `AGENT_LOOKOUT_CLAUDE_FEED=off` stops Agent Lookout running it.
+
+It listens on a loopback address only, 127.0.0.1 unless you set another, turns away requests from websites open in your browser, and has no password, so other programs and user accounts on this computer can use it as you can. The Mac app opens no port. [PRIVACY.md](PRIVACY.md) lists every file it reads and every command it runs, and [SECURITY.md](SECURITY.md) what it guards against.
 
 ## What it does not do yet
 
-- It does not resume a session itself: Resume copies the command that does, for a Claude Code session that has ended, on macOS and Linux. It cannot send a session a message. It stops a Claude Code session only when you press Stop and confirm, and not one in the desktop app or on Windows. It answers a permission prompt only with the plugin installed, and not on Windows, and offers Deny alone for an edit, since it does not show the change, for a plan or a question, and for a request it cannot show whole and as it is. A permission rule answers Claude Code's prompts only, and an allow rule never allows what you could not allow by hand, or a Bash line of more than one plain command. An agent using `agent-lookout mcp` can do none of these.
-- It shows sessions on this computer, and on [another machine](docs/GUIDE.md#another-machine-over-ssh) running Agent Lookout that you reach over SSH. Cloud sessions, Codex cloud tasks and chats in a browser tab do not appear.
-- Claude Code's session files and Codex's files are not documented by their makers. An update to either can make Agent Lookout show less, or nothing, until it is updated. [docs/adapters/codex.md](docs/adapters/codex.md#what-breaks-when-codex-changes) lists what breaks when Codex changes.
-- The Mac app is not signed with an Apple Developer ID yet, so the first time it is opened, macOS does not open it until you allow it in Privacy & Security. There is no app for Linux or Windows. Support for more agents is planned in the [milestones](https://github.com/Olanetsoft/agent-lookout/milestones).
+- It cannot send a session a message, and Resume only copies the command.
+- Cloud sessions, Codex cloud tasks and browser chats do not appear.
+- Claude Code's and Codex's files are undocumented, so an update can hide sessions. [What breaks when Codex changes](docs/adapters/codex.md#what-breaks-when-codex-changes)
+- The Mac app is not signed with an Apple Developer ID yet, and there is no Linux or Windows app.
+
+[What it does not do yet](docs/GUIDE.md#what-it-does-not-do-yet) has the details, and the [milestones](https://github.com/Olanetsoft/agent-lookout/milestones) what is planned.
 
-[What it does not do yet](docs/GUIDE.md#what-it-does-not-do-yet) has the details.
+## Questions
+
+<details>
+<summary>Can it act on a session without me?</summary>
+
+No. Stop needs a press and a confirm, and Allow and Deny need a press or a rule you added. `AGENT_LOOKOUT_STOP=off` and `AGENT_LOOKOUT_ANSWER=off` take them away.
+
+</details>
+
+<details>
+<summary>Why does a Codex session never show as needing me?</summary>
+
+Codex's files do not record when it waits for your approval, so watch its Quiet for line instead.
+
+</details>
+
+<details>
+<summary>Can I run the Mac app and npx together?</summary>
+
+Yes. The app opens no port, so `status` and `mcp` need the npx copy. Turn notifications on in only one of them, as [Mac app and npx together](docs/INSTALL.md#mac-app-and-npx-together) says.
+
+</details>
 
 ## Documentation
 
-| To                                                                 | Read                                                                 |
-| ------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| Learn each part of the screen, every setting and every fix         | [docs/GUIDE.md](docs/GUIDE.md)                                       |
-| See every file it reads, every command it runs and all it can send | [PRIVACY.md](PRIVACY.md)                                             |
-| Call its local HTTP API                                            | [docs/API.md](docs/API.md)                                           |
-| See how the parts fit together                                     | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)                         |
-| See what it reads from Codex, and what breaks when Codex changes   | [docs/adapters/codex.md](docs/adapters/codex.md)                     |
-| Add another agent, or send a fix                                   | [CONTRIBUTING.md](CONTRIBUTING.md)                                   |
-| See what changed                                                   | [CHANGELOG.md](CHANGELOG.md)                                         |
-| See what is planned                                                | [Milestones](https://github.com/Olanetsoft/agent-lookout/milestones) |
+| I want to                                      | Read                                                                 |
+| ---------------------------------------------- | -------------------------------------------------------------------- |
+| Install every way, update or stop it           | [docs/INSTALL.md](docs/INSTALL.md)                                   |
+| Learn each part of the screen                  | [The screen](docs/GUIDE.md#the-screen)                               |
+| Change a setting                               | [Settings you can change](docs/GUIDE.md#settings-you-can-change)     |
+| Fix a problem                                  | [When something goes wrong](docs/GUIDE.md#when-something-goes-wrong) |
+| Show my own agent                              | [Your own agents](docs/GUIDE.md#your-own-agents)                     |
+| See every file it reads and all it can send    | [PRIVACY.md](PRIVACY.md)                                             |
+| Know what it guards, or report a vulnerability | [SECURITY.md](SECURITY.md)                                           |
+| Call its local HTTP API                        | [docs/API.md](docs/API.md)                                           |
+| See how the parts fit together                 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)                         |
+| Write tests                                    | [tests/README.md](tests/README.md)                                   |
+| Install or remove the Claude Code plugin       | [plugins/agent-lookout/README.md](plugins/agent-lookout/README.md)   |
+| See what changed                               | [CHANGELOG.md](CHANGELOG.md)                                         |
+| See what is planned                            | [Milestones](https://github.com/Olanetsoft/agent-lookout/milestones) |
+
+## For coding agents
+
+To set Agent Lookout up for someone:
+
+- Run `npx --yes agent-lookout` in the background. It is ready when `curl -s http://127.0.0.1:4777/api/health` prints `{"ok":true`.
+- `npx agent-lookout status --json` prints the counts and the sessions that need you, and exits with 0, 1 or 2 as above.
+- `GET /api/sessions` lists every session. All routes answer on loopback only, and [docs/API.md](docs/API.md) lists them.
+- Do not use `sudo`, and do not set up email, a webhook, pull requests or other machines unless asked.
+
+To change its code, read [AGENTS.md](AGENTS.md) first. It has the commands, the rules a change must keep and where tests go. Run `npm run check` before you finish. Codex, and Claude Code from version 2.1.277, read AGENTS.md on their own. If you keep a CLAUDE.md or CLAUDE.local.md of your own in the clone, which git ignores here, Claude Code reads that instead, so put the line `@AGENTS.md` in it.
 
 ## Contributing
 
-Bug reports, fixes and support for other agents are welcome. For anything larger than a fix, open an issue first. [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, the checks to run and how to add another agent. Report a security problem privately, as [SECURITY.md](SECURITY.md) describes, and not in a public issue.
+Bug reports, fixes and support for other agents are welcome. Open an issue first for anything larger than a fix.
+
+```sh
+git clone https://github.com/Olanetsoft/agent-lookout.git
+cd agent-lookout
+npm install
+npx playwright install chromium
+```
+
+`npm run dev` then serves the page at http://localhost:5173, with the collector inside, until you press Ctrl+C. `npm run check` runs every check, and is the one to run before you finish.
+
+```text
+src/collector/          Node: finds sessions and serves them on 127.0.0.1
+src/dashboard/          The React page
+src/core/               Shared logic, with no DOM and no Node APIs
+src/cli/                The agent-lookout command: start, status and mcp
+src/desktop/            The Mac app's main process
+plugins/agent-lookout/  The Claude Code plugin's hook
+tests/                  Every test, in unit/, integration/ and component/
+site/                   The website
+```
+
+Start at `src/core/sessions/session.ts`. The full map is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, checks and [adding an agent](CONTRIBUTING.md#adding-an-adapter), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) how to work together. Ask questions in [issues](https://github.com/Olanetsoft/agent-lookout/issues). Report a security problem privately, as [SECURITY.md](SECURITY.md) describes.
 
 ## License