agent-workbench 0.2.0 → 0.3.1
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/LICENSE +21 -21
- package/README.md +426 -413
- package/dist/server.js +927 -623
- package/dist/web/assets/de-PtmfVEFc.js +1 -0
- package/dist/web/assets/es-BWOH-zRt.js +1 -0
- package/dist/web/assets/fr-tY7LZ7vh.js +1 -0
- package/dist/web/assets/{highlight-D9nIZ0qi.js → highlight-BdawNAzW.js} +1 -1
- package/dist/web/assets/index-CmLNpznn.css +32 -0
- package/dist/web/assets/index-Crbjtl9a.js +135 -0
- package/dist/web/assets/ja-CebmU1Hk.js +1 -0
- package/dist/web/assets/ko-BuKbKnfu.js +1 -0
- package/dist/web/assets/pt-BR-CxtiCd-u.js +1 -0
- package/dist/web/assets/ru-C3EXpruH.js +1 -0
- package/dist/web/assets/zh-CN-DugN9tNb.js +1 -0
- package/dist/web/favicon.svg +32 -32
- package/dist/web/index.html +19 -19
- package/package.json +2 -2
- package/dist/web/assets/index-Bgx4KtjD.css +0 -32
- package/dist/web/assets/index-DIDbH8tn.js +0 -130
package/README.md
CHANGED
|
@@ -1,413 +1,426 @@
|
|
|
1
|
-
# Agent Workbench
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
](https://www.npmjs.com/package/agent-workbench)
|
|
4
|
+
[](https://github.com/cvelasquez/agent-workbench/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
**One local interface for the Claude Code, Codex, OpenCode and Antigravity
|
|
8
|
+
CLIs.** It uses the CLIs you already have logged in, never touches your
|
|
9
|
+
credentials, and makes no network calls of its own.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npx agent-workbench
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
It doesn't talk to any API. It launches the CLI you already have installed and
|
|
18
|
+
logged in —`claude`, `codex`, `opencode` or `agy`— inside a pseudo-terminal, and
|
|
19
|
+
adds around it what a terminal alone doesn't give you: tabs, browsable history,
|
|
20
|
+
the conversation as cards, a context meter, git status and a file tree.
|
|
21
|
+
|
|
22
|
+
The terminal is still the terminal. Everything you type reaches the CLI without
|
|
23
|
+
the app touching it.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## What it does
|
|
28
|
+
|
|
29
|
+
| | |
|
|
30
|
+
|---|---|
|
|
31
|
+
| **Tabs** | Several live sessions at once, from any of the CLIs, each in its own directory. They survive an `F5`: the processes live on the server, not in the browser tab. Each tab's dot tells you whether the agent is working, idle or waiting for an answer, on the CLIs that publish their status ([below](#multiple-clis)). |
|
|
32
|
+
| **Zero-cost startup** | When you open the app, tabs come back as **sleeping tabs**: you can read them in full, and they don't launch any CLI. You open the CLI with a button when you want to write to the agent. |
|
|
33
|
+
| **History** | Your projects and past conversations in the sidebar, with a filter, and those of all four CLIs together under each project, each with its badge. Opening one resumes it with its CLI, in the same session. **Archive history…** hides a CLI's sessions from before today in one go, and each project can be archived whole with one button: nothing is deleted, and both can be undone. |
|
|
34
|
+
| **Conversation** | The active session's messages, live, with tool calls collapsed and their results inside. Search, jump between matches, copy any message and, depending on the CLI, answer the agent's questions from the chat. |
|
|
35
|
+
| **Continue with…** | With more than one CLI installed, a conversation can be continued with another CLI in the same folder. The new agent starts from a transcript of the last turns, not from the context the previous one had. |
|
|
36
|
+
| **Search everything** | With more than one CLI and something saved in the local copy, the sidebar filter also searches the text of every saved conversation, not just their titles. |
|
|
37
|
+
| **Context meter** | Tokens from the last request against the model's context window. Tokens, never money. |
|
|
38
|
+
| **Changes** | Branch, ahead and behind against the upstream branch, worktrees, and the changed files with their diff. **Read-only.** |
|
|
39
|
+
| **Files** | The tree of the tab's directory, with search by name and a preview with syntax highlighting. A context menu to copy paths, insert them as `@path` or open the file with the system's default app. |
|
|
40
|
+
| **Plans** | The documents written by that conversation, rendered: the plans from plan mode, and also the `.md` files the agent created inside the project or in the session's temp folder. Only those named by the conversation you're viewing. |
|
|
41
|
+
| **Shared memory** | What agents learn about a project, in `.agents/memory/`, read and written by all four CLIs ([below](#shared-memory)). |
|
|
42
|
+
| **Local copy** | Optional. The history of all four CLIs in a folder of yours, in the app's own format, so you don't lose it if a CLI changes its format, deletes it, or you uninstall the CLI ([below](#local-copy-optional)). |
|
|
43
|
+
| **Nine languages** | The interface in English, Español, 简体中文, 日本語, Português (Brasil), Русский, 한국어, Français and Deutsch. It follows the browser's language and can be changed from the header, without reloading. |
|
|
44
|
+
| **Theme** | Light, dark, or the system's. |
|
|
45
|
+
|
|
46
|
+
<p>
|
|
47
|
+
<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
|
+
<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
|
+
</p>
|
|
50
|
+
|
|
51
|
+
### Multiple CLIs
|
|
52
|
+
|
|
53
|
+
With more than one CLI installed, every session in the sidebar and every tab
|
|
54
|
+
carries its CLI's badge, and the new-tab `+` opens with the one you used in that
|
|
55
|
+
project; its arrow lets you pick another. With just one, you see none of this.
|
|
56
|
+
|
|
57
|
+
<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
|
+
|
|
59
|
+
**Not every CLI exposes the same things.** Claude Code leaves everything the app
|
|
60
|
+
needs in its files. Codex leaves the history and the meter's tokens, but not its
|
|
61
|
+
status, its pending permissions, its questions or the model: its dot says the
|
|
62
|
+
status is unknown, there's no "waiting" notice and questions are answered in its
|
|
63
|
+
terminal. With OpenCode, the app starts a local OpenCode server when you open a
|
|
64
|
+
tab, and that's where its status, the notice that it's waiting for a permission
|
|
65
|
+
and the questions you answer from the chat come from. Antigravity CLI publishes
|
|
66
|
+
its status and tokens only if you configure its status line
|
|
67
|
+
([below](#antigravity-cli-status-and-meter-optional)).
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Requirements
|
|
72
|
+
|
|
73
|
+
| | |
|
|
74
|
+
|---|---|
|
|
75
|
+
| **Node.js** | 20 or later. **To see the OpenCode history and the Antigravity CLI titles, 22.13 or later**: they're read with the SQLite that Node ships since that version. With an older one everything else works the same; the startup output warns about OpenCode, and Antigravity CLI lists its conversations without the titles or folders from its index |
|
|
76
|
+
| **git** | for the Changes panel; everything else works without it |
|
|
77
|
+
| **At least one CLI** | installed and logged in (table below) |
|
|
78
|
+
|
|
79
|
+
| CLI | Command | Installation |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| Claude Code | `claude` | [installation guide](https://docs.claude.com/en/docs/claude-code/setup) |
|
|
82
|
+
| Codex | `codex` | [guide](https://learn.chatgpt.com/docs/codex/cli) |
|
|
83
|
+
| OpenCode | `opencode` | [documentation](https://opencode.ai/docs/) |
|
|
84
|
+
| Antigravity CLI | `agy` | [guide](https://antigravity.google/docs/cli/getting-started). For its status and meter, also `node` in the CLI's `PATH` |
|
|
85
|
+
|
|
86
|
+
Agent Workbench does **not** bundle or download any CLI: it uses the ones you
|
|
87
|
+
already have in your `PATH`. If it doesn't find any, it tells you so and doesn't
|
|
88
|
+
open sessions.
|
|
89
|
+
|
|
90
|
+
Developed and used daily on Windows 11 with PowerShell, which is the main
|
|
91
|
+
platform. On macOS and Linux, CI installs the package and starts it on every
|
|
92
|
+
push —server up, a pseudo-terminal spawning a process—, but it sees less daily
|
|
93
|
+
use there: reports are welcome. On Linux, the `node-pty` dependency doesn't ship a prebuilt
|
|
94
|
+
binary and is compiled on install: you need `python3`, `make` and a C++ compiler
|
|
95
|
+
(`build-essential` on Debian and Ubuntu).
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## Install
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
npm install -g agent-workbench
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Then, from the folder of the project you want to work on:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
agent-workbench
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
To try it once without installing it, `npx agent-workbench` — it downloads about
|
|
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:
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
URL http://127.0.0.1:52341/?token=…
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
That URL is the only way in. The token is different on every start, and the
|
|
122
|
+
server listens only on `127.0.0.1`.
|
|
123
|
+
|
|
124
|
+
### Shared memory
|
|
125
|
+
|
|
126
|
+
Each CLI keeps what it learns about a project in its own folder, and the others
|
|
127
|
+
can't see it. The **Memory** tab installs a bridge so all four use the same one:
|
|
128
|
+
notes in the project's `.agents/memory/`, which each CLI reads and writes —from
|
|
129
|
+
here or from its own terminal— through `AGENTS.md` and `CLAUDE.md`.
|
|
130
|
+
|
|
131
|
+
**Preview changes** shows, file by file, what will be written, and nothing is
|
|
132
|
+
touched until you confirm. Installing imports the memory Claude Code already had
|
|
133
|
+
for that project. The app doesn't write each CLI's global memory: it gives you
|
|
134
|
+
the snippet to paste yourself.
|
|
135
|
+
|
|
136
|
+
<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
|
+
|
|
138
|
+
### Antigravity CLI: status and meter (optional)
|
|
139
|
+
|
|
140
|
+
Antigravity CLI doesn't record in any file whether it's working, waiting for you
|
|
141
|
+
to authorize a tool or idle, nor how many tokens it has used: it only publishes
|
|
142
|
+
that through its *status line*. Without it configured, its tabs work the same
|
|
143
|
+
—history, conversation, mode, model— but the tab's dot says the status is
|
|
144
|
+
unknown and the meter stays empty. To turn it on:
|
|
145
|
+
|
|
146
|
+
1. Open an Antigravity tab and click **Configure**, next to the meter.
|
|
147
|
+
2. Copy the line the dialog shows and merge it into whatever
|
|
148
|
+
`~/.gemini/antigravity-cli/settings.json` already has. The app doesn't touch
|
|
149
|
+
that file: you edit it.
|
|
150
|
+
3. The dialog switches to **Configured** on its own within a couple of seconds,
|
|
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
|
+
### Local copy (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 local copy 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 local copy 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
|
|
174
|
+
from that folder.
|
|
175
|
+
|
|
176
|
+
Whatever the CLI no longer has stays in the sidebar, marked as a copy, and opens
|
|
177
|
+
in Markdown; each project can be exported to Markdown. And with the copy on and
|
|
178
|
+
more than one CLI, the sidebar filter offers **In conversations**: it searches
|
|
179
|
+
the text of everything copied, from every CLI.
|
|
180
|
+
|
|
181
|
+
<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
|
+
|
|
183
|
+
By default it lives inside the app's configuration folder
|
|
184
|
+
(`%APPDATA%\agent-workbench\vault` on Windows). **Change folder…** copies all of
|
|
185
|
+
it to another one —a synced folder, another drive— without overwriting anything,
|
|
186
|
+
and the previous one stays as it was. If you put it in a synced folder or in a
|
|
187
|
+
repository, what it keeps travels with it.
|
|
188
|
+
|
|
189
|
+
Two one-off importers bring in history from tools the app doesn't read. They run
|
|
190
|
+
from source ([below](#from-source)) and **write nothing without `--write`**:
|
|
191
|
+
without it, they tell you what they would import.
|
|
192
|
+
|
|
193
|
+
- `pnpm vault:import gemini-cli [--cwd <folder>]` — the chats left over from
|
|
194
|
+
Gemini CLI; `--cwd` names the folder where you used it, to place them in their
|
|
195
|
+
project.
|
|
196
|
+
- `pnpm vault:import antigravity-ide --workspace <folder>` — whatever is
|
|
197
|
+
readable from the Antigravity IDE conversations in that folder: each one's
|
|
198
|
+
summary and its `.md` documents. The conversation content is encrypted, so it
|
|
199
|
+
is marked as partial history.
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## From source
|
|
204
|
+
|
|
205
|
+
To work on the app, or if you'd rather not install anything globally:
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
corepack enable pnpm
|
|
209
|
+
pnpm install
|
|
210
|
+
pnpm dev # Vite with hot reload
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
pnpm build # builds the interface once
|
|
215
|
+
pnpm start # serves the built interface, without Vite
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### One-click start on Windows
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
pnpm package
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
It builds the interface and leaves an **`Agent Workbench.cmd`** in the root.
|
|
225
|
+
Double-click it and you're done: it installs whatever is missing, builds if
|
|
226
|
+
needed and opens the browser. It's a twenty-line text file; you can read all of
|
|
227
|
+
it before running it.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Keyboard shortcuts
|
|
232
|
+
|
|
233
|
+
`Alt+T` new tab · `Alt+W` close · `Alt+←/→` (or `Alt+PgUp/PgDn`) switch tabs ·
|
|
234
|
+
`Alt+P` show or hide the right panel · `Shift+Tab`, outside the terminal, go
|
|
235
|
+
back to the previous tab.
|
|
236
|
+
|
|
237
|
+
The `?` button in the top bar lists them all, along with the shortcuts of the
|
|
238
|
+
tab's CLI.
|
|
239
|
+
|
|
240
|
+
**Why `Alt` and not `Ctrl`:** the browser keeps `Ctrl+T`, `Ctrl+W` and
|
|
241
|
+
`Ctrl+Tab` for its own tabs and the event never reaches the page. It's not
|
|
242
|
+
something `preventDefault` can fix: there's no event to prevent.
|
|
243
|
+
|
|
244
|
+
The app captures exactly those combinations and no others. `Shift+Tab` only
|
|
245
|
+
when focus isn't on the terminal, because inside it's the key the CLI uses to
|
|
246
|
+
switch modes. Everything else —`Esc`, `Esc Esc`, `Ctrl+C`, `Ctrl+R`, `Ctrl+O`,
|
|
247
|
+
the arrow keys and above all `Alt+V`, which pastes images— reaches the CLI
|
|
248
|
+
untouched.
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## What the app does with your data
|
|
253
|
+
|
|
254
|
+
Nothing leaves your machine. No telemetry, no analytics, no outgoing network
|
|
255
|
+
calls at all. The exception is the CLI itself at work: the one you open in a
|
|
256
|
+
tab, and the OpenCode server described below, talk to the model provider just
|
|
257
|
+
as they would if you opened them by hand.
|
|
258
|
+
|
|
259
|
+
**It never touches your credentials.** There's no login in the interface: if
|
|
260
|
+
you aren't logged in, you log in inside the CLI's terminal and the app doesn't
|
|
261
|
+
even notice.
|
|
262
|
+
|
|
263
|
+
**From each CLI it reads only this, and it writes nothing in the CLI's
|
|
264
|
+
folder.** The local copy importers, when you run them, also read what
|
|
265
|
+
[their section](#local-copy-optional) says.
|
|
266
|
+
|
|
267
|
+
| CLI | Reads | Never opens |
|
|
268
|
+
|---|---|---|
|
|
269
|
+
| 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 |
|
|
270
|
+
| Codex | from `~/.codex/` (or `CODEX_HOME`): `sessions/` and `archived_sessions/` | `auth.json`, `config.toml` or its `*.sqlite` databases |
|
|
271
|
+
| 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 |
|
|
272
|
+
| 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 |
|
|
273
|
+
|
|
274
|
+
Three footprints worth knowing about:
|
|
275
|
+
|
|
276
|
+
- **Reading the OpenCode database** does what SQLite does with any reader: it
|
|
277
|
+
creates its `-wal` and `-shm` files if they're missing and updates the
|
|
278
|
+
timestamp of `-shm`. It never runs an OpenCode command to read it.
|
|
279
|
+
- **If an Antigravity tab's own log doesn't show up**, it reads the CLI's
|
|
280
|
+
`log/cli-*.log` files, which contain your messages and the account's email,
|
|
281
|
+
only to find the conversation id, and without keeping any line.
|
|
282
|
+
- **With OpenCode, the app runs its local server**, `opencode serve`: just one,
|
|
283
|
+
from when you open the first OpenCode tab until five minutes after you close
|
|
284
|
+
the last one, or until you close the app. It listens on `127.0.0.1`, with an
|
|
285
|
+
ephemeral port and a different password on every start, even if your OpenCode
|
|
286
|
+
configuration says otherwise. The app only asks it for the sessions' status,
|
|
287
|
+
pending permissions and questions, to create a session, to answer a question
|
|
288
|
+
and to abort a session: nothing about your configuration or your accounts.
|
|
289
|
+
|
|
290
|
+
**It adds no authentication variables** to the environment of the CLIs it
|
|
291
|
+
launches. The environment is inherited as is, with two exceptions: it
|
|
292
|
+
**removes** `CLAUDE_CODE_CHILD_SESSION` —which turns off history saving— and
|
|
293
|
+
tells you with a banner when it does; and it **adds** a single variable to the
|
|
294
|
+
OpenCode server, `OPENCODE_SERVER_PASSWORD`, holding that per-start password. It
|
|
295
|
+
isn't any account's password, and the variable doesn't reach any tab: each
|
|
296
|
+
OpenCode tab gets the password on its command line (`attach --password`), where
|
|
297
|
+
other processes running as your user can see it. It only works for that server
|
|
298
|
+
and stops being valid when you close the app.
|
|
299
|
+
|
|
300
|
+
**What the app writes:**
|
|
301
|
+
|
|
302
|
+
- **In its own configuration directory:** the open tabs, the index cache, the
|
|
303
|
+
notes, the archived sessions, the Antigravity status line script and, if you
|
|
304
|
+
turn it on, the local copy (or in the folder you choose).
|
|
305
|
+
- **In the temp folder:** the images you paste; each Antigravity tab's log,
|
|
306
|
+
which contains your messages, readable only by you and deleted on the first
|
|
307
|
+
start once it's more than 24 hours old; and the transcript of a conversation
|
|
308
|
+
you continue in another CLI, deleted when you close that tab or after 24
|
|
309
|
+
hours.
|
|
310
|
+
- **In your projects, one thing only, and only if you confirm:** the shared
|
|
311
|
+
memory. It's limited to `.agents/memory/`, to what's between its markers in
|
|
312
|
+
`AGENTS.md` and `CLAUDE.md`, and to a few lines at the end of `.gitignore`.
|
|
313
|
+
|
|
314
|
+
**The server listens only on `127.0.0.1`**, on an ephemeral port, with a random
|
|
315
|
+
per-start token that the WebSocket and every HTTP route require, and it rejects
|
|
316
|
+
requests whose `Origin` isn't its own.
|
|
317
|
+
|
|
318
|
+
**The git panel is read-only.** No commit, stage or push. With an agent editing
|
|
319
|
+
files, a button that writes history is exactly the kind of thing where, later,
|
|
320
|
+
nobody knows who pressed it.
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
|
|
324
|
+
---
|
|
325
|
+
|
|
326
|
+
## Troubleshooting
|
|
327
|
+
|
|
328
|
+
**The "claude" command wasn't found in the PATH**, followed by "Also works
|
|
329
|
+
with: …" — the app didn't find any of the four CLIs in the `PATH` of the process
|
|
330
|
+
running it. Check with `where claude` (or `which claude`), and the same with
|
|
331
|
+
`codex`, `opencode` or `agy`. CLIs are looked up at startup: if you installed
|
|
332
|
+
one while the app was open, restart it.
|
|
333
|
+
|
|
334
|
+
**The OpenCode history doesn't show up.** Look at the `History` line in the
|
|
335
|
+
startup output. If it says that Node version doesn't include `node:sqlite`,
|
|
336
|
+
update Node to 22.13 or later. If there's no such line, it didn't find the
|
|
337
|
+
database: it's at `~/.local/share/opencode/opencode.db`, or wherever
|
|
338
|
+
`OPENCODE_DB` or `XDG_DATA_HOME` points.
|
|
339
|
+
|
|
340
|
+
**An OpenCode tab won't open and says "Couldn't start the OpenCode server".**
|
|
341
|
+
The tab attaches to an `opencode serve` the app launches, and the reason comes
|
|
342
|
+
after the colon. If it isn't clear, open `opencode` in a regular terminal: if it
|
|
343
|
+
doesn't start there either, the problem is with that OpenCode installation.
|
|
344
|
+
|
|
345
|
+
**An OpenCode tab says the server closed.** The `opencode serve` process ended
|
|
346
|
+
and the tab's terminal was left without a connection. **Relaunch**, in the same
|
|
347
|
+
bar, starts another server and reattaches the tab to the same session.
|
|
348
|
+
|
|
349
|
+
**An Antigravity tab doesn't show its status or the meter.** Look at the
|
|
350
|
+
`Status line` entry in the startup output, under the CLI: if it says it isn't
|
|
351
|
+
configured, or that there's another one, follow the steps
|
|
352
|
+
[above](#antigravity-cli-status-and-meter-optional). If you configured it and
|
|
353
|
+
the CLI's terminal shows `Statusline Error`, `node` is most likely not in that
|
|
354
|
+
session's `PATH`. Until the line publishes anything, the tab is treated as if
|
|
355
|
+
you hadn't configured it.
|
|
356
|
+
|
|
357
|
+
**`node-pty` doesn't compile on install.** It's a native module. It usually
|
|
358
|
+
downloads a prebuilt binary and nothing else is needed; if your combination of
|
|
359
|
+
Node and platform doesn't have one, it has to be compiled:
|
|
360
|
+
|
|
361
|
+
- **Windows:** Visual Studio Build Tools with the *Desktop development with C++*
|
|
362
|
+
workload, and Python 3.
|
|
363
|
+
`npm install --global windows-build-tools` is no longer maintained: install
|
|
364
|
+
the Build Tools from the Visual Studio installer.
|
|
365
|
+
- **macOS:** `xcode-select --install`.
|
|
366
|
+
- **Linux:** `build-essential` and `python3`.
|
|
367
|
+
|
|
368
|
+
**The terminal stays blank.** The default renderer is canvas on purpose: with
|
|
369
|
+
the WebGL addon the tab freezes on Windows 11 + Chrome even though the data
|
|
370
|
+
arrives. If you want to try it anyway, add `?renderer=webgl` to the URL.
|
|
371
|
+
|
|
372
|
+
**A banner says `CLAUDE_CODE_CHILD_SESSION` was removed.** It happens when you
|
|
373
|
+
start the app from inside a Claude Code CLI session. That variable turns off
|
|
374
|
+
history saving, and without history there's no conversation or meter. The app
|
|
375
|
+
removes it and lets you know. In normal use —a regular terminal— it never shows
|
|
376
|
+
up.
|
|
377
|
+
|
|
378
|
+
**The Changes panel says the folder isn't a git repository** and it is one.
|
|
379
|
+
Make sure `git` is in the `PATH`. If the message is a different one, it's the
|
|
380
|
+
error git returned, verbatim.
|
|
381
|
+
|
|
382
|
+
---
|
|
383
|
+
|
|
384
|
+
## How it's built
|
|
385
|
+
|
|
386
|
+
A pnpm monorepo, TypeScript throughout.
|
|
387
|
+
|
|
388
|
+
```
|
|
389
|
+
packages/
|
|
390
|
+
server/ Node, Express, ws, node-pty, chokidar — serves the interface and hosts the ptys
|
|
391
|
+
src/agents/ one adapter per CLI: the only part of the server that knows each one
|
|
392
|
+
web/ Vite, React, xterm.js, highlight.js
|
|
393
|
+
shared/ the protocol types, with no `any` at the edges
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
A single process serves the interface and the WebSocket on the same port: with
|
|
397
|
+
a single origin, the `Origin` check and the token work the same in development
|
|
398
|
+
and in production, with no exceptions that nobody remembers to remove later.
|
|
399
|
+
|
|
400
|
+
The architectural decision that shapes the rest: **the ptys live in a server
|
|
401
|
+
registry and the WebSocket is just transport.** If the process died with the
|
|
402
|
+
socket, an accidental `Ctrl+R` would wipe out the working session. Each terminal
|
|
403
|
+
keeps a buffer of its recent output to repaint the screen when the client comes
|
|
404
|
+
back.
|
|
405
|
+
|
|
406
|
+
The other one: **the generic server doesn't name any CLI.** What it knows about
|
|
407
|
+
each one —where it stores things, how it's launched, what is read and what is
|
|
408
|
+
never opened— lives in its adapter, and the interface draws each control based
|
|
409
|
+
on what that CLI declares.
|
|
410
|
+
|
|
411
|
+
[`ARCHITECTURE.md`](ARCHITECTURE.md) has the hard rules, the code map, what is
|
|
412
|
+
read from each CLI and what is never opened. [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
|
413
|
+
covers how to work on the repository, [`SECURITY.md`](SECURITY.md) how to report
|
|
414
|
+
a vulnerability, and [`CHANGELOG.md`](CHANGELOG.md) what changed in each
|
|
415
|
+
version. Code comments are in Spanish. The screenshots in this README come from
|
|
416
|
+
`pnpm demo:shots`, on made-up data.
|
|
417
|
+
|
|
418
|
+
---
|
|
419
|
+
|
|
420
|
+
## License
|
|
421
|
+
|
|
422
|
+
MIT. See [`LICENSE`](LICENSE).
|
|
423
|
+
|
|
424
|
+
Agent Workbench is an independent project. It works with the Claude Code,
|
|
425
|
+
Codex, OpenCode and Antigravity CLIs, but it is not affiliated with or endorsed
|
|
426
|
+
by Anthropic, OpenAI, the OpenCode authors or Google.
|