agent-workbench 0.3.0 → 0.4.0

package/README.md

@@ -12,6 +12,8 @@ credentials, and makes no network calls of its own.
 npx agent-workbench
 ```
 
+![A tour: the conversation as cards, the changed files and a diff, one tab per CLI, and continuing a conversation with another CLI](https://raw.githubusercontent.com/cvelasquez/agent-workbench/main/assets/demo.webp)
+
 It doesn't talk to any API. It launches the CLI you already have installed and
 logged in —`claude`, `codex`, `opencode` or `agy`— inside a pseudo-terminal, and
 adds around it what a terminal alone doesn't give you: tabs, browsable history,
@@ -20,8 +22,6 @@ the conversation as cards, a context meter, git status and a file tree.
 The terminal is still the terminal. Everything you type reaches the CLI without
 the app touching it.
 
-![The conversation in the center; around it, the projects with their history, the tabs of the four CLIs and the file tree](https://raw.githubusercontent.com/cvelasquez/agent-workbench/main/assets/captura-conversacion.png)
-
 ---
 
 ## What it does
@@ -31,12 +31,12 @@ the app touching it.
 | **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)). |
 | **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. |
 | **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. |
-| **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. |
+| **Conversation** | The active session's messages, live, with tool calls collapsed and their results inside. Search, jump between matches, copy any message or code block and, depending on the CLI, answer the agent's questions from the chat. |
 | **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. |
 | **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. |
 | **Context meter** | Tokens from the last request against the model's context window. Tokens, never money. |
 | **Changes** | Branch, ahead and behind against the upstream branch, worktrees, and the changed files with their diff. **Read-only.** |
-| **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. |
+| **Files** | The tree of the tab's directory, with search by name and a preview with syntax highlighting. A button on each row puts its path in your message, without touching the clipboard. A context menu to copy paths, insert them as `@path` or open the file with the system's default app. |
 | **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. |
 | **Shared memory** | What agents learn about a project, in `.agents/memory/`, read and written by all four CLIs ([below](#shared-memory)). |
 | **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)). |
@@ -87,8 +87,10 @@ Agent Workbench does **not** bundle or download any CLI: it uses the ones you
 already have in your `PATH`. If it doesn't find any, it tells you so and doesn't
 open sessions.
 
-Tested on Windows 11 with PowerShell, which is the main platform. macOS and
-Linux work the same. On Linux, the `node-pty` dependency doesn't ship a prebuilt
+Developed and used daily on Windows 11 with PowerShell, which is the main
+platform. On macOS and Linux, CI installs the package and starts it on every
+push —server up, a pseudo-terminal spawning a process—, but it sees less daily
+use there: reports are welcome. On Linux, the `node-pty` dependency doesn't ship a prebuilt
 binary and is compiled on install: you need `python3`, `make` and a C++ compiler
 (`build-essential` on Debian and Ubuntu).
 
@@ -196,6 +198,144 @@ without it, they tell you what they would import.
   summary and its `.md` documents. The conversation content is encrypted, so it
   is marked as partial history.
 
+### Remote access over SSH (optional)
+
+You can leave Agent Workbench running on one computer and use it from another
+one on the same network, in its browser — with no CLI installed there.
+**The app is never opened to the network**: it keeps listening only on
+`127.0.0.1`, and the other computer reaches it through an SSH tunnel. That's
+also what makes it work: through the tunnel the other browser sees the app as
+`localhost`, and outside `localhost` browsers switch off things the app needs
+(the clipboard, notifications, `crypto.randomUUID`). **It's off by default.**
+
+**1. On the computer that runs the app, once: turn on its SSH server.** The app
+doesn't do this for you — it's a system change that needs administrator rights.
+
+- **Windows 10/11** — in PowerShell *as administrator*:
+
+  ```powershell
+  Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
+  Start-Service sshd
+  Set-Service -Name sshd -StartupType Automatic
+  ```
+
+  The first line downloads and installs the server: it takes a few minutes and
+  shows "Running" meanwhile. Wait until the prompt comes back.
+
+- **macOS** — System Settings → General → Sharing → **Remote Login**.
+- **Linux** — install and enable your distribution's OpenSSH server
+  (`sudo apt install openssh-server`, then `sudo systemctl enable --now ssh`).
+
+**2. In the app: the ⇄ button in the header → Turn on remote access**, and
+restart Agent Workbench. A tunnel needs a port that doesn't change on every
+start, so the app uses a fixed one (24837 by default, you can change it) — and
+the port is chosen at startup, which is why it takes a restart. Restarting
+closes the open CLIs; the tabs come back asleep. Turning it *off* takes effect
+right away.
+
+**3. On the other computer, every time: open the tunnel.** The dialog shows the
+command ready to copy:
+
+```
+ssh -N -L 24837:127.0.0.1:24837 you@your-computer
+```
+
+Leave it running. **Use the same port on both ends**: the server checks it, and
+with a different local port it answers 403. Adding
+`-o ServerAliveInterval=30 -o ExitOnForwardFailure=yes` makes the tunnel notice
+a dropped Wi‑Fi instead of hanging. On Windows you can save the line in a
+`.cmd` file and double-click it.
+
+**4. Pair that computer, once.** In the dialog, **Pair a device** shows an
+address with a one-time code, such as
+`http://localhost:24837/?pair=K7QM-X2RD`. Open it in the other computer's
+browser within five minutes. From then on that browser just opens
+`http://localhost:24837`, even after the app restarts. The dialog lists the
+paired devices, and **Revoke** cuts one off on the spot.
+
+A paired device can use the whole app, with two limits: it can't manage remote
+access (turn it on, pair or revoke), and it isn't offered what opens a window on
+the computer that runs the app — *Open with the default app*, opening the local
+copy's folder or exporting to Markdown. A small **Remote** badge in the header
+says so. Those limits are about what lands on the host's screen, not about
+trust: the app includes a console and launches agents, so a paired device can
+run commands on that computer, just as you can. Pair only devices that are
+yours.
+
+**A safer key (recommended).** The SSH login is the one of your user on that
+computer, so a password or key that opens the tunnel also opens a full terminal
+there. You can create a key that is only good for the tunnel: generate one on
+the other computer (`ssh-keygen -t ed25519`) and add its public half to
+`authorized_keys` on the computer that runs the app, with these options in
+front:
+
+```
+restrict,port-forwarding,permitopen="127.0.0.1:24837",command="exit" ssh-ed25519 AAAA… other-computer
+```
+
+`restrict` on its own still lets the key run commands (it only refuses a
+terminal, agent forwarding and other ports); `command="exit"` is what closes
+that door, and the tunnel never asks for a command. On Windows, if your user is
+an administrator, that file is
+`C:\ProgramData\ssh\administrators_authorized_keys` and it must be writable
+only by Administrators and SYSTEM; otherwise it's
+`%USERPROFILE%\.ssh\authorized_keys`. To check that the restriction holds, try
+`ssh you@your-computer whoami` with that key: it should print nothing and end
+at once, while the `-N -L` tunnel keeps working.
+
+**From a phone.** Through the same tunnel, a phone browser gets a
+single-column layout: the projects sidebar as a drawer, the tabs in the header,
+and a strip that switches between the conversation, the CLI, changes, files and
+the rest. It appears on any window narrower than 768 px (a tablet held upright, too).
+On a touch screen, Enter in the message box starts a new line (the send button
+sends), and dragging a finger over a terminal scrolls it like a mouse wheel.
+
+**Notifications.** The bell button in the header turns on system notifications:
+"finished" and "is waiting for you", with the tab's name, only when the window
+isn't in view. They follow the same rule as the notification sound, so they
+come from the CLIs that publish their status. Each browser remembers its own
+choice, and the sound plays on every screen that has the app open.
+
+### The Android app (optional)
+
+An app for Android 10 and later opens the tunnel for you and shows the same
+interface, served by your computer, in the phone-sized layout. It keeps the
+connection open in the background and notifies you when an agent finishes or is
+waiting for you, with the screen off too; tapping a notification opens that
+tab. When the Wi‑Fi comes back, it reconnects on its own.
+
+It needs remote access on and the computer's SSH server running (steps 1 and 2
+above). It isn't on Google Play yet: to install it now, build it from
+[`android/`](android/) as [`CONTRIBUTING.md`](CONTRIBUTING.md#the-android-app)
+explains.
+
+**Pairing, once:**
+
+1. In the ⇄ dialog, choose **Pair a phone**. It shows a line to paste in a
+   terminal on this computer, and a QR code. On Windows, if your user is an
+   administrator, the line goes in PowerShell *as administrator*; the dialog
+   says so.
+2. Paste the line. It adds the phone's key to `authorized_keys`, already
+   restricted to the tunnel: with that key the phone reaches the app's port and
+   nothing else — no terminal and no commands.
+3. Scan the QR with the app. The code works once and for five minutes, and the
+   dialog has to stay open until the phone connects.
+
+The QR carries the phone's private SSH key. This computer generates it, keeps
+it only in memory until the phone uses it and never writes it to disk: don't
+share a picture of that QR. The phone saves your computer's SSH fingerprint on
+the first connection, and if it ever changes, the app refuses to connect and
+tells you.
+
+**To remove a phone**, **Revoke** it in the dialog and delete its line from
+`authorized_keys` (it ends in `agent-workbench-phone`). On the phone,
+**Settings → Forget this computer** deletes its key and its credential.
+
+If notifications arrive late while the phone sits idle, let the app run without
+battery restrictions: **Settings → Open the app's battery settings**. What the
+app keeps on the phone and the permissions it asks for are in
+[`PRIVACY.md`](PRIVACY.md).
+
 ---
 
 ## From source
@@ -252,7 +392,8 @@ untouched.
 Nothing leaves your machine. No telemetry, no analytics, no outgoing network
 calls at all. The exception is the CLI itself at work: the one you open in a
 tab, and the OpenCode server described below, talk to the model provider just
-as they would if you opened them by hand.
+as they would if you opened them by hand. The Android app talks only to your
+computer; [`PRIVACY.md`](PRIVACY.md) lists what it keeps on the phone.
 
 **It never touches your credentials.** There's no login in the interface: if
 you aren't logged in, you log in inside the CLI's terminal and the app doesn't
@@ -299,7 +440,9 @@ and stops being valid when you close the app.
 
 - **In its own configuration directory:** the open tabs, the index cache, the
   notes, the archived sessions, the Antigravity status line script and, if you
-  turn it on, the local copy (or in the folder you choose).
+  turn it on, the local copy (or in the folder you choose). With remote access
+  on, also the list of paired devices: a name, two dates and a hash of each
+  one's credential — never the credential itself.
 - **In the temp folder:** the images you paste; each Antigravity tab's log,
   which contains your messages, readable only by you and deleted on the first
   start once it's more than 24 hours old; and the transcript of a conversation
@@ -311,7 +454,10 @@ and stops being valid when you close the app.
 
 **The server listens only on `127.0.0.1`**, on an ephemeral port, with a random
 per-start token that the WebSocket and every HTTP route require, and it rejects
-requests whose `Origin` isn't its own.
+requests whose `Origin` isn't its own. [Remote access](#remote-access-over-ssh-optional)
+doesn't change any of that: the port becomes a fixed one, still on `127.0.0.1`,
+and a paired device presents its own credential instead of the token. Reaching
+the port is left to SSH, which you turn on and control.
 
 **The git panel is read-only.** No commit, stage or push. With an agent editing
 files, a button that writes history is exactly the kind of thing where, later,
@@ -373,6 +519,26 @@ history saving, and without history there's no conversation or meter. The app
 removes it and lets you know. In normal use —a regular terminal— it never shows
 up.
 
+**From the other computer, `ssh` can't connect** (it times out or is refused).
+The SSH server isn't running on the computer that has the app, or something
+between the two blocks it. On Windows, check that the Wi‑Fi network is set to
+*Private* — the firewall rule the SSH server installs may not cover *Public*
+networks. And a work VPN that blocks the local network cuts this too while it's
+connected: there's nothing the app can do about that. If `ssh` rejects your
+user, a Microsoft or work account may need the name of your profile folder
+(`C:\Users\<name>`) and the account's password, not the PIN.
+
+**From the other computer, the page says "Origin not allowed"** (403). It was
+opened by the computer's name or IP. Open `http://localhost:<port>`, with the
+tunnel using the same port on both ends.
+
+**From the other computer, the page says the session token is missing** (401).
+That browser isn't paired, its access was revoked, or remote access is off.
+Pair it again from the ⇄ dialog.
+
+**The ⇄ dialog says the port is busy.** Another program —often a second Agent
+Workbench— already has it. Close it and restart, or choose another port.
+
 **The Changes panel says the folder isn't a git repository** and it is one.
 Make sure `git` is in the `PATH`. If the message is a different one, it's the
 error git returned, verbatim.
@@ -389,6 +555,7 @@ packages/
     src/agents/   one adapter per CLI: the only part of the server that knows each one
   web/       Vite, React, xterm.js, highlight.js
   shared/    the protocol types, with no `any` at the edges
+android/     the Android app, in Kotlin: the SSH tunnel, a viewer for the interface, the notifications
 ```
 
 A single process serves the interface and the WebSocket on the same port: with
@@ -409,9 +576,18 @@ on what that CLI declares.
 [`ARCHITECTURE.md`](ARCHITECTURE.md) has the hard rules, the code map, what is
 read from each CLI and what is never opened. [`CONTRIBUTING.md`](CONTRIBUTING.md)
 covers how to work on the repository, [`SECURITY.md`](SECURITY.md) how to report
-a vulnerability, and [`CHANGELOG.md`](CHANGELOG.md) what changed in each
-version. Code comments are in Spanish. The screenshots in this README come from
-`pnpm demo:shots`, on made-up data.
+a vulnerability, [`PRIVACY.md`](PRIVACY.md) what is collected (nothing), and
+[`CHANGELOG.md`](CHANGELOG.md) what changed in each version. Code comments are
+in Spanish. The screenshots in this README come from `pnpm demo:shots`, on
+made-up data.
+
+---
+
+## Support the project
+
+If Agent Workbench is useful to you, consider supporting it:
+[Buy Me a Coffee](https://buymeacoffee.com/cvelasquez). The app suggests it
+once per version, in a strip you can close, and never again until the next one.
 
 ---