agent-lookout 0.2.6 → 0.2.8
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 +34 -0
- package/PRIVACY.md +151 -26
- package/README.md +190 -160
- package/SECURITY.md +24 -9
- package/dist/assets/{HistoryPanel-Cwmn7YtJ.js → HistoryPanel-CQ7zovsM.js} +1 -1
- package/dist/assets/{SessionPanel-BJ5t_CPi.js → SessionPanel-DS29Z04P.js} +1 -1
- package/dist/assets/index-BWFkRW4g.js +3 -0
- package/dist/assets/motion-DlYOyClL.js +9 -0
- package/dist/cli/agent-lookout.js +2 -2
- package/dist/cli/{mcpServer-HJSH3WIS.js → mcpServer-BMSF2TXC.js} +2 -2
- package/dist/cli/{startCommand-PR5JPWCT.js → startCommand-ANC7NVAO.js} +2496 -474
- package/dist/index.html +2 -2
- package/docs/API.md +102 -46
- package/docs/GUIDE.md +250 -147
- package/docs/INSTALL.md +177 -0
- package/package.json +6 -1
- package/dist/assets/index-QSfCI-L_.js +0 -3
- package/dist/assets/motion-BAhdRuCw.js +0 -9
package/README.md
CHANGED
|
@@ -1,133 +1,67 @@
|
|
|
1
1
|
# Agent Lookout
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Shows the AI agent sessions on your computer in one browser page, and which need you.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/agent-lookout) [](https://github.com/Olanetsoft/agent-lookout/actions/workflows/ci.yml) [](LICENSE) 
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
It finds Claude Code, Codex and Antigravity CLI 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.
|
|
8
|
+
|
|
9
|
+
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, pushes to your phone through ntfy or Pushover, pull requests through your `gh` and other machines over your `ssh` stay off until you set them up. [Privacy](#privacy)
|
|
10
|
+
|
|
11
|
+
[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)
|
|
8
12
|
|
|
9
13
|
<picture>
|
|
10
14
|
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Olanetsoft/agent-lookout/main/docs/images/dashboard-day.png">
|
|
11
|
-
<img alt="The Overview.
|
|
15
|
+
<img alt="The Overview. In the Needs you panel, checkout-flow, a Claude Code session in Terminal, has waited 4 minutes 12 seconds for permission. Under Asks to run are the whole command, npm test, its description and the Deny and Allow buttons, and a Jump button is beside the timer. Below them are bars of how long sessions waited on you and counts of working, idle and stale sessions. The Last hour chart is beside the panel. Under both are the Sessions list, where billing-migration is marked devbox, the other machine it runs on, and the Events log." src="https://raw.githubusercontent.com/Olanetsoft/agent-lookout/main/docs/images/dashboard-night.png">
|
|
12
16
|
</picture>
|
|
13
17
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
| Part | Description |
|
|
17
|
-
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
18
|
-
| [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`. |
|
|
19
|
-
| [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. |
|
|
20
|
-
| [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. |
|
|
21
|
-
| [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. |
|
|
22
|
-
| [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. |
|
|
23
|
-
| [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. |
|
|
24
|
-
| [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. |
|
|
25
|
-
| [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. |
|
|
26
|
-
| [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. |
|
|
27
|
-
| [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. |
|
|
28
|
-
| [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. |
|
|
29
|
-
| [`agent-lookout status`](docs/GUIDE.md#in-the-terminal) | Prints which sessions need you, for a terminal, a tmux status line or a script. |
|
|
30
|
-
| [`agent-lookout mcp`](docs/GUIDE.md#for-your-agents) | Lets an AI agent ask which sessions need you. Its tools only read. |
|
|
31
|
-
| [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. |
|
|
32
|
-
|
|
33
|
-
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.
|
|
34
|
-
|
|
35
|
-
## Supported agents and systems
|
|
36
|
-
|
|
37
|
-
| Agent | Setup | How it finds sessions | Shows when it needs you | Jump |
|
|
38
|
-
| --------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------ |
|
|
39
|
-
| 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 |
|
|
40
|
-
| Codex | None | Reads `sessions`, `thread-writer-locks` and `session_index.jsonl` in `~/.codex` every 2 seconds, and runs nothing | No | No |
|
|
41
|
-
| 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 |
|
|
42
|
-
|
|
43
|
-
Claude Code sessions are found whether they run in a terminal, in VS Code or in the desktop app.
|
|
44
|
-
|
|
45
|
-
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.
|
|
46
|
-
|
|
47
|
-
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.
|
|
18
|
+
_A Claude Code session asks to run `npm test`. With the Claude Code plugin, Allow or Deny answers it from the page, and Jump takes you to it in Terminal._
|
|
48
19
|
|
|
49
20
|
## Install
|
|
50
21
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
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.
|
|
54
|
-
|
|
55
|
-
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.
|
|
56
|
-
|
|
57
|
-
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.
|
|
58
|
-
|
|
59
|
-
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.
|
|
22
|
+
Start it with npx or the Mac app. Add the Claude Code plugin to either one to answer permission prompts from the page.
|
|
60
23
|
|
|
61
24
|
### With npx
|
|
62
25
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
```sh
|
|
66
|
-
node --version
|
|
67
|
-
claude --version
|
|
68
|
-
claude agents --help
|
|
69
|
-
codex --version
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
`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.
|
|
73
|
-
|
|
74
|
-
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.
|
|
75
|
-
|
|
76
|
-
2. Start it. It keeps running until you press Ctrl+C, so leave this terminal open.
|
|
77
|
-
|
|
78
|
-
```sh
|
|
79
|
-
npx agent-lookout
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
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:
|
|
26
|
+
You need Node.js 22.12 or newer, and Claude Code, Codex or the Antigravity CLI.
|
|
83
27
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
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`.
|
|
90
|
-
|
|
91
|
-
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.
|
|
92
|
-
|
|
93
|
-
3. Check that it answers. If `npx agent-lookout` holds your terminal, use a second one.
|
|
28
|
+
```sh
|
|
29
|
+
npx agent-lookout
|
|
30
|
+
```
|
|
94
31
|
|
|
95
|
-
|
|
96
|
-
curl -s http://127.0.0.1:4777/api/health
|
|
97
|
-
```
|
|
32
|
+
The first time, npm asks `Ok to proceed?`. Then it prints:
|
|
98
33
|
|
|
99
|
-
|
|
34
|
+
```text
|
|
35
|
+
Agent Lookout is running at http://127.0.0.1:4777
|
|
36
|
+
It listens on this machine only. Press Ctrl+C to stop.
|
|
37
|
+
```
|
|
100
38
|
|
|
101
|
-
|
|
39
|
+
Open http://127.0.0.1:4777. Your sessions appear within a few seconds. To check it from another terminal:
|
|
102
40
|
|
|
103
|
-
|
|
41
|
+
```sh
|
|
42
|
+
curl -s http://127.0.0.1:4777/api/health
|
|
43
|
+
```
|
|
104
44
|
|
|
105
|
-
|
|
45
|
+
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.
|
|
106
46
|
|
|
107
|
-
|
|
47
|
+
### Mac app
|
|
108
48
|
|
|
109
|
-
|
|
49
|
+
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 macOS 13 Ventura or later, and 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.
|
|
110
50
|
|
|
111
|
-
|
|
112
|
-
npm install -g agent-lookout
|
|
113
|
-
agent-lookout
|
|
114
|
-
```
|
|
51
|
+
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.
|
|
115
52
|
|
|
116
|
-
###
|
|
53
|
+
### Claude Code plugin
|
|
117
54
|
|
|
118
|
-
|
|
55
|
+
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:
|
|
119
56
|
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
npm install
|
|
124
|
-
npm run build
|
|
125
|
-
npm start
|
|
57
|
+
```text
|
|
58
|
+
/plugin marketplace add Olanetsoft/agent-lookout
|
|
59
|
+
/plugin install agent-lookout@agent-lookout
|
|
126
60
|
```
|
|
127
61
|
|
|
128
|
-
|
|
62
|
+
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.
|
|
129
63
|
|
|
130
|
-
|
|
64
|
+
### Install with your agent
|
|
131
65
|
|
|
132
66
|
A coding agent such as Claude Code or Codex can start it for you. Give it this prompt:
|
|
133
67
|
|
|
@@ -139,110 +73,206 @@ It should print "Agent Lookout is running at http://127.0.0.1:4777".
|
|
|
139
73
|
If it prints anything else, or says the port is in use, stop and tell
|
|
140
74
|
me what it printed.
|
|
141
75
|
|
|
142
|
-
Do not use sudo, and do not set up email
|
|
143
|
-
|
|
76
|
+
Do not use sudo, and do not set up email, a webhook, phone pushes,
|
|
77
|
+
pull requests or other machines. You are done when
|
|
78
|
+
curl -s http://127.0.0.1:4777/api/health prints {"ok":true and a
|
|
144
79
|
version number. Tell me what it printed.
|
|
145
80
|
```
|
|
146
81
|
|
|
147
82
|
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.
|
|
148
83
|
|
|
149
|
-
|
|
84
|
+
To run it from a clone, see [From the repository](docs/INSTALL.md#from-the-repository).
|
|
85
|
+
|
|
86
|
+
## What it does
|
|
150
87
|
|
|
151
|
-
|
|
88
|
+
| Part | What it does |
|
|
89
|
+
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
90
|
+
| [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. |
|
|
91
|
+
| [Sessions](docs/GUIDE.md#sessions) | Lists the rest by status, by repository or on a board, with folder and branch. `/` searches every session. |
|
|
92
|
+
| [Jump](docs/GUIDE.md#jump) | Takes you to a Claude Code session in VS Code, its tmux pane, or its Terminal or iTerm2 tab. |
|
|
93
|
+
| [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. |
|
|
94
|
+
| [Allow and Deny](docs/GUIDE.md#answer-a-permission-prompt) | Answers a Claude Code permission prompt from the page, or the Mac app's notification and menu bar, with the plugin. [Rules](docs/GUIDE.md#permission-rules) you add can answer some for you. |
|
|
95
|
+
| [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. |
|
|
96
|
+
| [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. |
|
|
97
|
+
| [ntfy](docs/GUIDE.md#ntfy) and [Pushover](docs/GUIDE.md#pushover) | Push a wait, its reminders and what else you choose to your phone, with Send a test in Settings. Off until set up. |
|
|
98
|
+
| [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. |
|
|
99
|
+
| [Your own agents](docs/GUIDE.md#your-own-agents) | Shows any other agent that writes one small JSON file per session. |
|
|
100
|
+
|
|
101
|
+
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.
|
|
102
|
+
|
|
103
|
+
## Supported agents and systems
|
|
104
|
+
|
|
105
|
+
Claude Code, Codex and the Antigravity CLI 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).
|
|
106
|
+
|
|
107
|
+
<!-- Checked against the adapters by tests/integration/collector/adapters/adapter.test.ts -->
|
|
108
|
+
|
|
109
|
+
| Agent | Needs you | Jump | Quiet for | Stop | Answer |
|
|
110
|
+
| --------------- | --------- | ------ | --------- | ------ | ------ |
|
|
111
|
+
| Claude Code | Yes | Partly | No | Partly | Partly |
|
|
112
|
+
| Codex | No | No | Yes | No | No |
|
|
113
|
+
| Antigravity CLI | Partly | No | Yes | No | No |
|
|
114
|
+
| Status files | Partly | No | Partly | No | No |
|
|
115
|
+
|
|
116
|
+
A Codex session waiting for approval shows as working, and so does an Antigravity CLI session waiting for an answer to a question. After 5 minutes its row says how long it has been quiet. An Antigravity CLI session needs you while agy asks you to approve a tool. Antigravity CLI support is new: it is built from what agy 1.3.1 documents and its program holds, and checked against one conversation. [What each agent can report](docs/GUIDE.md#what-each-agent-can-report) gives the reason for every Partly and No.
|
|
117
|
+
|
|
118
|
+
| | macOS | Linux | Windows |
|
|
119
|
+
| -------------------------------------------------- | ----- | ----- | ------- |
|
|
120
|
+
| Dashboard, `status`, `mcp`, email, webhook, pushes | Yes | Yes | Yes |
|
|
121
|
+
| Jump to VS Code | Yes | Yes | Yes |
|
|
122
|
+
| Jump to a tmux pane | Yes | Yes | No |
|
|
123
|
+
| Jump to Terminal or iTerm2 | Yes | No | No |
|
|
124
|
+
| Stop, and ending sessions left running | Yes | Yes | No |
|
|
125
|
+
| Allow and Deny, permission rules | Yes | Yes | No |
|
|
126
|
+
| Resume | Yes | Yes | No |
|
|
127
|
+
| Notifications with no tab open | Yes | No | No |
|
|
128
|
+
| Mac app and menu bar | Yes | No | No |
|
|
129
|
+
|
|
130
|
+
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)
|
|
131
|
+
|
|
132
|
+
## In the terminal
|
|
152
133
|
|
|
153
134
|
```sh
|
|
154
135
|
npx agent-lookout status
|
|
155
136
|
```
|
|
156
137
|
|
|
157
|
-
It prints, for example:
|
|
158
|
-
|
|
159
138
|
```text
|
|
160
139
|
2 need you · 3 working · 2 idle
|
|
161
140
|
checkout-flow Waiting for permission 4m 12s
|
|
162
141
|
search-indexing Asked you a question 31s
|
|
163
142
|
```
|
|
164
143
|
|
|
165
|
-
It exits with 0 when nothing needs you,
|
|
166
|
-
|
|
167
|
-
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.
|
|
168
|
-
|
|
169
|
-
## For your agents
|
|
144
|
+
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.
|
|
170
145
|
|
|
171
|
-
|
|
146
|
+
## MCP server
|
|
172
147
|
|
|
173
|
-
To add it to Claude Code for
|
|
148
|
+
`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:
|
|
174
149
|
|
|
175
150
|
```sh
|
|
176
151
|
claude mcp add --scope user agent-lookout -- npx -y agent-lookout mcp
|
|
177
152
|
```
|
|
178
153
|
|
|
179
|
-
|
|
154
|
+
<details>
|
|
155
|
+
<summary>Other apps that take MCP servers</summary>
|
|
180
156
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
157
|
+
```json
|
|
158
|
+
{
|
|
159
|
+
"mcpServers": {
|
|
160
|
+
"agent-lookout": { "command": "npx", "args": ["-y", "agent-lookout", "mcp"] }
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
```
|
|
184
164
|
|
|
185
|
-
|
|
165
|
+
</details>
|
|
186
166
|
|
|
187
|
-
|
|
188
|
-
AGENT_LOOKOUT_CLAUDE_FEED=off npx agent-lookout
|
|
189
|
-
```
|
|
167
|
+
[For your agents](docs/GUIDE.md#for-your-agents) covers a global install, Node installed with nvm, and another port.
|
|
190
168
|
|
|
191
|
-
|
|
192
|
-
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
193
|
-
| `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. |
|
|
194
|
-
| `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. |
|
|
195
|
-
| `AGENT_LOOKOUT_NOTIFICATIONS=on` | On a Mac, shows notifications of waits from the moment it starts, with no dashboard tab open. |
|
|
196
|
-
| `AGENT_LOOKOUT_CLAUDE_FEED=off` | Never runs the `claude` command. Sessions come from Claude Code's session files alone. |
|
|
197
|
-
| `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. |
|
|
198
|
-
| `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`. |
|
|
199
|
-
| `AGENT_LOOKOUT_STOP=off` | Takes away Stop and the ending of sessions left running. No session is ever stopped from Agent Lookout. |
|
|
200
|
-
| `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. |
|
|
169
|
+
## Settings
|
|
201
170
|
|
|
202
|
-
|
|
171
|
+
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.
|
|
203
172
|
|
|
204
173
|
## Privacy
|
|
205
174
|
|
|
206
|
-
By default Agent Lookout
|
|
175
|
+
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.
|
|
176
|
+
|
|
177
|
+
Each of these is off until you set it up:
|
|
207
178
|
|
|
208
|
-
-
|
|
209
|
-
-
|
|
210
|
-
-
|
|
211
|
-
-
|
|
212
|
-
-
|
|
213
|
-
-
|
|
214
|
-
- 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.
|
|
215
|
-
- `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.
|
|
216
|
-
- 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.
|
|
217
|
-
- 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.
|
|
179
|
+
- Email and the webhook, each to the one address you name.
|
|
180
|
+
- Pushes to your phone through ntfy, to the one topic you name, or Pushover, to the one user key you name.
|
|
181
|
+
- Pull requests, through your own `gh`, with `AGENT_LOOKOUT_PULL_REQUESTS=on`.
|
|
182
|
+
- Other machines, through your own `ssh`, named in `AGENT_LOOKOUT_REMOTES`.
|
|
183
|
+
- The MCP server, whose answers the agent's app hands to its model.
|
|
184
|
+
- The Claude Code plugin, which reaches Agent Lookout over a socket in `~/.agent-lookout`.
|
|
218
185
|
|
|
219
|
-
|
|
186
|
+
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.
|
|
187
|
+
|
|
188
|
+
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.
|
|
220
189
|
|
|
221
190
|
## What it does not do yet
|
|
222
191
|
|
|
223
|
-
- It
|
|
224
|
-
-
|
|
225
|
-
- Claude Code's
|
|
226
|
-
- The Mac app is not signed with an Apple Developer ID yet,
|
|
192
|
+
- It cannot send a session a message, and Resume only copies the command.
|
|
193
|
+
- Cloud sessions, Codex cloud tasks, browser chats and the Antigravity desktop app's conversations do not appear.
|
|
194
|
+
- Claude Code's and Codex's files are undocumented, and the Antigravity CLI's are documented only for its own agents, so an update can hide sessions. [What breaks when Codex changes](docs/adapters/codex.md#what-breaks-when-codex-changes), [and when Antigravity changes](docs/adapters/antigravity.md#what-breaks-when-antigravity-changes)
|
|
195
|
+
- The Mac app is not signed with an Apple Developer ID yet, and there is no Linux or Windows app.
|
|
196
|
+
|
|
197
|
+
[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.
|
|
227
198
|
|
|
228
|
-
|
|
199
|
+
## Questions
|
|
200
|
+
|
|
201
|
+
<details>
|
|
202
|
+
<summary>Can it act on a session without me?</summary>
|
|
203
|
+
|
|
204
|
+
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.
|
|
205
|
+
|
|
206
|
+
</details>
|
|
207
|
+
|
|
208
|
+
<details>
|
|
209
|
+
<summary>Why does a Codex session never show as needing me?</summary>
|
|
210
|
+
|
|
211
|
+
Its files do not record when it waits for your approval, as far as Agent Lookout can read, so watch the Quiet for line instead. An Antigravity CLI session does show as needing you while agy asks you to approve a tool, which agy's own log records, but not while it waits for an answer to a question.
|
|
212
|
+
|
|
213
|
+
</details>
|
|
214
|
+
|
|
215
|
+
<details>
|
|
216
|
+
<summary>Can I run the Mac app and npx together?</summary>
|
|
217
|
+
|
|
218
|
+
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.
|
|
219
|
+
|
|
220
|
+
</details>
|
|
229
221
|
|
|
230
222
|
## Documentation
|
|
231
223
|
|
|
232
|
-
|
|
|
233
|
-
|
|
|
234
|
-
|
|
|
235
|
-
|
|
|
236
|
-
|
|
|
237
|
-
|
|
|
238
|
-
|
|
|
239
|
-
|
|
|
240
|
-
|
|
|
241
|
-
|
|
|
224
|
+
| I want to | Read |
|
|
225
|
+
| ---------------------------------------------- | -------------------------------------------------------------------- |
|
|
226
|
+
| Install every way, update or stop it | [docs/INSTALL.md](docs/INSTALL.md) |
|
|
227
|
+
| Learn each part of the screen | [The screen](docs/GUIDE.md#the-screen) |
|
|
228
|
+
| Change a setting | [Settings you can change](docs/GUIDE.md#settings-you-can-change) |
|
|
229
|
+
| Fix a problem | [When something goes wrong](docs/GUIDE.md#when-something-goes-wrong) |
|
|
230
|
+
| Show my own agent | [Your own agents](docs/GUIDE.md#your-own-agents) |
|
|
231
|
+
| See every file it reads and all it can send | [PRIVACY.md](PRIVACY.md) |
|
|
232
|
+
| Know what it guards, or report a vulnerability | [SECURITY.md](SECURITY.md) |
|
|
233
|
+
| Call its local HTTP API | [docs/API.md](docs/API.md) |
|
|
234
|
+
| See how the parts fit together | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
|
|
235
|
+
| Write tests | [tests/README.md](tests/README.md) |
|
|
236
|
+
| Install or remove the Claude Code plugin | [plugins/agent-lookout/README.md](plugins/agent-lookout/README.md) |
|
|
237
|
+
| See what changed | [CHANGELOG.md](CHANGELOG.md) |
|
|
238
|
+
| See what is planned | [Milestones](https://github.com/Olanetsoft/agent-lookout/milestones) |
|
|
239
|
+
|
|
240
|
+
## For coding agents
|
|
241
|
+
|
|
242
|
+
To set Agent Lookout up for someone:
|
|
243
|
+
|
|
244
|
+
- 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`.
|
|
245
|
+
- `npx agent-lookout status --json` prints the counts and the sessions that need you, and exits with 0, 1 or 2 as above.
|
|
246
|
+
- `GET /api/sessions` lists every session. All routes answer on loopback only, and [docs/API.md](docs/API.md) lists them.
|
|
247
|
+
- Do not use `sudo`, and do not set up email, a webhook, phone pushes, pull requests or other machines unless asked.
|
|
248
|
+
|
|
249
|
+
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.
|
|
242
250
|
|
|
243
251
|
## Contributing
|
|
244
252
|
|
|
245
|
-
Bug reports, fixes and support for other agents are welcome.
|
|
253
|
+
Bug reports, fixes and support for other agents are welcome. Open an issue first for anything larger than a fix.
|
|
254
|
+
|
|
255
|
+
```sh
|
|
256
|
+
git clone https://github.com/Olanetsoft/agent-lookout.git
|
|
257
|
+
cd agent-lookout
|
|
258
|
+
npm install
|
|
259
|
+
npx playwright install chromium
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
`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.
|
|
263
|
+
|
|
264
|
+
```text
|
|
265
|
+
src/collector/ Node: finds sessions and serves them on 127.0.0.1
|
|
266
|
+
src/dashboard/ The React page
|
|
267
|
+
src/core/ Shared logic, with no DOM and no Node APIs
|
|
268
|
+
src/cli/ The agent-lookout command: start, status and mcp
|
|
269
|
+
src/desktop/ The Mac app's main process
|
|
270
|
+
plugins/agent-lookout/ The Claude Code plugin's hook
|
|
271
|
+
tests/ Every test, in unit/, integration/ and component/
|
|
272
|
+
site/ The website
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
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.
|
|
246
276
|
|
|
247
277
|
## License
|
|
248
278
|
|