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