agent-workbench 0.5.2 → 0.5.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/README.md +398 -390
- package/dist/server.js +69 -31
- package/dist/web/assets/{highlight-C6RpQUgN.js → highlight-BeEbartE.js} +1 -1
- package/dist/web/assets/index-D4OE_EfT.css +32 -0
- package/dist/web/assets/index-zFKk_FJ_.js +139 -0
- package/dist/web/index.html +2 -2
- package/package.json +1 -1
- package/dist/web/assets/index-CrEDljyV.js +0 -139
- package/dist/web/assets/index-zo2-uEwR.css +0 -32
package/README.md
CHANGED
|
@@ -3,10 +3,14 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/agent-workbench)
|
|
4
4
|
[](https://github.com/cvelasquez/agent-workbench/actions/workflows/ci.yml)
|
|
5
5
|
[](LICENSE)
|
|
6
|
+
[](https://github.com/hesreallyhim/awesome-claude-code)
|
|
6
7
|
|
|
7
|
-
**
|
|
8
|
-
|
|
9
|
-
|
|
8
|
+
**English** · [Español](https://github.com/cvelasquez/agent-workbench/blob/main/README.es.md) · [简体中文](https://github.com/cvelasquez/agent-workbench/blob/main/README.zh-CN.md) · [日本語](https://github.com/cvelasquez/agent-workbench/blob/main/README.ja.md) · [Português (Brasil)](https://github.com/cvelasquez/agent-workbench/blob/main/README.pt-BR.md) · [Русский](https://github.com/cvelasquez/agent-workbench/blob/main/README.ru.md) · [한국어](https://github.com/cvelasquez/agent-workbench/blob/main/README.ko.md) · [Français](https://github.com/cvelasquez/agent-workbench/blob/main/README.fr.md) · [Deutsch](https://github.com/cvelasquez/agent-workbench/blob/main/README.de.md)
|
|
9
|
+
|
|
10
|
+
**A visual workbench for the coding agents you already use: the Claude Code,
|
|
11
|
+
Codex, OpenCode and Antigravity CLIs.** It runs on your computer and opens in
|
|
12
|
+
your browser. It uses the CLIs you already have installed and logged in, never
|
|
13
|
+
touches your credentials, and makes no network calls of its own.
|
|
10
14
|
|
|
11
15
|
```bash
|
|
12
16
|
npx agent-workbench
|
|
@@ -14,89 +18,108 @@ npx agent-workbench
|
|
|
14
18
|
|
|
15
19
|
|
|
16
20
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
+
## How it works
|
|
22
|
+
|
|
23
|
+
Agent Workbench doesn't talk to any AI service. It starts the CLI you already
|
|
24
|
+
have —`claude`, `codex`, `opencode` or `agy`— inside a real terminal, and adds
|
|
25
|
+
around it what a terminal alone doesn't give you: tabs, your past
|
|
26
|
+
conversations, the conversation as easy-to-read cards, a context meter, the
|
|
27
|
+
files that changed and a file tree.
|
|
21
28
|
|
|
22
|
-
The terminal is still the terminal
|
|
23
|
-
|
|
29
|
+
The terminal is still the terminal: everything you type goes straight to the
|
|
30
|
+
CLI.
|
|
24
31
|
|
|
25
32
|
---
|
|
26
33
|
|
|
27
|
-
## What
|
|
34
|
+
## What you get
|
|
28
35
|
|
|
29
36
|
| | |
|
|
30
37
|
|---|---|
|
|
31
|
-
| **Tabs** | Several
|
|
32
|
-
| **
|
|
33
|
-
| **History** | Your projects and past conversations in the sidebar,
|
|
34
|
-
| **Conversation** | The
|
|
35
|
-
| **
|
|
36
|
-
| **
|
|
37
|
-
| **
|
|
38
|
-
| **
|
|
39
|
-
| **
|
|
40
|
-
| **
|
|
41
|
-
| **
|
|
42
|
-
| **
|
|
43
|
-
| **
|
|
44
|
-
| **
|
|
38
|
+
| **Tabs** | Several agents at once, from any CLI, each in its own folder. A dot on each tab tells you whether the agent is working, idle or waiting for you. Reloading the page doesn't stop anything: the CLIs run on the server, not in the browser. |
|
|
39
|
+
| **Fast start** | When you open the app, your tabs come back **asleep**: you can read them in full, and no CLI starts until you click **Open CLI**. |
|
|
40
|
+
| **History** | Your projects and past conversations in the sidebar, from every CLI, with a filter. Click one to pick it up where you left it, with its CLI. Archive old sessions or a whole project to tidy up: nothing is deleted, and it can be undone. |
|
|
41
|
+
| **Conversation** | The messages as cards, live, with tool calls folded. Older messages load as you scroll up. Search, copy any message or code block, and jump back to your previous message (↑) or to the end (↓). A row at the bottom says when your message reached the CLI and whether the agent is still working. Depending on the CLI, you can answer the agent's questions right there. |
|
|
42
|
+
| **Message box** | Room to write, paste images, attach files, and long pasted text kept as a tidy chip. What you're typing survives closing the app, and shows up live in every open window. |
|
|
43
|
+
| **Context meter** | How much of the model's context window the conversation is using. Tokens, never money. |
|
|
44
|
+
| **Changes** | The branch, the changed files and their diff. **Read-only**: no commit or push buttons. |
|
|
45
|
+
| **Files** | The project's file tree, with search and a preview with syntax highlighting. Open several files at once, each in its own tab; Markdown files open formatted. One click puts a file's path in your message. |
|
|
46
|
+
| **Plans** | The plans and `.md` documents the conversation wrote, rendered. |
|
|
47
|
+
| **Notes** | A scratchpad next to the conversation, images included. With Claude Code, one click sends a note to a new conversation. |
|
|
48
|
+
| **Console** | Your system's terminal at the bottom, in the project's folder: PowerShell, cmd or Git Bash on Windows; bash or zsh on macOS and Linux. |
|
|
49
|
+
| **Continue with…** | With more than one CLI, continue a conversation with another one in the same folder. The new agent starts from a transcript of the last turns. |
|
|
50
|
+
| **Notifications** | A sound, and optional system notifications, when an agent finishes or is waiting for you. |
|
|
51
|
+
| **Settings** | ⚙ in the header: the language, the terminal's theme, which panels show, which console opens and which CLIs the app uses. |
|
|
52
|
+
| **Nine languages** | English, Español, 简体中文, 日本語, Português (Brasil), Русский, 한국어, Français and Deutsch. It follows your browser's language. |
|
|
53
|
+
| **Theme** | Light, dark or the system's. The terminal stays dark by default, so the CLIs' colors stay readable. |
|
|
54
|
+
|
|
55
|
+
Optional, and off by default: [shared memory](#shared-memory-between-clis)
|
|
56
|
+
between CLIs, a [backup](#backup-of-your-history) of your history,
|
|
57
|
+
[remote access](#remote-access-over-ssh) from another computer or a phone, and
|
|
58
|
+
an [Android app](#the-android-app).
|
|
45
59
|
|
|
46
60
|
<p>
|
|
47
61
|
<img src="https://raw.githubusercontent.com/cvelasquez/agent-workbench/main/assets/captura-cambios.png" width="49%" alt="The Changes panel: branch and changed files, by group">
|
|
48
62
|
<img src="https://raw.githubusercontent.com/cvelasquez/agent-workbench/main/assets/captura-diff.png" width="49%" alt="The diff of one of those files, in the same panel">
|
|
49
63
|
</p>
|
|
50
64
|
|
|
51
|
-
###
|
|
65
|
+
### With more than one CLI
|
|
52
66
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
67
|
+
Each session and each tab shows a small badge with its CLI, and the `+` for a
|
|
68
|
+
new tab lets you pick which one to open. With a single CLI you see none of
|
|
69
|
+
this.
|
|
56
70
|
|
|
57
71
|
<img src="https://raw.githubusercontent.com/cvelasquez/agent-workbench/main/assets/captura-clis.png" width="45%" alt="The projects sidebar with sessions from several CLIs, each with its badge, and the + menu with the four CLIs and their versions">
|
|
58
72
|
|
|
59
|
-
**Not every CLI
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
73
|
+
**Not every CLI shares the same information**, so a few features depend on the
|
|
74
|
+
CLI:
|
|
75
|
+
|
|
76
|
+
| | Claude Code | Codex | OpenCode | Antigravity CLI |
|
|
77
|
+
|---|:---:|:---:|:---:|:---:|
|
|
78
|
+
| Tab dot: working, idle, waiting for you | ✓ | — | ✓ ¹ | ✓ ² |
|
|
79
|
+
| Answer the agent's questions from the conversation | ✓ | — | ✓ ¹ | — |
|
|
80
|
+
| Context meter | ✓ | ✓ | ✓ | ✓ ² |
|
|
81
|
+
| Mode and model pickers | ✓ | — | — | ✓ |
|
|
82
|
+
| Paste images | ✓ | ✓ | ✓ | — |
|
|
83
|
+
| Plans tab | ✓ | — | — | — |
|
|
84
|
+
| Send a note to a new conversation | ✓ | — | — | — |
|
|
85
|
+
|
|
86
|
+
The CLI's own terminal is always there for the rest: where there's a "—",
|
|
87
|
+
questions, for example, are answered in it.
|
|
88
|
+
|
|
89
|
+
¹ With OpenCode, the app starts a local OpenCode server to get this
|
|
90
|
+
([details](#your-data-and-security)).
|
|
91
|
+
² Only if you set up its status line
|
|
92
|
+
([how](#antigravity-cli-status-and-context-meter)).
|
|
68
93
|
|
|
69
94
|
---
|
|
70
95
|
|
|
71
96
|
## Requirements
|
|
72
97
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
98
|
+
- **Node.js 20 or later.** To see OpenCode's history and Antigravity CLI's
|
|
99
|
+
conversation titles, **22.13 or later**: they're read with the SQLite built
|
|
100
|
+
into Node since that version. With an older one, everything else works.
|
|
101
|
+
- **git**, for the Changes panel. Everything else works without it.
|
|
102
|
+
- **At least one CLI**, installed and logged in:
|
|
78
103
|
|
|
79
|
-
| CLI | Command |
|
|
104
|
+
| CLI | Command | How to install |
|
|
80
105
|
|---|---|---|
|
|
81
106
|
| Claude Code | `claude` | [installation guide](https://docs.claude.com/en/docs/claude-code/setup) |
|
|
82
107
|
| Codex | `codex` | [guide](https://learn.chatgpt.com/docs/codex/cli) |
|
|
83
108
|
| OpenCode | `opencode` | [documentation](https://opencode.ai/docs/) |
|
|
84
|
-
| Antigravity CLI | `agy` | [guide](https://antigravity.google/docs/cli/getting-started)
|
|
109
|
+
| Antigravity CLI | `agy` | [guide](https://antigravity.google/docs/cli/getting-started) |
|
|
85
110
|
|
|
86
|
-
Agent Workbench
|
|
87
|
-
|
|
88
|
-
open sessions.
|
|
111
|
+
Agent Workbench doesn't include or download any CLI: it finds the ones in your
|
|
112
|
+
`PATH`. If there are none, it tells you so and doesn't open sessions.
|
|
89
113
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
(`build-essential` on Debian and Ubuntu).
|
|
114
|
+
**Platforms.** Built and used every day on Windows 11 with PowerShell. On macOS
|
|
115
|
+
and Linux, every change is installed and started automatically, but they get
|
|
116
|
+
less daily use: reports are welcome. On Linux, installing compiles the terminal
|
|
117
|
+
module, so you need `python3`, `make` and a C++ compiler (`build-essential` on
|
|
118
|
+
Debian and Ubuntu).
|
|
96
119
|
|
|
97
120
|
---
|
|
98
121
|
|
|
99
|
-
## Install
|
|
122
|
+
## Install and start
|
|
100
123
|
|
|
101
124
|
```bash
|
|
102
125
|
npm install -g agent-workbench
|
|
@@ -108,110 +131,143 @@ Then, from the folder of the project you want to work on:
|
|
|
108
131
|
agent-workbench
|
|
109
132
|
```
|
|
110
133
|
|
|
111
|
-
|
|
112
|
-
60 MB whenever the npm cache is cold, mostly the terminal's native binary. For
|
|
113
|
-
daily use, the global install is the better choice.
|
|
114
|
-
|
|
115
|
-
The server prints a URL with a token and opens it in the browser:
|
|
134
|
+
It opens your browser at an address like this one:
|
|
116
135
|
|
|
117
136
|
```
|
|
118
137
|
URL http://127.0.0.1:52341/?token=…
|
|
119
138
|
```
|
|
120
139
|
|
|
121
|
-
That
|
|
122
|
-
|
|
140
|
+
That address is the only way in: the token changes on every start, and the app
|
|
141
|
+
only listens on your own computer (`127.0.0.1`).
|
|
142
|
+
|
|
143
|
+
To try it once without installing: `npx agent-workbench`. It downloads about
|
|
144
|
+
60 MB the first time, mostly the terminal's native module. For everyday use,
|
|
145
|
+
the global install is better.
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## Keyboard shortcuts
|
|
150
|
+
|
|
151
|
+
| Keys | Action |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `Alt+T` | New tab |
|
|
154
|
+
| `Alt+W` | Close the tab |
|
|
155
|
+
| `Alt+←` / `Alt+→` (or `Alt+PgUp` / `Alt+PgDn`) | Previous / next tab |
|
|
156
|
+
| `Alt+P` | Show or hide the right panel |
|
|
157
|
+
| `Shift+Tab`, outside the terminal | Back to the previous tab |
|
|
158
|
+
|
|
159
|
+
The `?` button in the header lists them all, along with the active CLI's own
|
|
160
|
+
shortcuts. They use `Alt` because the browser keeps `Ctrl+T`, `Ctrl+W` and
|
|
161
|
+
`Ctrl+Tab` for its own tabs and never passes them to the page.
|
|
162
|
+
|
|
163
|
+
Every other key —`Esc`, `Ctrl+C`, `Ctrl+R`, `Ctrl+O`, the arrows, `Alt+V` to
|
|
164
|
+
paste images— reaches the CLI untouched. `Ctrl+V` too: what it does there is up
|
|
165
|
+
to the CLI. Only in the console at the bottom, on Windows, `Ctrl+V` pastes text,
|
|
166
|
+
as in Windows Terminal.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## Optional extras
|
|
123
171
|
|
|
124
|
-
### Shared memory
|
|
172
|
+
### Shared memory between CLIs
|
|
125
173
|
|
|
126
|
-
Each CLI keeps what it learns about a project in its own
|
|
127
|
-
can't see it. The **Memory** tab
|
|
128
|
-
|
|
129
|
-
|
|
174
|
+
Each CLI keeps what it learns about a project in its own place, and the others
|
|
175
|
+
can't see it. The **Memory** tab sets up one memory for all four: notes in the
|
|
176
|
+
project's `.agents/memory/` folder, which every CLI reads and writes —from here
|
|
177
|
+
or from its own terminal— through `AGENTS.md` and `CLAUDE.md`. The tab is hidden
|
|
178
|
+
at first: show it from ⚙ Settings.
|
|
130
179
|
|
|
131
|
-
**Preview changes** shows, file by file, what
|
|
132
|
-
touched until you confirm.
|
|
133
|
-
for that project. The app doesn't
|
|
134
|
-
the snippet to paste yourself.
|
|
180
|
+
**Preview changes** shows, file by file, what would be written, and nothing is
|
|
181
|
+
touched until you confirm. Setting it up imports the memory Claude Code already
|
|
182
|
+
had for that project. The app doesn't edit each CLI's global settings: it gives
|
|
183
|
+
you the snippet to paste yourself.
|
|
135
184
|
|
|
136
185
|
<img src="https://raw.githubusercontent.com/cvelasquez/agent-workbench/main/assets/captura-memoria.png" width="70%" alt="The Memory tab with the bridge installed for the four CLIs and the imported notes">
|
|
137
186
|
|
|
138
|
-
###
|
|
187
|
+
### Backup of your history
|
|
139
188
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
unknown and the meter stays empty. To turn it on:
|
|
189
|
+
Each CLI owns its history, and it can change its format, prune it, or be
|
|
190
|
+
uninstalled. The backup keeps a copy of your conversations —messages, tool
|
|
191
|
+
calls and results, images, and each project's memory— in a folder of yours, in
|
|
192
|
+
files you can read without the app.
|
|
145
193
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
or with **Check**.
|
|
152
|
-
|
|
153
|
-
The line runs a script the app keeps in its own folder. It saves only each
|
|
154
|
-
conversation's status, mode, model and tokens, in that same folder; it doesn't
|
|
155
|
-
save your email, quota, plan or cost, which the CLI also passes to it, and it
|
|
156
|
-
prints nothing, so the CLI's own status line stays as it is. Once set, **every**
|
|
157
|
-
`agy` session runs it, including those you open outside the app, and it needs
|
|
158
|
-
`node` in the `PATH`. On Windows the line changes into the script's folder
|
|
159
|
-
instead of naming the script in quotes: the CLI runs it with `cmd /c`, and no
|
|
160
|
-
quote reaches `node` intact.
|
|
161
|
-
|
|
162
|
-
### Backup (optional)
|
|
163
|
-
|
|
164
|
-
Each conversation's history belongs to its CLI, in its format, and a CLI can
|
|
165
|
-
change it, prune it or cease to exist. The backup keeps the same as that
|
|
166
|
-
history —messages, tool inputs and results, images and each project's memory—
|
|
167
|
-
in a folder of yours, in files you can read without the app. **It's off by
|
|
168
|
-
default.** The backup button, in the header of the projects sidebar, opens a
|
|
169
|
-
dialog: first **Measure** tells you how much space it would take per CLI,
|
|
170
|
-
without writing anything, and then **Turn on** enables it. Once on, it copies
|
|
171
|
-
everything the sidebar lists that isn't archived, and copies each session that
|
|
172
|
-
changes again a minute after it goes quiet. Archived sessions aren't copied, and
|
|
173
|
-
archiving doesn't delete what was already copied: the app never deletes anything
|
|
194
|
+
**It's off by default.** Open it with the backup button at the top of the
|
|
195
|
+
projects sidebar, or from ⚙ Settings. **Measure** tells you how much space it
|
|
196
|
+
would take per CLI, without writing anything, and **Turn on** starts it. From
|
|
197
|
+
then on it copies everything in the sidebar that isn't archived, and copies a
|
|
198
|
+
conversation again a minute after it stops changing. It never deletes anything
|
|
174
199
|
from that folder.
|
|
175
200
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
201
|
+
With the backup on:
|
|
202
|
+
|
|
203
|
+
- Conversations a CLI no longer has stay in the sidebar, marked as backup, and
|
|
204
|
+
open as Markdown.
|
|
205
|
+
- Any project can be exported to Markdown.
|
|
206
|
+
- With more than one CLI, the sidebar filter can search **In conversations**:
|
|
207
|
+
the text of everything copied, from every CLI.
|
|
180
208
|
|
|
181
209
|
<img src="https://raw.githubusercontent.com/cvelasquez/agent-workbench/main/assets/captura-buscador.png" width="40%" alt="Search in conversations: a match in one session of each CLI, with its snippet">
|
|
182
210
|
|
|
183
|
-
By default it lives
|
|
184
|
-
(`%APPDATA%\agent-workbench\vault` on Windows). **Change folder…** copies
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
211
|
+
By default it lives in the app's configuration folder
|
|
212
|
+
(`%APPDATA%\agent-workbench\vault` on Windows). **Change folder…** copies it to
|
|
213
|
+
another one —a synced folder, another drive— without overwriting anything, and
|
|
214
|
+
leaves the old one as it was. If you put it in a synced folder or a repository,
|
|
215
|
+
your conversations go with it.
|
|
216
|
+
|
|
217
|
+
<details>
|
|
218
|
+
<summary>Importing history from Gemini CLI and the Antigravity IDE</summary>
|
|
188
219
|
|
|
189
|
-
Two one-
|
|
190
|
-
from source ([below](#from-source)) and **write nothing without
|
|
191
|
-
without it, they tell you what they would import.
|
|
220
|
+
Two one-time importers bring in history from tools the app doesn't read. They
|
|
221
|
+
run from the source code ([below](#from-source)) and **write nothing without
|
|
222
|
+
`--write`**: without it, they only tell you what they would import.
|
|
192
223
|
|
|
193
224
|
- `pnpm vault:import gemini-cli [--cwd <folder>]` — the chats left over from
|
|
194
|
-
Gemini CLI
|
|
225
|
+
Gemini CLI. `--cwd` is the folder where you used it, to file them under that
|
|
195
226
|
project.
|
|
196
|
-
- `pnpm vault:import antigravity-ide --workspace <folder>` —
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
227
|
+
- `pnpm vault:import antigravity-ide --workspace <folder>` — what can be read
|
|
228
|
+
from the Antigravity IDE conversations in that folder: each one's summary and
|
|
229
|
+
its `.md` documents. The conversation itself is encrypted, so it's marked as
|
|
230
|
+
partial history.
|
|
200
231
|
|
|
201
|
-
|
|
232
|
+
</details>
|
|
202
233
|
|
|
203
|
-
|
|
204
|
-
one on the same network, in its browser — with no CLI installed there.
|
|
205
|
-
**The app is never opened to the network**: it keeps listening only on
|
|
206
|
-
`127.0.0.1`, and the other computer reaches it through an SSH tunnel. That's
|
|
207
|
-
also what makes it work: through the tunnel the other browser sees the app as
|
|
208
|
-
`localhost`, and outside `localhost` browsers switch off things the app needs
|
|
209
|
-
(the clipboard, notifications, `crypto.randomUUID`). **It's off by default.**
|
|
234
|
+
### Antigravity CLI: status and context meter
|
|
210
235
|
|
|
211
|
-
|
|
212
|
-
|
|
236
|
+
Antigravity CLI only tells whether it's working or waiting for you, and how
|
|
237
|
+
many tokens it has used, through its *status line*. Without it, its tabs work
|
|
238
|
+
normally, but the tab's dot says the status is unknown and the meter stays
|
|
239
|
+
empty. To turn it on:
|
|
213
240
|
|
|
214
|
-
|
|
241
|
+
1. Open an Antigravity tab and click **Configure**, next to the meter.
|
|
242
|
+
2. Copy the line it shows and add it to what
|
|
243
|
+
`~/.gemini/antigravity-cli/settings.json` already has. The app doesn't edit
|
|
244
|
+
that file: you do.
|
|
245
|
+
3. Within a couple of seconds, or with **Check**, the dialog says
|
|
246
|
+
**Configured**.
|
|
247
|
+
|
|
248
|
+
The line runs a small script kept in the app's own folder. It saves only each
|
|
249
|
+
conversation's status, mode, model and tokens —not your email, quota, plan or
|
|
250
|
+
cost, which the CLI also passes to it— and prints nothing, so the CLI's own
|
|
251
|
+
status line stays as it was. Once set, it runs on **every** `agy` session,
|
|
252
|
+
including the ones you open outside the app, and it needs `node` in the
|
|
253
|
+
`PATH`.
|
|
254
|
+
|
|
255
|
+
### Remote access over SSH
|
|
256
|
+
|
|
257
|
+
Leave Agent Workbench running on one computer and use it from another one on
|
|
258
|
+
your network, in its browser, with no CLI installed there. **The app is never
|
|
259
|
+
opened to the network**: it still listens only on `127.0.0.1`, and the other
|
|
260
|
+
computer reaches it through an SSH tunnel. The tunnel is also what makes it
|
|
261
|
+
work: through it the other browser sees the app as `localhost`, which browsers
|
|
262
|
+
require for the clipboard and notifications. **It's off by default.**
|
|
263
|
+
|
|
264
|
+
**1. On the computer that runs the app, once: turn on its SSH server.** It's a
|
|
265
|
+
system change that needs administrator rights, so the app doesn't do it for
|
|
266
|
+
you.
|
|
267
|
+
|
|
268
|
+
- **Windows 10/11** — in PowerShell *as administrator*. The first line downloads
|
|
269
|
+
and installs the server and takes a few minutes: wait until the prompt comes
|
|
270
|
+
back.
|
|
215
271
|
|
|
216
272
|
```powershell
|
|
217
273
|
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
|
|
@@ -219,93 +275,87 @@ doesn't do this for you — it's a system change that needs administrator rights
|
|
|
219
275
|
Set-Service -Name sshd -StartupType Automatic
|
|
220
276
|
```
|
|
221
277
|
|
|
222
|
-
The first line downloads and installs the server: it takes a few minutes and
|
|
223
|
-
shows "Running" meanwhile. Wait until the prompt comes back.
|
|
224
|
-
|
|
225
278
|
- **macOS** — System Settings → General → Sharing → **Remote Login**.
|
|
226
|
-
- **Linux** — install and
|
|
227
|
-
|
|
279
|
+
- **Linux** — install and turn on your distribution's OpenSSH server. On Debian
|
|
280
|
+
or Ubuntu:
|
|
228
281
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
282
|
+
```bash
|
|
283
|
+
sudo apt install openssh-server
|
|
284
|
+
sudo systemctl enable --now ssh
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
**2. In the app: ⇄ in the header → Turn on remote access, then restart Agent
|
|
288
|
+
Workbench.** The tunnel needs a port that doesn't change, so the app uses a
|
|
289
|
+
fixed one (24837 by default; you can change it), and the port is chosen at
|
|
290
|
+
startup. Restarting closes the open CLIs; your tabs come back asleep. Turning
|
|
291
|
+
it *off* works right away.
|
|
235
292
|
|
|
236
|
-
**3. On the other computer,
|
|
293
|
+
**3. On the other computer, each time: open the tunnel.** The dialog shows the
|
|
237
294
|
command ready to copy:
|
|
238
295
|
|
|
239
296
|
```
|
|
240
297
|
ssh -N -L 24837:127.0.0.1:24837 you@your-computer
|
|
241
298
|
```
|
|
242
299
|
|
|
243
|
-
Leave it running
|
|
244
|
-
|
|
300
|
+
Leave it running, and **use the same port on both ends**: with a different
|
|
301
|
+
local port the app answers 403. Adding
|
|
245
302
|
`-o ServerAliveInterval=30 -o ExitOnForwardFailure=yes` makes the tunnel notice
|
|
246
|
-
a dropped Wi‑Fi instead of hanging. On Windows you can save the
|
|
303
|
+
a dropped Wi‑Fi instead of hanging. On Windows you can save the command in a
|
|
247
304
|
`.cmd` file and double-click it.
|
|
248
305
|
|
|
249
|
-
**4. Pair that computer, once.** In the dialog, **Pair a device**
|
|
250
|
-
address with a one-time code,
|
|
251
|
-
|
|
252
|
-
browser
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
306
|
+
**4. Pair that computer, once.** In the dialog, **Pair a device** gives you an
|
|
307
|
+
address with a one-time code, like `http://localhost:24837/?pair=K7QM-X2RD`.
|
|
308
|
+
Open it in the other computer's browser within five minutes. From then on, that
|
|
309
|
+
browser just opens `http://localhost:24837`, even after the app restarts. The
|
|
310
|
+
dialog lists the paired devices, and **Revoke** cuts one off at once.
|
|
311
|
+
|
|
312
|
+
A paired device can use the whole app, except managing remote access and the
|
|
313
|
+
few things that would open a window on the host computer, like *Open with the
|
|
314
|
+
default app*. A **Remote** badge in the header shows it. Keep in mind that the
|
|
315
|
+
app includes a console and launches agents, so a paired device can run commands
|
|
316
|
+
on your computer, just as you can. **Pair only devices that are yours.**
|
|
317
|
+
|
|
318
|
+
**On a phone or tablet.** Through the same tunnel, a phone's browser gets a
|
|
319
|
+
one-column layout: the projects sidebar slides in from the side, the tabs sit
|
|
320
|
+
in the header, and a strip switches between the conversation, the CLI, changes,
|
|
321
|
+
files and the rest. It appears on any window narrower than 768 px. On a touch
|
|
322
|
+
screen, Enter in the message box starts a new line (the send button sends), and
|
|
323
|
+
dragging a finger over a terminal scrolls it.
|
|
324
|
+
|
|
325
|
+
<details>
|
|
326
|
+
<summary>A safer SSH key, only good for the tunnel (recommended)</summary>
|
|
327
|
+
|
|
328
|
+
The SSH login is your user's on that computer, so a password or key that opens
|
|
329
|
+
the tunnel also opens a full terminal there. You can create a key that is only
|
|
330
|
+
good for the tunnel: generate one on the other computer
|
|
331
|
+
(`ssh-keygen -t ed25519`) and add its public half to `authorized_keys` on the
|
|
332
|
+
computer that runs the app, with these options in front:
|
|
271
333
|
|
|
272
334
|
```
|
|
273
335
|
restrict,port-forwarding,permitopen="127.0.0.1:24837",command="exit" ssh-ed25519 AAAA… other-computer
|
|
274
336
|
```
|
|
275
337
|
|
|
276
|
-
`restrict`
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
`C:\ProgramData\ssh\administrators_authorized_keys` and it must be writable
|
|
338
|
+
`restrict` alone still lets the key run commands; `command="exit"` is what
|
|
339
|
+
closes that door, and the tunnel never asks for a command. On Windows, if your
|
|
340
|
+
user is an administrator, that file is
|
|
341
|
+
`C:\ProgramData\ssh\administrators_authorized_keys`, and it must be writable
|
|
281
342
|
only by Administrators and SYSTEM; otherwise it's
|
|
282
|
-
`%USERPROFILE%\.ssh\authorized_keys`. To check
|
|
343
|
+
`%USERPROFILE%\.ssh\authorized_keys`. To check it, try
|
|
283
344
|
`ssh you@your-computer whoami` with that key: it should print nothing and end
|
|
284
345
|
at once, while the `-N -L` tunnel keeps working.
|
|
285
346
|
|
|
286
|
-
|
|
287
|
-
single-column layout: the projects sidebar as a drawer, the tabs in the header,
|
|
288
|
-
and a strip that switches between the conversation, the CLI, changes, files and
|
|
289
|
-
the rest. It appears on any window narrower than 768 px (a tablet held upright, too).
|
|
290
|
-
On a touch screen, Enter in the message box starts a new line (the send button
|
|
291
|
-
sends), and dragging a finger over a terminal scrolls it like a mouse wheel.
|
|
292
|
-
|
|
293
|
-
**Notifications.** The bell button in the header turns on system notifications:
|
|
294
|
-
"finished" and "is waiting for you", with the tab's name, only when the window
|
|
295
|
-
isn't in view. They follow the same rule as the notification sound, so they
|
|
296
|
-
come from the CLIs that publish their status. Each browser remembers its own
|
|
297
|
-
choice, and the sound plays on every screen that has the app open.
|
|
347
|
+
</details>
|
|
298
348
|
|
|
299
|
-
### The Android app
|
|
349
|
+
### The Android app
|
|
300
350
|
|
|
301
351
|
An app for Android 10 and later opens the tunnel for you and shows the same
|
|
302
|
-
interface, served by your computer, in the phone
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
352
|
+
interface, served by your computer, in the phone layout. It stays connected in
|
|
353
|
+
the background and notifies you when an agent finishes or is waiting for you,
|
|
354
|
+
even with the screen off; tapping a notification opens that tab. When the Wi‑Fi
|
|
355
|
+
comes back, it reconnects on its own.
|
|
306
356
|
|
|
307
357
|
It needs remote access on and the computer's SSH server running (steps 1 and 2
|
|
308
|
-
above).
|
|
358
|
+
above). Get it on
|
|
309
359
|
[Google Play](https://play.google.com/store/apps/details?id=io.github.cvelasquez.agentworkbench),
|
|
310
360
|
or build it yourself from [`android/`](android/) as
|
|
311
361
|
[`CONTRIBUTING.md`](CONTRIBUTING.md#the-android-app) explains.
|
|
@@ -315,18 +365,17 @@ or build it yourself from [`android/`](android/) as
|
|
|
315
365
|
1. In the ⇄ dialog, choose **Pair a phone**. It shows a line to paste in a
|
|
316
366
|
terminal on this computer, and a QR code. On Windows, if your user is an
|
|
317
367
|
administrator, the line goes in PowerShell *as administrator*; the dialog
|
|
318
|
-
|
|
319
|
-
2. Paste the line. It
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
tells you.
|
|
368
|
+
tells you.
|
|
369
|
+
2. Paste the line. It authorizes the phone's key for the tunnel only: with it,
|
|
370
|
+
the phone reaches the app and nothing else — no terminal, no commands.
|
|
371
|
+
3. Scan the QR code with the app. The code works once and for five minutes, and
|
|
372
|
+
the dialog has to stay open until the phone connects.
|
|
373
|
+
|
|
374
|
+
The QR code carries the phone's private SSH key. Your computer keeps it only in
|
|
375
|
+
memory until the phone uses it and never writes it to disk: **don't share a
|
|
376
|
+
picture of that QR code**. The phone remembers your computer's SSH fingerprint
|
|
377
|
+
on the first connection, and if it ever changes, it refuses to connect and tells
|
|
378
|
+
you.
|
|
330
379
|
|
|
331
380
|
**To remove a phone**, **Revoke** it in the dialog and delete its line from
|
|
332
381
|
`authorized_keys` (it ends in `agent-workbench-phone`). On the phone,
|
|
@@ -339,132 +388,83 @@ app keeps on the phone and the permissions it asks for are in
|
|
|
339
388
|
|
|
340
389
|
---
|
|
341
390
|
|
|
342
|
-
##
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
it
|
|
367
|
-
|
|
368
|
-
---
|
|
369
|
-
|
|
370
|
-
## Keyboard shortcuts
|
|
371
|
-
|
|
372
|
-
`Alt+T` new tab · `Alt+W` close · `Alt+←/→` (or `Alt+PgUp/PgDn`) switch tabs ·
|
|
373
|
-
`Alt+P` show or hide the right panel · `Shift+Tab`, outside the terminal, go
|
|
374
|
-
back to the previous tab.
|
|
375
|
-
|
|
376
|
-
The `?` button in the top bar lists them all, along with the shortcuts of the
|
|
377
|
-
tab's CLI.
|
|
378
|
-
|
|
379
|
-
**Why `Alt` and not `Ctrl`:** the browser keeps `Ctrl+T`, `Ctrl+W` and
|
|
380
|
-
`Ctrl+Tab` for its own tabs and the event never reaches the page. It's not
|
|
381
|
-
something `preventDefault` can fix: there's no event to prevent.
|
|
382
|
-
|
|
383
|
-
The app captures exactly those combinations and no others. `Shift+Tab` only
|
|
384
|
-
when focus isn't on the terminal, because inside it's the key the CLI uses to
|
|
385
|
-
switch modes. Everything else —`Esc`, `Esc Esc`, `Ctrl+C`, `Ctrl+R`, `Ctrl+O`,
|
|
386
|
-
the arrow keys and above all `Alt+V`, which pastes images— reaches the CLI
|
|
387
|
-
untouched. `Ctrl+V` too: what it does there is up to the CLI. Only in the
|
|
388
|
-
console at the bottom, on Windows, `Ctrl+V` pastes text, as in Windows
|
|
389
|
-
Terminal.
|
|
390
|
-
|
|
391
|
-
---
|
|
392
|
-
|
|
393
|
-
## What the app does with your data
|
|
394
|
-
|
|
395
|
-
Nothing leaves your machine. No telemetry, no analytics, no outgoing network
|
|
396
|
-
calls at all. The exception is the CLI itself at work: the one you open in a
|
|
397
|
-
tab, and the OpenCode server described below, talk to the model provider just
|
|
398
|
-
as they would if you opened them by hand. The Android app talks only to your
|
|
399
|
-
computer; [`PRIVACY.md`](PRIVACY.md) lists what it keeps on the phone.
|
|
400
|
-
|
|
401
|
-
**It never touches your credentials.** There's no login in the interface: if
|
|
402
|
-
you aren't logged in, you log in inside the CLI's terminal and the app doesn't
|
|
403
|
-
even notice.
|
|
391
|
+
## Your data and security
|
|
392
|
+
|
|
393
|
+
- **Nothing leaves your computer.** No telemetry, no analytics, no network calls
|
|
394
|
+
of its own. Only the CLIs talk to their AI provider, just as they would if you
|
|
395
|
+
opened them by hand. The Android app talks only to your computer.
|
|
396
|
+
- **It never touches your credentials.** There's no login screen: if a CLI asks
|
|
397
|
+
you to log in, you do it in its own terminal, and the app doesn't even notice.
|
|
398
|
+
- **It reads the CLIs' history and writes nothing in their folders.** The table
|
|
399
|
+
below lists what it reads and what it never opens.
|
|
400
|
+
- **It writes only in its own folders**, plus one thing in your projects, and
|
|
401
|
+
only if you confirm it: the shared memory.
|
|
402
|
+
- **The server listens only on your computer** (`127.0.0.1`), on a random port,
|
|
403
|
+
with a new random token on every start, and it rejects requests coming from
|
|
404
|
+
other web pages. Remote access doesn't change that: the port becomes a fixed
|
|
405
|
+
one, still on `127.0.0.1`, and SSH —which you turn on and control— does the
|
|
406
|
+
rest.
|
|
407
|
+
- **The Changes panel is read-only.** No commit, stage or push: with an agent
|
|
408
|
+
editing files, a button that writes history is exactly the kind of thing
|
|
409
|
+
where, later, nobody knows who pressed it.
|
|
410
|
+
|
|
411
|
+
| CLI | What it reads | What it never opens |
|
|
412
|
+
|---|---|---|
|
|
413
|
+
| Claude Code | From `~/.claude/`: `projects/` (the history, and each project's memory, to import it), `sessions/` (whether the CLI is waiting for you) and `plans/`. For the Plans tab, also the `.md` files the conversation wrote in the project or in that session's temp folder — **only the ones named by the conversation you're viewing**, without browsing any folder | `.credentials.json` or any token |
|
|
414
|
+
| Codex | From `~/.codex/` (or `CODEX_HOME`): `sessions/` and `archived_sessions/` | `auth.json`, `config.toml` or its `*.sqlite` databases |
|
|
415
|
+
| OpenCode | Its `opencode.db` database, opened read-only, and from it only the sessions, messages and parts; and its model catalog, for the context window size | `auth.json`, `opencode.json`, or the accounts, credentials, permissions and shared-sessions tables |
|
|
416
|
+
| Antigravity CLI | From `~/.gemini/antigravity-cli/`: each conversation's transcripts, `history.jsonl`, the last conversation of each folder, the model and status line from `settings.json`, and a temporary **copy** of its conversation index; from `~/.gemini/config/projects/`, each project's folder | Its MCP configuration, its entry in the system keychain, the contents of `conversations/`, and `~/.gemini/antigravity/`, which is its IDE |
|
|
404
417
|
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
[
|
|
418
|
+
The [backup importers](#backup-of-your-history), when you run them, also read
|
|
419
|
+
what their section says. The full list, file by file, is in
|
|
420
|
+
[`ARCHITECTURE.md`](ARCHITECTURE.md#4-what-is-read-from-each-cli).
|
|
408
421
|
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
| Claude Code | from `~/.claude/`: `projects/` (the history, and each project's memory, to import it), `sessions/` (whether the CLI is waiting for an answer) and `plans/`. And for the Plans tab, the `.md` files the conversation wrote inside the project or in that session's temp folder: **only those named by the conversation you're viewing**, without walking any folder | `.credentials.json` or any token |
|
|
412
|
-
| Codex | from `~/.codex/` (or `CODEX_HOME`): `sessions/` and `archived_sessions/` | `auth.json`, `config.toml` or its `*.sqlite` databases |
|
|
413
|
-
| OpenCode | its `opencode.db` database, opened read-only, and from it only the sessions, messages and parts tables; and its model catalog, for the context window size | `auth.json`, `opencode.json`, or the accounts, credentials, permissions and shared-sessions tables |
|
|
414
|
-
| Antigravity CLI | from `~/.gemini/antigravity-cli/`: each conversation's transcripts, `history.jsonl`, the last conversation of each folder, from `settings.json` only the model and the status line, and its conversation index, from a temporary **copy**; from `~/.gemini/config/projects/`, each project's folder | the MCP configuration, its entry in the system keychain, the contents of `conversations/`, or `~/.gemini/antigravity/`, which is its IDE |
|
|
422
|
+
<details>
|
|
423
|
+
<summary>The fine print: footprints, environment variables and what the app writes</summary>
|
|
415
424
|
|
|
416
|
-
Three footprints worth knowing about
|
|
425
|
+
**Three footprints worth knowing about:**
|
|
417
426
|
|
|
418
427
|
- **Reading the OpenCode database** does what SQLite does with any reader: it
|
|
419
|
-
creates its `-wal` and `-shm` files if they're missing and updates the
|
|
420
|
-
|
|
421
|
-
- **If an Antigravity tab's own log doesn't show up**,
|
|
428
|
+
creates its `-wal` and `-shm` files if they're missing and updates the date of
|
|
429
|
+
`-shm`. The app never runs an OpenCode command to read it.
|
|
430
|
+
- **If an Antigravity tab's own log doesn't show up**, the app reads the CLI's
|
|
422
431
|
`log/cli-*.log` files, which contain your messages and the account's email,
|
|
423
|
-
only to find the conversation id, and without keeping any line.
|
|
424
|
-
- **With OpenCode, the app runs
|
|
425
|
-
from when you open the first OpenCode tab until five minutes after
|
|
426
|
-
the last one, or until you close the app. It listens on
|
|
427
|
-
|
|
428
|
-
configuration says otherwise. The app only asks it for the
|
|
429
|
-
pending permissions and questions, to create a session, to
|
|
430
|
-
and to
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
OpenCode tab gets
|
|
439
|
-
other
|
|
440
|
-
and stops
|
|
432
|
+
only to find the conversation's id, and without keeping any line.
|
|
433
|
+
- **With OpenCode, the app runs a local OpenCode server** (`opencode serve`):
|
|
434
|
+
just one, from when you open the first OpenCode tab until five minutes after
|
|
435
|
+
you close the last one, or until you close the app. It listens on
|
|
436
|
+
`127.0.0.1`, on a random port, with a different password on every start, even
|
|
437
|
+
if your OpenCode configuration says otherwise. The app only asks it for the
|
|
438
|
+
sessions' status, pending permissions and questions, to create a session, to
|
|
439
|
+
answer a question and to stop a session: nothing about your configuration or
|
|
440
|
+
your accounts.
|
|
441
|
+
|
|
442
|
+
**Environment variables.** The CLIs inherit your environment as it is, with no
|
|
443
|
+
login variables added. Two exceptions: the app **removes**
|
|
444
|
+
`CLAUDE_CODE_CHILD_SESSION` —which turns off history saving— and tells you with
|
|
445
|
+
a banner when it does; and it **adds** one variable to the OpenCode server,
|
|
446
|
+
`OPENCODE_SERVER_PASSWORD`, with that per-start password. It isn't any account's
|
|
447
|
+
password, and it doesn't reach any tab: each OpenCode tab gets it on its command
|
|
448
|
+
line (`attach --password`), where other programs running as your user can see
|
|
449
|
+
it. It only works for that server and stops working when you close the app.
|
|
441
450
|
|
|
442
451
|
**What the app writes:**
|
|
443
452
|
|
|
444
|
-
- **In its own configuration
|
|
445
|
-
notes, the archived sessions, the Antigravity status line
|
|
446
|
-
turn it on, the backup (or in the folder you choose). With
|
|
447
|
-
on, also the list of paired devices: a name, two dates and a
|
|
448
|
-
one's credential — never the credential itself.
|
|
449
|
-
- **In the temp folder:** the images you paste; each
|
|
450
|
-
which contains your messages, readable only by you and
|
|
451
|
-
start
|
|
452
|
-
you continue
|
|
453
|
-
hours.
|
|
453
|
+
- **In its own configuration folder:** the open tabs, the index cache, the
|
|
454
|
+
notes, the archived sessions, unsent messages, the Antigravity status line
|
|
455
|
+
script and, if you turn it on, the backup (or in the folder you choose). With
|
|
456
|
+
remote access on, also the list of paired devices: a name, two dates and a
|
|
457
|
+
hash of each one's credential — never the credential itself.
|
|
458
|
+
- **In the temp folder:** the images and files you paste or attach; each
|
|
459
|
+
Antigravity tab's log, which contains your messages, readable only by you and
|
|
460
|
+
deleted on the first start after it's 24 hours old; and the transcript of a
|
|
461
|
+
conversation you continue with another CLI, deleted when you close that tab
|
|
462
|
+
or after 24 hours.
|
|
454
463
|
- **In your projects, one thing only, and only if you confirm:** the shared
|
|
455
464
|
memory. It's limited to `.agents/memory/`, to what's between its markers in
|
|
456
465
|
`AGENTS.md` and `CLAUDE.md`, and to a few lines at the end of `.gitignore`.
|
|
457
466
|
|
|
458
|
-
|
|
459
|
-
per-start token that the WebSocket and every HTTP route require, and it rejects
|
|
460
|
-
requests whose `Origin` isn't its own. [Remote access](#remote-access-over-ssh-optional)
|
|
461
|
-
doesn't change any of that: the port becomes a fixed one, still on `127.0.0.1`,
|
|
462
|
-
and a paired device presents its own credential instead of the token. Reaching
|
|
463
|
-
the port is left to SSH, which you turn on and control.
|
|
464
|
-
|
|
465
|
-
**The git panel is read-only.** No commit, stage or push. With an agent editing
|
|
466
|
-
files, a button that writes history is exactly the kind of thing where, later,
|
|
467
|
-
nobody knows who pressed it.
|
|
467
|
+
</details>
|
|
468
468
|
|
|
469
469
|
|
|
470
470
|
|
|
@@ -472,79 +472,95 @@ nobody knows who pressed it.
|
|
|
472
472
|
|
|
473
473
|
## Troubleshooting
|
|
474
474
|
|
|
475
|
-
**The "claude" command wasn't found in the PATH
|
|
476
|
-
with: …" — the app didn't find any of the four CLIs
|
|
477
|
-
|
|
478
|
-
`
|
|
479
|
-
|
|
475
|
+
**"The "claude" command wasn't found in the PATH", followed by "Also works
|
|
476
|
+
with: …"** — the app didn't find any of the four CLIs. Check with
|
|
477
|
+
`where claude` on Windows (`which claude` elsewhere), and the same with `codex`,
|
|
478
|
+
`opencode` or `agy`. CLIs are looked up at startup: if you installed one while
|
|
479
|
+
the app was open, restart it.
|
|
480
480
|
|
|
481
|
-
**
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
`
|
|
481
|
+
**OpenCode's history doesn't show up.** Look at the `History` line when the app
|
|
482
|
+
starts. If it says that Node version doesn't include `node:sqlite`, update Node
|
|
483
|
+
to 22.13 or later. If there's no such line, it didn't find the database: it's at
|
|
484
|
+
`~/.local/share/opencode/opencode.db`, or wherever `OPENCODE_DB` or
|
|
485
|
+
`XDG_DATA_HOME` points.
|
|
486
486
|
|
|
487
|
-
**An OpenCode tab won't open
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
doesn't start there either, the problem is with that OpenCode installation.
|
|
487
|
+
**An OpenCode tab won't open: "Couldn't start the OpenCode server".** The reason
|
|
488
|
+
comes after the colon. If it isn't clear, open `opencode` in a regular terminal:
|
|
489
|
+
if it doesn't start there either, the problem is that OpenCode installation.
|
|
491
490
|
|
|
492
|
-
**An OpenCode tab says the server closed.**
|
|
493
|
-
|
|
494
|
-
bar, starts another server and reattaches the tab to the same session.
|
|
491
|
+
**An OpenCode tab says the server closed.** **Relaunch**, in the same bar,
|
|
492
|
+
starts another server and reconnects the tab to the same session.
|
|
495
493
|
|
|
496
494
|
**An Antigravity tab doesn't show its status or the meter.** Look at the
|
|
497
|
-
`Status line` entry
|
|
498
|
-
configured, or that there's another one, follow
|
|
499
|
-
[
|
|
500
|
-
the CLI's terminal shows `Statusline Error`, `node` is most likely not in
|
|
501
|
-
session's `PATH`.
|
|
502
|
-
you hadn't configured it.
|
|
495
|
+
`Status line` entry when the app starts, under the CLI. If it says it isn't
|
|
496
|
+
configured, or that there's another one, follow
|
|
497
|
+
[these steps](#antigravity-cli-status-and-context-meter). If you configured it
|
|
498
|
+
and the CLI's terminal shows `Statusline Error`, `node` is most likely not in
|
|
499
|
+
that session's `PATH`.
|
|
503
500
|
|
|
504
|
-
**`node-pty` doesn't compile on install.** It's
|
|
505
|
-
downloads a
|
|
506
|
-
|
|
501
|
+
**`node-pty` doesn't compile on install.** It's the terminal's native module. It
|
|
502
|
+
usually downloads a ready-made binary; if your Node and platform don't have one,
|
|
503
|
+
it has to be compiled:
|
|
507
504
|
|
|
508
505
|
- **Windows:** Visual Studio Build Tools with the *Desktop development with C++*
|
|
509
|
-
workload, and Python 3.
|
|
510
|
-
|
|
511
|
-
the Build Tools from the Visual Studio installer.
|
|
506
|
+
workload, and Python 3. (`windows-build-tools` from npm is no longer
|
|
507
|
+
maintained.)
|
|
512
508
|
- **macOS:** `xcode-select --install`.
|
|
513
509
|
- **Linux:** `build-essential` and `python3`.
|
|
514
510
|
|
|
515
511
|
**The terminal stays blank.** The default renderer is canvas on purpose: with
|
|
516
|
-
|
|
517
|
-
|
|
512
|
+
WebGL the tab freezes on Windows 11 + Chrome. To try WebGL anyway, add
|
|
513
|
+
`?renderer=webgl` to the address.
|
|
518
514
|
|
|
519
|
-
**A banner says `CLAUDE_CODE_CHILD_SESSION` was removed.**
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
up.
|
|
515
|
+
**A banner says `CLAUDE_CODE_CHILD_SESSION` was removed.** You started the app
|
|
516
|
+
from inside a Claude Code session. That variable turns off history saving, so
|
|
517
|
+
the app removes it and lets you know. From a regular terminal you'll never see
|
|
518
|
+
this.
|
|
524
519
|
|
|
525
520
|
**From the other computer, `ssh` can't connect** (it times out or is refused).
|
|
526
|
-
The SSH server isn't running on the computer
|
|
527
|
-
|
|
528
|
-
*Private
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
user
|
|
532
|
-
(`C:\Users\<name>`) and the account's password, not the PIN.
|
|
521
|
+
The SSH server isn't running on the computer with the app, or something between
|
|
522
|
+
the two blocks it. On Windows, check that the Wi‑Fi network is set to
|
|
523
|
+
*Private*: the SSH server's firewall rule may not cover *Public* networks. A
|
|
524
|
+
work VPN that blocks the local network also cuts it while it's connected. If
|
|
525
|
+
`ssh` rejects your user, a Microsoft or work account may need the name of your
|
|
526
|
+
user folder (`C:\Users\<name>`) and the account's password, not the PIN.
|
|
533
527
|
|
|
534
528
|
**From the other computer, the page says "Origin not allowed"** (403). It was
|
|
535
|
-
opened by the computer's name or IP. Open `http://localhost:<port>`,
|
|
536
|
-
tunnel using the same port on both ends.
|
|
529
|
+
opened by the computer's name or IP address. Open `http://localhost:<port>`,
|
|
530
|
+
with the tunnel using the same port on both ends.
|
|
537
531
|
|
|
538
532
|
**From the other computer, the page says the session token is missing** (401).
|
|
539
|
-
That browser isn't paired,
|
|
540
|
-
|
|
533
|
+
That browser isn't paired, it was revoked, or remote access is off. Pair it
|
|
534
|
+
again from the ⇄ dialog.
|
|
541
535
|
|
|
542
536
|
**The ⇄ dialog says the port is busy.** Another program —often a second Agent
|
|
543
|
-
Workbench—
|
|
537
|
+
Workbench— is using it. Close it and restart, or choose another port.
|
|
538
|
+
|
|
539
|
+
**The Changes panel says the folder isn't a git repository**, and it is one.
|
|
540
|
+
Make sure `git` is in the `PATH`. If the message is a different one, it's git's
|
|
541
|
+
own error, word for word.
|
|
542
|
+
|
|
543
|
+
---
|
|
544
|
+
|
|
545
|
+
## From source
|
|
546
|
+
|
|
547
|
+
To work on the app, or if you'd rather not install anything globally:
|
|
548
|
+
|
|
549
|
+
```bash
|
|
550
|
+
corepack enable pnpm
|
|
551
|
+
pnpm install
|
|
552
|
+
pnpm dev # with hot reload
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
```bash
|
|
556
|
+
pnpm build # builds the interface once
|
|
557
|
+
pnpm start # serves the built interface
|
|
558
|
+
```
|
|
544
559
|
|
|
545
|
-
**
|
|
546
|
-
|
|
547
|
-
|
|
560
|
+
**One-click start on Windows:** `pnpm package` builds the interface and leaves
|
|
561
|
+
an **`Agent Workbench.cmd`** in the root. Double-click it: it installs whatever
|
|
562
|
+
is missing, builds if needed and opens the browser. It's a twenty-line text
|
|
563
|
+
file you can read before running it.
|
|
548
564
|
|
|
549
565
|
---
|
|
550
566
|
|
|
@@ -554,32 +570,24 @@ A pnpm monorepo, TypeScript throughout.
|
|
|
554
570
|
|
|
555
571
|
```
|
|
556
572
|
packages/
|
|
557
|
-
server/ Node, Express, ws, node-pty, chokidar — serves the interface and
|
|
573
|
+
server/ Node, Express, ws, node-pty, chokidar — serves the interface and runs the terminals
|
|
558
574
|
src/agents/ one adapter per CLI: the only part of the server that knows each one
|
|
559
575
|
web/ Vite, React, xterm.js, highlight.js
|
|
560
576
|
shared/ the protocol types, with no `any` at the edges
|
|
561
|
-
android/ the Android app, in Kotlin: the SSH tunnel,
|
|
577
|
+
android/ the Android app, in Kotlin: the SSH tunnel, the interface, the notifications
|
|
562
578
|
```
|
|
563
579
|
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
each one —where it stores things, how it's launched, what is read and what is
|
|
576
|
-
never opened— lives in its adapter, and the interface draws each control based
|
|
577
|
-
on what that CLI declares.
|
|
578
|
-
|
|
579
|
-
[`ARCHITECTURE.md`](ARCHITECTURE.md) has the hard rules, the code map, what is
|
|
580
|
-
read from each CLI and what is never opened. [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
|
581
|
-
covers how to work on the repository, [`SECURITY.md`](SECURITY.md) how to report
|
|
582
|
-
a vulnerability, [`PRIVACY.md`](PRIVACY.md) what is collected (nothing), and
|
|
580
|
+
Two decisions shape the rest. **The terminals live on the server and the
|
|
581
|
+
browser is just a window onto them**: closing or reloading the page doesn't
|
|
582
|
+
kill a working session. And **the generic server doesn't name any CLI**: what it
|
|
583
|
+
knows about each one —where it keeps things, how it's launched, what is read
|
|
584
|
+
and what is never opened— lives in that CLI's adapter, and the interface shows
|
|
585
|
+
each control based on what that CLI declares.
|
|
586
|
+
|
|
587
|
+
[`ARCHITECTURE.md`](ARCHITECTURE.md) has the hard rules and the code map,
|
|
588
|
+
[`CONTRIBUTING.md`](CONTRIBUTING.md) how to work on the repository,
|
|
589
|
+
[`SECURITY.md`](SECURITY.md) how to report a vulnerability,
|
|
590
|
+
[`PRIVACY.md`](PRIVACY.md) what is collected (nothing), and
|
|
583
591
|
[`CHANGELOG.md`](CHANGELOG.md) what changed in each version. Code comments are
|
|
584
592
|
in Spanish. The screenshots in this README come from `pnpm demo:shots`, on
|
|
585
593
|
made-up data.
|