agent-lookout 0.2.1 → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +41 -0
- package/PRIVACY.md +113 -25
- package/README.md +21 -15
- package/SECURITY.md +20 -8
- package/bin/agent-lookout.mjs +49 -24
- package/dist/THIRD-PARTY-LICENSES.md +195 -0
- package/dist/assets/HistoryPanel-CIjshvhu.js +1 -0
- package/dist/assets/SessionPanel-eBOdTLD9.js +1 -0
- package/dist/assets/index-B-myfVQS.js +2 -0
- package/dist/assets/index-Cceyz9yZ.css +1 -0
- package/dist/assets/radix-BH0JH8UU.js +41 -0
- package/dist/cli/agent-lookout.js +4 -4
- package/dist/cli/{chunk-PQ3B5TN6.js → chunk-63XPRBHW.js} +88 -2
- package/dist/cli/{chunk-XJM5RZNV.js → chunk-KNOLJ3IC.js} +1 -1
- package/dist/cli/{chunk-UYGESSPG.js → chunk-XVXSGVEW.js} +6 -2
- package/dist/cli/mcpServer-HGH6PY4W.js +23664 -0
- package/dist/cli/{startCommand-ZV2NQ6YG.js → startCommand-KNXMVM2U.js} +3417 -676
- package/dist/index.html +3 -3
- package/docs/API.md +301 -79
- package/docs/GUIDE.md +215 -67
- package/package.json +6 -6
- package/dist/assets/HistoryPanel-Llcz5XPi.js +0 -1
- package/dist/assets/SessionPanel-B4g_6Unu.js +0 -1
- package/dist/assets/atkinson-hyperlegible-mono-latin-400-normal-Cmjm2dBj.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-mono-latin-500-normal-BV5ipwqM.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-mono-latin-600-normal-CuPF9o0F.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-mono-latin-ext-400-normal-ITMuFrSK.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-mono-latin-ext-500-normal-BiHEOgiK.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-mono-latin-ext-600-normal-ZiH-ObRk.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-next-latin-400-normal-DPp7N0cD.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-next-latin-500-normal-B0CYqHl3.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-next-latin-600-normal-BhgCag5w.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-next-latin-ext-400-normal-qxMiU51n.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-next-latin-ext-500-normal-oZS3KxrF.woff +0 -0
- package/dist/assets/atkinson-hyperlegible-next-latin-ext-600-normal-BBAQIogt.woff +0 -0
- package/dist/assets/index-DRcy1hT5.js +0 -2
- package/dist/assets/index-Dz4q_OYZ.css +0 -1
- package/dist/assets/radix-27o0jeIu.js +0 -41
- package/dist/cli/mcpServer-CGLIGL4X.js +0 -246
package/dist/index.html
CHANGED
|
@@ -28,11 +28,11 @@
|
|
|
28
28
|
document.documentElement.setAttribute("data-theme", theme);
|
|
29
29
|
})();
|
|
30
30
|
</script>
|
|
31
|
-
<script type="module" crossorigin src="/assets/index-
|
|
31
|
+
<script type="module" crossorigin src="/assets/index-B-myfVQS.js"></script>
|
|
32
32
|
<link rel="modulepreload" crossorigin href="/assets/react-C2DiJaR6.js">
|
|
33
33
|
<link rel="modulepreload" crossorigin href="/assets/motion-BAhdRuCw.js">
|
|
34
|
-
<link rel="modulepreload" crossorigin href="/assets/radix-
|
|
35
|
-
<link rel="stylesheet" crossorigin href="/assets/index-
|
|
34
|
+
<link rel="modulepreload" crossorigin href="/assets/radix-BH0JH8UU.js">
|
|
35
|
+
<link rel="stylesheet" crossorigin href="/assets/index-Cceyz9yZ.css">
|
|
36
36
|
</head>
|
|
37
37
|
<body>
|
|
38
38
|
<div id="root"></div>
|
package/docs/API.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# API
|
|
2
2
|
|
|
3
|
-
Agent Lookout's server answers a small HTTP API under `/api/`. The dashboard reads it, and so do `agent-lookout status` and `agent-lookout mcp`. It is meant for this computer only: it listens on a loopback address, and it answers only requests made to a loopback name. Every route returns JSON, and every route but
|
|
3
|
+
Agent Lookout's server answers a small HTTP API under `/api/`. The dashboard reads it, and so do `agent-lookout status` and `agent-lookout mcp`. It is meant for this computer only: it listens on a loopback address, and it answers only requests made to a loopback name. Every route returns JSON, and every route but four only reads.
|
|
4
4
|
|
|
5
5
|
The answers hold your session names and folder paths. Check one before you share it.
|
|
6
6
|
|
|
@@ -31,25 +31,30 @@ curl -s http://127.0.0.1:4777/api/sessions
|
|
|
31
31
|
|
|
32
32
|
Every answer has `Content-Type: application/json; charset=utf-8`, `Cache-Control: no-store`, `X-Content-Type-Options: nosniff` and `Cross-Origin-Resource-Policy: same-origin`. Every answer that is not a 200 has the body `{ "error": "<one sentence>" }`.
|
|
33
33
|
|
|
34
|
-
| Status | When
|
|
35
|
-
| ------ |
|
|
36
|
-
| 400 | The address, `since` or `windowMs` could not be read
|
|
37
|
-
| 403 | The `Host`, the `Origin` or `Sec-Fetch-Site` above
|
|
38
|
-
| 404 | There is no route at that path
|
|
39
|
-
| 405 | Any method but `GET`, with `Allow: GET`.
|
|
40
|
-
| 500 | Something went wrong that the server did not expect
|
|
34
|
+
| Status | When |
|
|
35
|
+
| ------ | ------------------------------------------------------------------------------------------------------ |
|
|
36
|
+
| 400 | The address, `since` or `windowMs` could not be read |
|
|
37
|
+
| 403 | The `Host`, the `Origin` or `Sec-Fetch-Site` above |
|
|
38
|
+
| 404 | There is no route at that path |
|
|
39
|
+
| 405 | Any method but `GET`, with `Allow: GET`. The four routes that act take only `POST`, with `Allow: POST` |
|
|
40
|
+
| 500 | Something went wrong that the server did not expect |
|
|
41
41
|
|
|
42
42
|
## Routes
|
|
43
43
|
|
|
44
|
-
| Route | Answers
|
|
45
|
-
| ---------------------------------- |
|
|
46
|
-
| `GET /api/health` | `{ ok: true, version }`
|
|
47
|
-
| `GET /api/sessions` | The latest snapshot: `{ generatedAt, sources, sessions }`
|
|
48
|
-
| `GET /api/events?since=<epoch ms>` | `{ events }`, newest first, at most 200
|
|
49
|
-
| `GET /api/history?windowMs=<ms>` | `{ points, startedAt }`, one point for each poll, oldest first
|
|
50
|
-
| `GET /api/email` | `{ on, to, events, afterMs, problem, last, limitedUntil }`
|
|
51
|
-
| `GET /api/webhook` | `{ on, host, events, afterMs, problem, last, limitedUntil }`
|
|
52
|
-
| `
|
|
44
|
+
| Route | Answers |
|
|
45
|
+
| ---------------------------------- | --------------------------------------------------------------------------------------- |
|
|
46
|
+
| `GET /api/health` | `{ ok: true, version }` |
|
|
47
|
+
| `GET /api/sessions` | The latest snapshot: `{ generatedAt, sources, sessions }` |
|
|
48
|
+
| `GET /api/events?since=<epoch ms>` | `{ events }`, newest first, at most 200 |
|
|
49
|
+
| `GET /api/history?windowMs=<ms>` | `{ points, startedAt, since, kept, restarts }`, one point for each poll, oldest first |
|
|
50
|
+
| `GET /api/email` | `{ on, to, events, afterMs, asking, problem, last, limitedUntil }` |
|
|
51
|
+
| `GET /api/webhook` | `{ on, host, events, afterMs, asking, problem, last, limitedUntil }` |
|
|
52
|
+
| `GET /api/pull-requests` | `{ on, problem, gh, last }`: whether each branch's pull request is shown |
|
|
53
|
+
| `GET /api/waits` | `{ at, today, sevenDays, since, where }`: how long sessions waited on you |
|
|
54
|
+
| `POST /api/jump` | `{ ok: true, kind, place }`, with `app` for a terminal tab. One of four routes that act |
|
|
55
|
+
| `POST /api/history/clear` | `{ ok: true, clearedAt }`. A route that acts |
|
|
56
|
+
| `POST /api/sessions/stop` | `{ ok: true }` once the session's process has ended. A route that acts |
|
|
57
|
+
| `POST /api/sessions/clean-up` | `{ results }`, what became of each session left running. A route that acts |
|
|
53
58
|
|
|
54
59
|
Times are milliseconds since 1970, and lengths of time are milliseconds.
|
|
55
60
|
|
|
@@ -99,70 +104,207 @@ The snapshot the collector made at its last poll, two seconds apart at most:
|
|
|
99
104
|
|
|
100
105
|
Sessions come in this order: those that need you first, longest wait first, then working, idle, finished, failed and unknown, each with the most recent change first.
|
|
101
106
|
|
|
102
|
-
| Session field
|
|
103
|
-
|
|
|
104
|
-
| `id`
|
|
105
|
-
| `source`
|
|
106
|
-
| `agent`
|
|
107
|
-
| `surface`
|
|
108
|
-
| `name`
|
|
109
|
-
| `cwd`
|
|
110
|
-
| `project`
|
|
111
|
-
| `git`
|
|
112
|
-
| `git.repository`
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
|
|
125
|
-
|
|
|
126
|
-
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
107
|
+
| Session field | Holds |
|
|
108
|
+
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
109
|
+
| `id` | Stable across polls: the source, a colon, and the agent's own id for the session |
|
|
110
|
+
| `source` | `claude-code`, `codex` or `status-files` |
|
|
111
|
+
| `agent` | The agent's own name, for a session from a status file. Left out for the others, whose agent is the source's `label` |
|
|
112
|
+
| `surface` | `terminal`, `vscode`, `desktop`, `cloud`, `browser` or `unknown` |
|
|
113
|
+
| `name` | What the dashboard calls it |
|
|
114
|
+
| `cwd` | The folder it works in, or `null` |
|
|
115
|
+
| `project` | The last part of `cwd`, or `null` |
|
|
116
|
+
| `git` | `{ branch }`, or `{ commit }` with seven characters when no branch is checked out, each with `repository`. Left out when the folder is in no repository that could be read |
|
|
117
|
+
| `git.repository` | `{ id, name }`: the repository the folder belongs to, the same for its main folder and every worktree of it. `name` is the main folder's name. `id` is 16 hexadecimal characters, a hash of the path of the repository's own git folder, which its worktrees share, for telling repositories apart. Left out for a repository with no name, at the root, or a worktree whose `commondir` cannot be read |
|
|
118
|
+
| `git.pullRequest` | With `AGENT_LOOKOUT_PULL_REQUESTS=on` only, for a branch whose pull request on github.com your own `gh` found: `{ number, title, state, checks, url }`. Described below. Left out with the setting off, for a commit, for the default branch, for a branch named with digits alone, such as `51`, for a repository with no remote on github.com, and for a branch with no pull request |
|
|
119
|
+
| `status` | `needs-you`, `working`, `idle`, `finished`, `failed` or `unknown` |
|
|
120
|
+
| `waitingReason` | For `needs-you` only: `permission`, `question` or `other` |
|
|
121
|
+
| `waitingDetail` | The agent's own words for the wait, when it gives any |
|
|
122
|
+
| `waitingText` | For `needs-you` Claude Code sessions only: what the session is asking, in a line or two, read from the last message of its transcript, such as `Run: npm test`, `Edit: src/app.ts` or the question it put. Plain text of at most 200 characters. Left out when the transcript does not say, or with `AGENT_LOOKOUT_WAITING_TEXT=off`. No event in `/api/events`, and no history point, holds it. An email or webhook post holds it only with `AGENT_LOOKOUT_EMAIL_ASKING=on` or `AGENT_LOOKOUT_WEBHOOK_ASKING=on` |
|
|
123
|
+
| `startedAt` | When it started, or `null` |
|
|
124
|
+
| `statusSince` | When its status last changed, or `null`. It does not move while a wait goes on |
|
|
125
|
+
| `lastWriteAt` | When its agent last wrote the file it is read from, for Codex and status files |
|
|
126
|
+
| `pid`, `alive` | Its process and whether that still runs, when known |
|
|
127
|
+
| `links.open` | A `vscode://` address that opens it, for a session in VS Code |
|
|
128
|
+
| `jump` | `{ kind: "tmux", place }` or `{ kind: "terminal", app, place }` when `POST /api/jump` can take you to it |
|
|
129
|
+
| `stop` | `{ how: "signal" }` or `{ how: "background" }` when `POST /api/sessions/stop` can stop it: a Claude Code session in a terminal or VS Code, or a background job. It holds nothing else |
|
|
130
|
+
| `stale` | `true` once it has been idle for 24 hours |
|
|
131
|
+
|
|
132
|
+
| Source field | Holds |
|
|
133
|
+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
134
|
+
| `id`, `label` | `claude-code` and `Claude Code`, `codex` and `Codex`, or `status-files` and `Status files` |
|
|
135
|
+
| `state` | `ok`, `searching`, `unavailable`, `not-set-up` or `error` |
|
|
136
|
+
| `detail` | One plain sentence: how it is being read, or what went wrong |
|
|
137
|
+
| `advice` | One plain sentence saying what you can do about a problem, when the collector knows |
|
|
138
|
+
| `watching` | `[{ label, value }]`: what it reads and runs, and how often |
|
|
139
|
+
| `basis` | Which way the sessions were read, for a source that has more than one |
|
|
140
|
+
| `capabilities` | What its agent can report, and whether its sessions can be stopped: for each of eight things, `{ level: "yes" }`, or `{ level: "no" }` or `"partly"` with a `reason` |
|
|
141
|
+
| `checkedAt` | When it was last read |
|
|
135
142
|
|
|
136
143
|
The [guide](GUIDE.md#what-each-agent-can-report) has the table `capabilities` holds.
|
|
137
144
|
|
|
145
|
+
With `AGENT_LOOKOUT_PULL_REQUESTS=on`, a session on a branch that has a pull request carries it in `git`:
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
"git": {
|
|
149
|
+
"branch": "checkout-flow",
|
|
150
|
+
"repository": { "id": "ad1b8c7a6a7a8b36", "name": "storefront" },
|
|
151
|
+
"pullRequest": {
|
|
152
|
+
"number": 51,
|
|
153
|
+
"title": "Show the pull request and its checks",
|
|
154
|
+
"state": "open",
|
|
155
|
+
"checks": { "state": "failing", "passing": 4, "failing": 2, "pending": 1 },
|
|
156
|
+
"url": "https://github.com/example-org/storefront/pull/51"
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
| Pull request field | Holds |
|
|
162
|
+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
163
|
+
| `number` | Its number on github.com |
|
|
164
|
+
| `title` | Its title, as someone wrote it on GitHub, cleaned of control characters and of the characters that change the direction of text, and cut to 200 characters, as a session's name is. Plain text |
|
|
165
|
+
| `state` | `open`, `draft`, `merged` or `closed` |
|
|
166
|
+
| `checks` | `{ state, passing, failing, pending }`, from each check on its latest commit, a check run again counted once. `state` is `failing` when any failed, `pending` when none failed and some have not finished, `passing`, or `none` with no checks |
|
|
167
|
+
| `checks.passing` | Checks that passed, were skipped or ended neutral |
|
|
168
|
+
| `checks.failing` | Checks that failed, timed out, were cancelled, went stale or need an action |
|
|
169
|
+
| `checks.pending` | Checks queued or still running, and commit statuses still pending |
|
|
170
|
+
| `url` | Its page, `https://github.com/<owner>/<repository>/pull/<number>`, which the collector builds from the remote and the number rather than take from GitHub |
|
|
171
|
+
|
|
172
|
+
It is what `gh` last said, asked at most once every 2 minutes for each repository and branch, so it can be up to about 2 minutes old. [Pull requests](GUIDE.md#pull-requests) in the guide says when it is asked for.
|
|
173
|
+
|
|
138
174
|
### `GET /api/events?since=<epoch ms>`
|
|
139
175
|
|
|
140
|
-
`{ "events": [...] }`: what changed, newest first, at most 200, and with `since` only those after it. Each event is `{ id, at, sessionId, sessionName, kind, from, to, severity }`, where `kind` is `appeared`, `status-changed` or `
|
|
176
|
+
`{ "events": [...] }`: what changed, newest first, at most 200, and with `since` only those after it. Each event is `{ id, at, sessionId, sessionName, kind, from, to, severity }`, where `kind` is `appeared`, `status-changed`, `ended` or `stopped`, `from` and `to` are statuses, and `severity` is `advisory`, `warning` for a change to `needs-you` or `critical` for a change to `failed`. A `stopped` event says that Agent Lookout stopped the session, when you pressed Stop or ended the sessions left running: it has `from`, the status the session had, no `to`, and `by: "agent-lookout"`. Its leaving the list is an `ended` event of its own. A reader should pass over a `kind` it does not know: later versions may add others. The collector keeps the last 1,000 in memory, and with history kept on disk it reads them back when it starts again.
|
|
141
177
|
|
|
142
178
|
### `GET /api/history?windowMs=<ms>`
|
|
143
179
|
|
|
144
|
-
|
|
180
|
+
One point for each poll, oldest first, each `{ at, needsYou, working, idle, total }`, over the last 15 minutes or the `windowMs` given, up to six hours, with where the history begins, where it is kept and when Agent Lookout was started again:
|
|
181
|
+
|
|
182
|
+
```json
|
|
183
|
+
{
|
|
184
|
+
"points": [{ "at": 1791204002000, "needsYou": 1, "working": 2, "idle": 3, "total": 6 }],
|
|
185
|
+
"startedAt": 1791204000000,
|
|
186
|
+
"since": { "at": 1790944800000, "by": "started" },
|
|
187
|
+
"kept": {
|
|
188
|
+
"where": "disk",
|
|
189
|
+
"folder": "~/.agent-lookout/history",
|
|
190
|
+
"bytes": 1468006,
|
|
191
|
+
"maxBytes": 20971520,
|
|
192
|
+
"maxAgeMs": 691200000,
|
|
193
|
+
"canClear": true,
|
|
194
|
+
"problem": null
|
|
195
|
+
},
|
|
196
|
+
"restarts": [{ "at": 1791204000000, "lastBefore": 1791190800000 }]
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
| Field | Holds |
|
|
201
|
+
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
202
|
+
| `startedAt` | When this run of Agent Lookout began. A new one means it was started again |
|
|
203
|
+
| `since` | Where the history it holds begins: `at`, a time, and `by`, which is `started` when Agent Lookout started watching then, `cleared` when the history was cleared then, or `trimmed` when that is the oldest history kept and what came before it was deleted for its age or the size. Time before `since.at` was not measured. With history kept on disk it can be days before `startedAt` |
|
|
204
|
+
| `kept` | `where` is `disk` or `memory`, with `AGENT_LOOKOUT_HISTORY=off`. On disk, `folder` is the folder with the home folder written `~`, and `bytes` how much the files hold. `maxBytes` is the cap, 20 MB, and `maxAgeMs` how long after its day a day's history is kept, 8 days. `canClear` says whether this copy can clear it, and `problem`, while it does not write the files, one sentence saying why, such as another copy writing them |
|
|
205
|
+
| `restarts` | Each time Agent Lookout started again after `since.at` with history kept from before, oldest first, this run's start among them: `at`, when it started, and `lastBefore`, the newest moment the history before it holds. Nothing was measured between the two, however close they are. Empty in memory only, and before the first restart |
|
|
206
|
+
|
|
207
|
+
A poll adds no point when no source answered, or when a source that answered before did not. Two points further apart than a few polls had time between them that was not measured: the computer asleep, a source that stopped answering, or Agent Lookout not running. So had two points either side of a restart. The dashboard draws that time hatched.
|
|
208
|
+
|
|
209
|
+
After a restart, the first poll that reads a source compares each session with the last event the history kept of it. A session whose status changed while Agent Lookout was stopped gets a `status-changed` event, one that ended an `ended` event, and one back after it ended an `appeared` event, all at that poll. A session the history kept no event of is taken as it is found.
|
|
210
|
+
|
|
211
|
+
### `GET /api/waits`
|
|
212
|
+
|
|
213
|
+
How long sessions waited on you today, from local midnight, and over the last seven days, which are today and the six days before it, from midnight. It is worked out from the whole of the history kept, eight days of it, and not only the six hours `/api/history` serves, and counts only the time Agent Lookout measured: while it was running and every source it reads answered. Days are this computer's own, by its clock and time zone.
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{
|
|
217
|
+
"at": 1791298800000,
|
|
218
|
+
"today": {
|
|
219
|
+
"from": 1791244800000,
|
|
220
|
+
"to": 1791298800000,
|
|
221
|
+
"waitedMs": 2100000,
|
|
222
|
+
"openMs": 298000,
|
|
223
|
+
"waits": 3,
|
|
224
|
+
"measuredMs": 8998000,
|
|
225
|
+
"days": [
|
|
226
|
+
{
|
|
227
|
+
"day": "2026-10-06",
|
|
228
|
+
"from": 1791244800000,
|
|
229
|
+
"to": 1791298800000,
|
|
230
|
+
"waitedMs": 2100000,
|
|
231
|
+
"openMs": 298000,
|
|
232
|
+
"waits": 3,
|
|
233
|
+
"measuredMs": 8998000
|
|
234
|
+
}
|
|
235
|
+
],
|
|
236
|
+
"sessions": [
|
|
237
|
+
{
|
|
238
|
+
"sessionId": "claude-code:00000000-0000-4000-8000-000000000001",
|
|
239
|
+
"name": "demo-project",
|
|
240
|
+
"waitedMs": 1200000,
|
|
241
|
+
"waits": 1,
|
|
242
|
+
"open": false
|
|
243
|
+
}
|
|
244
|
+
],
|
|
245
|
+
"sessionCount": 3
|
|
246
|
+
},
|
|
247
|
+
"sevenDays": { "from": 1790726400000, "to": 1791298800000, "days": [], "sessions": [] },
|
|
248
|
+
"since": { "at": 1791018000000, "by": "started" },
|
|
249
|
+
"where": "disk"
|
|
250
|
+
}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
`today` and `sevenDays` have the same fields. `sevenDays` above is cut short: it has its own totals, seven `days`, oldest first, and its own `sessions`.
|
|
254
|
+
|
|
255
|
+
| Field | Holds |
|
|
256
|
+
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
257
|
+
| `at` | When it was worked out, by the server's clock. Both periods end here |
|
|
258
|
+
| `waitedMs` | How long sessions waited on you. Each session's waits are added up, so two waiting at once for a minute are two minutes. Only time that was measured counts |
|
|
259
|
+
| `openMs` | The part of `waitedMs` that is a wait still open: a session that needs you now |
|
|
260
|
+
| `waits` | How many waits had time in the period. A wait that runs on across midnight, or across time that was not measured, is one wait |
|
|
261
|
+
| `measuredMs` | How much of the period Agent Lookout measured. The rest it was not running, the computer was asleep, a source did not answer, or it came before `since` |
|
|
262
|
+
| `days` | Each local day in the period, oldest first, with the same four figures: `day` as `2026-10-06`, `from` its midnight and `to` the next, or `at` for today |
|
|
263
|
+
| `sessions` | The ten sessions that waited longest, longest first: `sessionId`, `name` as it was last seen, `waitedMs`, `waits`, and `open`, true while it needs you |
|
|
264
|
+
| `sessionCount` | How many sessions waited in the period in all |
|
|
265
|
+
| `since` | Where the history held begins, as in `/api/history`. Nothing before it is counted |
|
|
266
|
+
| `where` | `disk`, or `memory` with `AGENT_LOOKOUT_HISTORY=off`, when the history begins as this run of Agent Lookout started, so only the time since then counts |
|
|
267
|
+
|
|
268
|
+
A wait begins with a move into `needs-you` and ends with the session's next move out of it, or its end. A wait already under way when Agent Lookout found the session, as when it started while the session waited, is counted from when that run of Agent Lookout started. A wait the history holds no end for, of a session that does not need you now, ended while Agent Lookout was stopped, so it is counted up to the start of this run and no further. Only Claude Code sessions and sessions from a status file can be seen waiting: a Codex session never needs you, so it is never in this answer.
|
|
145
269
|
|
|
146
270
|
### `GET /api/email` and `GET /api/webhook`
|
|
147
271
|
|
|
148
272
|
Whether [email](GUIDE.md#email) or a [webhook](GUIDE.md#webhook) is set up, and how the last one went. They only read: both are set up in the environment Agent Lookout starts with.
|
|
149
273
|
|
|
150
|
-
| Field | Holds
|
|
151
|
-
| -------------- |
|
|
152
|
-
| `on` | Whether it sends
|
|
153
|
-
| `to` | Email only: the address, with all but its first letter before the `@` hidden
|
|
154
|
-
| `host` | Webhook only: the host the posts go to, and never the rest of the address
|
|
155
|
-
| `events` | What is sent: `needs-you`, `finished`, `failed` and `ended`, any of them
|
|
156
|
-
| `afterMs` | How long a wait lasts before it is sent
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
274
|
+
| Field | Holds |
|
|
275
|
+
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
276
|
+
| `on` | Whether it sends |
|
|
277
|
+
| `to` | Email only: the address, with all but its first letter before the `@` hidden |
|
|
278
|
+
| `host` | Webhook only: the host the posts go to, and never the rest of the address |
|
|
279
|
+
| `events` | What is sent: `needs-you`, `finished`, `failed` and `ended`, any of them |
|
|
280
|
+
| `afterMs` | How long a wait lasts before it is sent |
|
|
281
|
+
| `asking` | Whether the email or post for a wait says what the session is asking: `true` with `AGENT_LOOKOUT_EMAIL_ASKING=on` or `AGENT_LOOKOUT_WEBHOOK_ASKING=on`, `false` when that setting is `off` or left out, and `null` while email or the webhook is off |
|
|
282
|
+
| `problem` | While off because a setting is wrong, one sentence naming the setting, never its value |
|
|
283
|
+
| `last` | `{ at, sent: true }` or `{ at, sent: false, reason }` for the last one tried, or `null` |
|
|
284
|
+
| `limitedUntil` | While the limit of 20 an hour holds them back, when the next may go |
|
|
285
|
+
|
|
286
|
+
Neither ever holds the mail server's address, its user name or its password, the webhook's path, or anything a session was asking.
|
|
287
|
+
|
|
288
|
+
### `GET /api/pull-requests`
|
|
160
289
|
|
|
161
|
-
|
|
290
|
+
Whether Agent Lookout shows each session's [pull request](GUIDE.md#pull-requests), with `AGENT_LOOKOUT_PULL_REQUESTS=on`, and whether the GitHub CLI, `gh`, can be asked for them. It only reads.
|
|
291
|
+
|
|
292
|
+
```json
|
|
293
|
+
{ "on": true, "problem": null, "gh": "ready", "last": { "at": 1791205920000, "ok": true } }
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
| Field | Holds |
|
|
297
|
+
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
298
|
+
| `on` | Whether pull requests are asked for |
|
|
299
|
+
| `problem` | While off because the setting is neither `on` nor `off`, one sentence naming it |
|
|
300
|
+
| `gh` | While on, what `gh` was last found to be: `unknown` before it was needed, `ready`, `not-found` when there is no `gh` on `PATH` or in the usual places, or `signed-out` when it is not signed in. `null` while off |
|
|
301
|
+
| `last` | `{ at, ok: true }` or `{ at, ok: false, reason }` for the last question `gh` was asked, or `null`. A `reason` is one of Agent Lookout's own sentences, such as `gh did not answer within 15 seconds`, never what `gh` printed |
|
|
302
|
+
|
|
303
|
+
It never holds a token: `gh` signs in with its own login, which Agent Lookout never reads.
|
|
162
304
|
|
|
163
305
|
### `POST /api/jump`
|
|
164
306
|
|
|
165
|
-
|
|
307
|
+
One of the four routes that act. It selects the tmux pane a session runs in, or brings its tab of Terminal or iTerm2 to the front, as the Jump button does. Its checks, on top of the ones every request passes, are `jumpRefusalFor` in `src/collector/jumpRoute.ts`, which makes those `actionRefusalFor` in `src/collector/handler.ts` makes for every route that acts. It answers only a request that:
|
|
166
308
|
|
|
167
309
|
- is a `POST`. Any other method gets 405, with `Allow: POST`.
|
|
168
310
|
- has an `Origin` that names this computer. A request with no `Origin` gets 403 here, though a read may go without one.
|
|
@@ -184,18 +326,96 @@ The server then looks the session up in its own latest snapshot and acts on the
|
|
|
184
326
|
|
|
185
327
|
Each of these has an `error` sentence beside its `reason`. [SECURITY.md](../SECURITY.md) says what the route can and cannot change.
|
|
186
328
|
|
|
329
|
+
### `POST /api/history/clear`
|
|
330
|
+
|
|
331
|
+
A route that acts. It deletes the files the history is kept in, except any that a later version of Agent Lookout wrote, and empties the Events log and the history in memory, as Clear history in Settings does. The history then begins again from that moment, with `since` set to `{ at, by: "cleared" }`. It makes the same checks as `POST /api/jump`, with its own action, in `src/collector/history/clearRoute.ts`, and answers only a request that:
|
|
332
|
+
|
|
333
|
+
- is a `POST`. Any other method gets 405, with `Allow: POST`.
|
|
334
|
+
- has an `Origin` that names this computer, or gets 403.
|
|
335
|
+
- is marked `same-origin` in `Sec-Fetch-Site`, when that header is sent, or gets 403.
|
|
336
|
+
- carries `X-Agent-Lookout-Action: clear-history`, or gets 403.
|
|
337
|
+
- has `Content-Type: application/json`, or gets 415.
|
|
338
|
+
- has a body of 64 bytes or less, or gets 413, that is exactly `{}`, or gets 400.
|
|
339
|
+
|
|
340
|
+
Nothing in the request names a file: the files are the ones in the history's own folder.
|
|
341
|
+
|
|
342
|
+
| Status | Body |
|
|
343
|
+
| ------ | ------------------------------------------------------------------------------------------------------------------------ |
|
|
344
|
+
| 200 | `{ "ok": true, "clearedAt": 1791204000000 }` |
|
|
345
|
+
| 409 | `reason: "memory-only"`: history is kept in memory only, with `AGENT_LOOKOUT_HISTORY=off`, and there is nothing to clear |
|
|
346
|
+
| 409 | `reason: "not-writing"`: another copy of Agent Lookout writes the files, or they cannot be written here |
|
|
347
|
+
| 500 | `reason: "failed"`: the files could not all be deleted, and nothing in memory was emptied |
|
|
348
|
+
|
|
349
|
+
Each of these has an `error` sentence beside its `reason`.
|
|
350
|
+
|
|
351
|
+
### `POST /api/sessions/stop`
|
|
352
|
+
|
|
353
|
+
A route that acts. It ends one Claude Code session's process, as Stop session does in the session's details. It makes the same checks as `POST /api/jump`, with its own action, in `src/collector/actions/stopRoute.ts`, and answers only a request that:
|
|
354
|
+
|
|
355
|
+
- is a `POST`. Any other method gets 405, with `Allow: POST`.
|
|
356
|
+
- has an `Origin` that names this computer, or gets 403.
|
|
357
|
+
- is marked `same-origin` in `Sec-Fetch-Site`, when that header is sent, or gets 403.
|
|
358
|
+
- carries `X-Agent-Lookout-Action: stop`, or gets 403.
|
|
359
|
+
- has `Content-Type: application/json`, or gets 415.
|
|
360
|
+
- has a body of 1,024 bytes or less, or gets 413, that is exactly `{ "sessionId": "..." }`, or gets 400.
|
|
361
|
+
|
|
362
|
+
The server looks the session up in its own latest snapshot, and stops only one with a `stop` field, by what it found for it itself: its process, or its background job. Before it acts it reads the session's registry file again, which must still name that session, that process, the same kind, `interactive` or `bg`, and the same start time, and asks `ps` for the process's start time again, which must be the same, to the second. It never stops process 1, its own process, the one it was started from or any process above that. Then it sends SIGTERM, and waits up to 10 seconds for the process to end, or runs `claude stop` with the job's ID. Nothing in the request reaches a signal or a command. A stop adds a `stopped` event, and the server reads the sessions again before it answers. It makes one stop a second, and one at a time, with the clean-up's.
|
|
363
|
+
|
|
364
|
+
| Status | Body |
|
|
365
|
+
| ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
366
|
+
| 200 | `{ "ok": true }`: the process has ended, or the background job was stopped |
|
|
367
|
+
| 202 | `{ "ok": false, "reason": "still-running" }`: SIGTERM was sent, and the process is still running 10 seconds later. Nothing more is sent |
|
|
368
|
+
| 404 | `reason: "gone"`: the session is not listed, or its process has already ended |
|
|
369
|
+
| 409 | `reason: "unsupported"`: Agent Lookout does not stop this session, such as one in the desktop app or one whose kind is not known |
|
|
370
|
+
| 409 | `reason: "cannot-confirm"`: its registry file changed, or `ps` did not give the same start time |
|
|
371
|
+
| 403 | `reason: "not-allowed"`: the process is another user's, or one Agent Lookout never stops |
|
|
372
|
+
| 429 | `reason: "too-soon"`, with `Retry-After: 1` |
|
|
373
|
+
| 500 | `reason: "failed"`: the signal could not be sent, or `claude stop` failed |
|
|
374
|
+
|
|
375
|
+
Each of these has an `error` sentence beside its `reason`. With `AGENT_LOOKOUT_STOP=off` there is no such route, and a POST to it gets 405.
|
|
376
|
+
|
|
377
|
+
### `POST /api/sessions/clean-up`
|
|
378
|
+
|
|
379
|
+
A route that acts. It ends the sessions left running that you chose, as End does under Left running in the Sessions card. It makes the same checks as `POST /api/sessions/stop`, with `X-Agent-Lookout-Action: clean-up`, and takes a body of 8 KiB or less that is exactly:
|
|
380
|
+
|
|
381
|
+
```json
|
|
382
|
+
{
|
|
383
|
+
"sessions": [
|
|
384
|
+
{
|
|
385
|
+
"sessionId": "claude-code:00000000-0000-4000-8000-000000000004",
|
|
386
|
+
"statusSince": 1791118800000
|
|
387
|
+
}
|
|
388
|
+
]
|
|
389
|
+
}
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
with 1 to 20 sessions, none named twice, each with the `statusSince` the page showed for it. Anything else gets 400. For each session in turn the server makes every check of `POST /api/sessions/stop`, and then reads in the session's registry file, and in its own latest list of sessions, that it is still idle, since that same `statusSince`, and that this was 24 hours or more ago. A session that has done anything since is left running. Then it stops each one that passed, as the stop route does, and waits up to 10 seconds for them all.
|
|
393
|
+
|
|
394
|
+
```json
|
|
395
|
+
{
|
|
396
|
+
"results": [
|
|
397
|
+
{ "sessionId": "claude-code:00000000-0000-4000-8000-000000000004", "outcome": "ended" },
|
|
398
|
+
{ "sessionId": "claude-code:00000000-0000-4000-8000-000000000005", "outcome": "became-active" }
|
|
399
|
+
]
|
|
400
|
+
}
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
The answer is 200 with an `outcome` for each session asked for, in order: `ended`, `became-active`, `not-stale`, `gone`, `unsupported`, `cannot-confirm`, `not-allowed`, `still-running` or `failed`, which mean what the stop route's reasons do. One `stopped` event is added for each session ended. A clean-up while a stop or another clean-up is under way, or less than a second after one began, gets 429 with `reason: "too-soon"`.
|
|
404
|
+
|
|
187
405
|
## In the Mac app only
|
|
188
406
|
|
|
189
|
-
The Mac app serves the dashboard and this API from its own address, `agent-lookout://app/`, with no port, and answers
|
|
407
|
+
The Mac app serves the dashboard and this API from its own address, `agent-lookout://app/`, with no port, and answers six more routes there, for its updates and its menu bar item. `npm start`, `npx agent-lookout` and `npm run dev` do not have them: there, each answers 404.
|
|
190
408
|
|
|
191
|
-
| Route
|
|
192
|
-
|
|
|
193
|
-
| `GET /api/app/update`
|
|
194
|
-
| `POST /api/app/update/check`
|
|
195
|
-
| `POST /api/app/update/install`
|
|
196
|
-
| `POST /api/app/update/setting`
|
|
409
|
+
| Route | Body | Does |
|
|
410
|
+
| -------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
411
|
+
| `GET /api/app/update` | | Where updates stand: the version, the switch, the last check, what was found and how far a download has got |
|
|
412
|
+
| `POST /api/app/update/check` | `{}` | Checks GitHub now, and answers once it has |
|
|
413
|
+
| `POST /api/app/update/install` | `{}` | Installs the version that is ready, then quits and opens it. 409 when none is ready, or it cannot be installed where the app runs |
|
|
414
|
+
| `POST /api/app/update/setting` | `{ "automatic": true }` or `false` | Turns the daily check on or off |
|
|
415
|
+
| `GET /api/app/menu-bar` | | Whether the menu bar item is shown: `{ "show": true }` or `false` |
|
|
416
|
+
| `POST /api/app/menu-bar/setting` | `{ "show": true }` or `false` | Shows the menu bar item or takes it away |
|
|
197
417
|
|
|
198
|
-
Each POST passes the checks `POST /api/jump` does, with its own `X-Agent-Lookout-Action
|
|
418
|
+
Each POST passes the checks `POST /api/jump` does, with its own `X-Agent-Lookout-Action` and a body that is exactly what the table says. For updates, the action is `check-for-updates`, `install-update` or `update-setting`, the body is 256 bytes or less, and each answers with the status `GET /api/app/update` gives, `AppUpdateStatus` in `src/core/appUpdate.ts`. For the menu bar item, the action is `menu-bar-setting`, the body is 64 bytes or less, and it answers with what `GET /api/app/menu-bar` gives, `MenuBarStatus` in `src/core/appMenuBar.ts`. That says `false` while the item could not be put in the menu bar, even with the switch on. Nothing in a request reaches a command or a path.
|
|
199
419
|
|
|
200
420
|
## The notifications header
|
|
201
421
|
|
|
@@ -205,18 +425,20 @@ A program that only reads should not send it. `agent-lookout status` and `agent-
|
|
|
205
425
|
|
|
206
426
|
## For this computer only
|
|
207
427
|
|
|
208
|
-
The API has no token or password. The `Host` and `Origin` rules keep websites, and other computers on the network, away from it: it listens on loopback, and a browser cannot be made to read it from another site. What they do not stop is another program on this computer, which can read it as `curl` does, and on a shared computer that includes other user accounts. [SECURITY.md](../SECURITY.md) lists that as a known limit.
|
|
428
|
+
The API has no token or password. The `Host` and `Origin` rules keep websites, and other computers on the network, away from it: it listens on loopback, and a browser cannot be made to read it from another site. What they do not stop is another program on this computer, which can read it as `curl` does, and on a shared computer that includes other user accounts. Such a program can also send the headers a route that acts asks for, since no browser is involved, so another account can ask the server to stop your Claude Code sessions, which it could not do itself. [SECURITY.md](../SECURITY.md) lists that as a known limit. The Mac app opens no port, and `AGENT_LOOKOUT_STOP=off` takes stopping away.
|
|
209
429
|
|
|
210
|
-
A token would not keep out programs running as you, which could read it as easily as the API. It could keep out other accounts on a shared computer, the known limit above, and is left for a later version. The MCP server changes none of this: it opens no port of its own, speaks to the app that started it over stdin and stdout, and reads the same loopback API the dashboard and `agent-lookout status` read without one. A token is also for an API that can be reached some other way, such as from another computer, and Agent Lookout has none.
|
|
430
|
+
A token would not keep out programs running as you, which could read it as easily as the API. It could keep out other accounts on a shared computer, stopping your sessions included, the known limit above, and is left for a later version. The MCP server changes none of this: it opens no port of its own, speaks to the app that started it over stdin and stdout, and reads the same loopback API the dashboard and `agent-lookout status` read without one. A token is also for an API that can be reached some other way, such as from another computer, and Agent Lookout has none.
|
|
211
431
|
|
|
212
432
|
## The MCP server
|
|
213
433
|
|
|
214
434
|
`agent-lookout mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server for an agent that keeps track of your other agents. The agent's app starts it and speaks to it over stdin and stdout. For each tool call it reads `GET /api/sessions` once, exactly as `agent-lookout status` does: from a loopback address only, with no `Origin` and no notifications header. It has three tools, and none of them acts:
|
|
215
435
|
|
|
216
|
-
| Tool | Answers
|
|
217
|
-
| ---------------------- |
|
|
218
|
-
| `list_sessions` | Every session, or those with the `status` given, with its id, name, agent, status, reason, folder, branch, app, since and how long it has been quiet |
|
|
219
|
-
| `sessions_needing_you` | The waiting sessions, longest wait first, with how long each has waited, and a sentence that sums them up
|
|
220
|
-
| `sources` | Each source's state in words, and its row of what its agent can and cannot report
|
|
436
|
+
| Tool | Answers |
|
|
437
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
438
|
+
| `list_sessions` | Every session, or those with the `status` given, with its id, name, agent, status, reason, folder, branch, pull request, app, since and how long it has been quiet |
|
|
439
|
+
| `sessions_needing_you` | The waiting sessions, longest wait first, with how long each has waited, and a sentence that sums them up |
|
|
440
|
+
| `sources` | Each source's state in words, and its row of what its agent can and cannot report |
|
|
441
|
+
|
|
442
|
+
A session's `pullRequest` is `{ number, checks }`, its number and the state of its checks, `failing`, `pending`, `passing` or `none`, only with `AGENT_LOOKOUT_PULL_REQUESTS=on` and for a branch that has one, and `null` otherwise. It never holds the title or the address. `agent-lookout status --json` gives a waiting session the same `pullRequest`, and leaves it out when there is none.
|
|
221
443
|
|
|
222
444
|
The [guide](GUIDE.md#for-your-agents) says how to add it to an agent's app and what each answer holds.
|