agentbox-app 0.1.7 → 0.1.12

package/README.md

@@ -1,41 +1,55 @@
-# Agentbox
+<p align="center">
+  <img src="docs/readme/icon.svg" alt="" width="96">
+</p>
 
-**An inbox for your coding agents.** You file the work, each item gets its own
-agent in its own thread, and they come back to you with a summary of what they
-did and what they need. You read, you approve or redirect, you move on.
+<h1 align="center">Agentbox</h1>
 
-Today the number of agents you can run is limited by how many windows you can
-keep track of at once. Agentbox drops the chat window entirely and gives your
-agents an inbox instead, so you can run far more of them than you could ever
-watch and only deal with one when it actually needs you.
+<p align="center">
+  <strong>Give your agents an inbox.</strong><br>
+  Run dozens of coding agents at once and only hear from the ones that need you.
+</p>
 
-A macOS app. It runs on the Claude Code or Codex plan you already have, on your
-own machine. There is no server, no account to make, and no extra subscription.
+<p align="center">
+  <a href="#get-it">Get it</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#what-matters-most-goes-first">Priorities</a> ·
+  <a href="#built-for-the-keyboard">Keys</a> ·
+  <a href="#what-this-sends">Privacy</a> ·
+  <a href="LICENSE">GPL-3.0</a>
+</p>
 
-## How it works
+<p align="center">
+  <img src="docs/readme/inbox.webp" alt="Twelve agents finish their work and their rows arrive in the inbox, each one saying what it did and what it needs" width="100%">
+</p>
+
+<p align="center">
+  Free and open source. Runs in your browser or as a Mac app, on the Claude Code or Codex plan you already have.<br>
+  No server, no account, no extra subscription.
+</p>
+
+---
+
+## Install
+
+There are two ways to run it: in the browser, or as a Mac app. Both need Node 22 and Claude Code or Codex installed and signed in.
+
+**In your browser.** One command, nothing to install first:
+
+```
+npx agentbox-app
+```
+
+It starts on your machine and opens a tab. On Linux that open goes through `xdg-open`. Nothing is hosted: it listens only on `127.0.0.1`, and the address carries a key that is new every run. Add `--help` to see the options. `--no-open` prints the address and leaves the browser to you.
+
+From a checkout, build the screen once, then start it the same way:
+
+```
+npm install
+npm run build
+npx agentbox-app
+```
 
-1. **File the work.** Paste a list, send over a board of issues, or type one
-   task. Twelve at once is a normal day.
-2. **Walk away.** Each item gets a headless agent in its own thread. Nothing
-   needs you while they run, so go and do something else.
-3. **Come back to an inbox.** Every thread opens with what the agent did and
-   what it wants from you, in two lines you can read at a glance.
-4. **Answer with one key.** Press `E` to approve and merge. Press `1`, `2` or
-   `3` to pick an option an agent offered. Type a sentence and send it back if
-   none of them is right.
-5. **Reach inbox zero.** The rows you approved are done. The ones you
-   redirected are already working again.
-
-The job this leaves you is reviewing what agents made and deciding whether it
-is good enough, rather than watching them make it. That is the whole argument
-for an inbox: a person in the loop where judgment is worth something, and
-nowhere else. An agent that got a failing test to pass by editing the test is
-exactly the moment you want to be asked.
-
-## Get it
-
-You need a Mac, Claude Code installed and signed in, and Node 22 to build.
-Codex is optional and is picked up when it is there.
+**As a desktop app.** Build it from this repo. `npm start` is the desktop command on Omarchy and on a Mac:
 
 ```
 git clone https://github.com/savannahfeder/agentbox.git
@@ -44,33 +58,153 @@ npm install
 npm start
 ```
 
-`npm start` builds the renderer and launches the app. On first run it walks you
-through connecting Claude Code and choosing a folder to work in.
+On Linux, `npm install` puts `agentbox` on `~/.local/bin` and adds the app to the launcher. The entry is `$XDG_DATA_HOME/applications/agentbox.desktop` (`~/.local/share/applications` when that variable is unset), and it runs `agentbox`. That command starts this checkout. Open the app from the launcher.
+
+`npm start` builds the app and opens it. On first run it walks you through connecting Claude Code or Codex and choosing a folder to work in.
+
+On macOS, the system may ask to let Terminal find devices on your local network. Agentbox does not need that, so Don't Allow is fine.
+
+## The chat window is the bottleneck
+
+Today you run agents in chat windows and terminals, and you wait for each one
+to finish before you prompt it again. So the number of agents you can run is limited 
+by the number of windows you can keep track of.
+
+<p align="center">
+  <img src="docs/readme/before.webp" alt="Five terminal windows, each with an agent waiting on a different task" width="60%">
+</p>
+
+Models are now good enough that most tasks do not need watching. They need
+someone to review the work at the right moment. Agentbox drops the chat window
+and gives each agent a row in an inbox instead, so you can run far more of them
+than you could ever watch and only deal with one when it actually needs you.
+
+## How it works
+
+### 1. File the work
+
+Paste a list, send over a board of issues, or type one task. Each item becomes
+its own row, and each row is its own agent, already working.
+
+<img src="docs/readme/file.webp" alt="Twelve issues from a project board go over in one message and appear as twelve agents working" width="100%">
+
+### 2. Walk away
+
+Nothing needs you while they run. Go to lunch. A row only comes back to you
+when its agent is done or stuck, so a hundred agents working is as quiet as one.
 
-## Keys
+<img src="docs/readme/scale.webp" alt="A wall of over a hundred agents working, with only the four that need a person lifted out" width="100%">
 
-It is built for the keyboard. Arrows move, Enter opens, `E` approves the
-recommendation or marks a row done, `1`/`2`/`3` pick an option an agent
-offered, `R` replies, `S` snoozes, `C` composes, Tab cycles views, `Z` undoes,
-and `⌘K` opens the palette, which reaches almost everything else.
+### 3. Come back to an inbox
 
-## Make it yours
+Every row opens with what the agent did and what it wants from you, in two
+lines you can read at a glance. Most of the time the answer is yes. Press `1`
+and it merges, and the next one is already in front of you.
+
+<img src="docs/readme/answer.webp" alt="An agent's summary card reads Snooze survives a restart now; pressing 1 merges it and the next card arrives" width="100%">
+
+### 4. Answer however fits
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <img src="docs/readme/designs.webp" alt="An agent offers three directions for an empty inbox, drawn in the real app, and option two is picked" width="100%"><br>
+      <strong>Pick a design.</strong> Ask for options before anything is built,
+      and agents come back with versions drawn in your actual app. Pick one and
+      that one gets built.
+    </td>
+    <td width="50%" valign="top">
+      <img src="docs/readme/sendback.webp" alt="Two versions of onboarding copy, and a typed reply asking for something shorter is sent back to the agent" width="100%"><br>
+      <strong>Send it back.</strong> When none of the options is right, type a
+      sentence. The agent picks up where it left off, and the row comes back
+      to you when it is done.
+    </td>
+  </tr>
+</table>
+
+### 5. Stay the person in the loop
+
+Your job stops being watching agents work. It becomes reviewing what they made
+and deciding whether it is good enough. This agent got a failing test to pass by
+editing the test instead of the code, which is exactly the moment you want to be
+asked. Code changes open right beside the row.
+
+<img src="docs/readme/loop.webp" alt="An agent reports the usage test passes; the change beside it shows it edited the expected value in the test, and the reply sends it back to fix the code" width="100%">
+
+## What matters most goes first
+
+Twenty agents means twenty things competing for your attention and for a limited
+number of running sessions. Agentbox keeps one order and uses it for both.
+
+- **Tag a task** Urgent, High, Medium or Low, when you file it or later from `⌘K` or `Ctrl+K`.
+- **Rank your projects** once by dragging them into order. A project's place
+  counts for more than any single task's tag, so your most important project
+  never waits behind a side one.
+- **The order decides who starts.** When there are more tasks than session
+  slots, the queue starts the most important first. An answer you have already
+  given wins a tie against new work, so replies never pile up.
+- **Urgent rises to the top.** Urgent rows sit above everything else in the
+  inbox under their own heading.
+- **Only your tags count.** An agent cannot promote its own work. If it says
+  its task is urgent, that is ignored.
+
+<img src="docs/readme/inbox-urgent.png" alt="The inbox with two urgent rows lifted above everything else under an Urgent heading" width="100%">
+
+<p align="center">
+  <img src="docs/readme/priority-palette.png" alt="The command palette showing Priority Urgent, High, Medium and Low for the selected row" width="60%"><br>
+  <sub>Any row's priority is a <code>⌘K</code> or <code>Ctrl+K</code> away.</sub>
+</p>
+
+## Built for the keyboard
+
+<img src="docs/readme/keys.webp" alt="The keys E, R, J, K and the number row light up over the inbox, then the command palette opens on the themes" width="100%">
+
+| Key | Does |
+|---|---|
+| `J` `K` or arrows | Move through the inbox |
+| `Enter` | Open a row |
+| `E` | Approve the recommendation, or mark a row done |
+| `1` `2` `3` | Pick an option an agent offered |
+| `R` | Reply |
+| `N` | New thread |
+| `L` | Later: put a task off until a time you pick |
+| `S` | Show or hide the summary, in an open task |
+| `Z` | Undo |
+| `⌘K` or `Ctrl+K` | Everything else |
 
 Fifteen skins, each in light and dark, from plain slate to woodblock and riso
-prints. Press `⌘K` and type "theme", or open Settings and then Look.
+prints. Press `⌘K` or `Ctrl+K` and type "theme". `Ctrl+K` is the same palette on Linux, where there is no Command key.
 
-## Config
+## Runs on the plan you already have
+
+<img src="docs/readme/engines.webp" alt="The app's icon wired to Claude Code on one side and Codex on the other" width="100%">
+
+Agentbox drives Claude Code and Codex on your own machine, signed in with your
+own subscription. When you first open it, it finds the agents you have already
+set up and offers to bring them in. There is no server, no account to make, and
+nothing new to pay for.
+
+---
+
+## Reference
+
+<details>
+<summary><strong>Config</strong></summary>
+
+<br>
 
 `zero.config.json` in the repo root, gitignored and machine-specific. Every
 default works unset and they all live in `main/config.mjs`. The ones that
 matter:
 
-- `storeRoot`: where the store lives. Defaults to a folder named after the app
-  in your home directory.
+- `storeRoot`: where the store lives. On macOS this defaults to a folder
+  named after the app in your home directory. On Linux it defaults to
+  `$XDG_DATA_HOME/agentbox`, which is `~/.local/share/agentbox` when that
+  variable is unset.
 - `claudeBin`: the binary to run. The app finds `claude` itself if you leave
   this alone.
 - `maxConcurrentSessions`: how many agents run at once. The queue absorbs the
-  rest.
+  rest, in priority order.
 - `sessionArgs`: what a spawned session may do. **The default grants only the
   store tools**, so an agent can read the store, file questions and update work
   items, and nothing else. To let agents edit code and run commands, opt in:
@@ -86,28 +220,40 @@ matter:
   and replying resumes the same session, like a thread.
 - `diagnostics`: `false` turns off the counts described below.
 
-## What this sends
+</details>
+
+<details id="what-this-sends">
+<summary><strong>What this sends</strong></summary>
+
+<br>
 
 Nothing, unless you are running a build that was signed and released with a
 PostHog key baked into it. A build made from this repo has no key, so a clone
 and a fork are silent, and with no key the whole path is off at every send.
 
-A released build counts seven things, and they are counts:
+A released build counts twelve things, and they are counts:
 
 - the app was opened
+- the app was used today, once a day
+- a setup step was reached, by its number
 - first run finished
 - a repo was connected
 - an agent was seen
+- a task was written
 - a task was opened
 - a reply was sent
 - a task finished
+- an agent started work
+- an agent stopped work
 
 Each carries a random install id, the app and platform version, and at most
-four other things: how long something took, how many of a thing there were,
-which kind of row it was out of six fixed words, and whether an agent or you
-did it. No file contents, no prompts, no paths, no titles, nothing you typed.
+seven other things: how long something took, how many of a thing there were,
+which kind of row it was out of six fixed words, whether an agent or you did
+it, whether an agent's run failed, whether it happened in setup's practice
+project, and which coding agent ran it, Claude Code or Codex.
+No file contents, no prompts, no paths, no titles, nothing you typed.
 `shared/analytics-events.mjs` is the whole list, and anything a caller attaches
-beyond those four is dropped rather than sent, so nobody can widen it by
+beyond those seven is dropped rather than sent, so nobody can widen it by
 accident. Crash reports travel the same way and are scrubbed first
 (`shared/crash-scrub.mjs`).
 
@@ -124,7 +270,12 @@ The thing that sends the most is not ours at all. This app drives Claude Code
 and Codex, so whatever a session reads and writes goes to Anthropic or OpenAI
 under their terms, exactly as it would if you ran those tools yourself.
 
-## How it is built
+</details>
+
+<details>
+<summary><strong>How it is built</strong></summary>
+
+<br>
 
 Sessions are cattle and the store is the truth. The durable state is a folder
 on disk at `storeRoot`, written through `main/store/` so the fold rules exist
@@ -141,7 +292,12 @@ agent noticing.
 - `tests/` the suite, which is large and is the documentation of record for how
   any of this is meant to behave.
 
-## Develop
+</details>
+
+<details>
+<summary><strong>Develop</strong></summary>
+
+<br>
 
 ```
 npm run dev        # vite HMR plus electron
@@ -151,26 +307,32 @@ npm test
 Useful modes:
 
 - `ZERO_FIXTURES=1` canned data, with no store and no agents touched
-- `ZERO_FIXTURES=empty` inbox zero, which is the reward browser
+- `ZERO_FIXTURES=empty` inbox zero
 - `ZERO_NO_SUPERVISOR=1` never spawn sessions
 - `ZERO_SCREENSHOT=/tmp/x.png` capture the window and quit
 
 The same fixture worlds are reachable off the url, which is how the
 `scripts/shot-*.mjs` family photographs them: `?fixtures`, `?fixtures=empty`,
-`?fixtures=crowded`, `?fixtures=mock`, `?shelf=on`, `?working=3`. `?engines=`
+`?fixtures=crowded`, `?fixtures=mock`, `?working=3`. `?engines=`
 picks which coding agents the fixture Mac has, where nothing is one agent,
 `?engines=missing` is the gate open with Codex not found, and `?engines=claude`
 or `?engines=codex` give two.
 
 To open the app as somebody who has never seen it, with its own throwaway home
-and nothing of yours inside it, press `⌘K` and choose "Open agentbox as a new
-user". `npm run fresh` does the same from a terminal.
+and nothing of yours inside it, press `⌘K` or `Ctrl+K` and choose "Open Agentbox as a new
+user". `npm run fresh` does the same from a terminal. `ZERO_NO_SUPERVISOR=1` applies to `npm start` and to `npx agentbox-app`.
 
 The app is named in exactly one place, `shared/product-name.mjs`. Change it
 there and run `node scripts/product-name.mjs --write`, and everything else
 follows. The `zero` and `ZERO_` prefixes through the code are the name it had
 first and are load-bearing in places, so they are left alone.
 
+The pictures in this README live in `docs/readme/`. The two stills are taken of
+the real app by `scripts/shot-readme.mjs`; the moving ones are cut from the
+launch film.
+
+</details>
+
 ## Licence
 
 GPL-3.0-or-later. See [LICENSE](LICENSE).

package/bin/agentbox.mjs

@@ -12,11 +12,11 @@
 
 import path from 'node:path';
 import fs from 'node:fs';
-import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { bootHeadless, createServer, newToken } from '../main/serve.mjs';
+import { appHome } from '../main/store/home.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const appDir = path.dirname(here);
@@ -43,9 +43,13 @@ if (args.includes('--help') || args.includes('-h')) {
 
 // WHERE THE STORE LIVES. A copy run out of npm has no folder of its own to
 // write into, and writing inside node_modules would be thrown away by the next
-// install. `~/.agentbox` is the plain answer and `--dir` is the escape hatch.
+// install. The default is appHome(): a dot-folder already on disk, else the
+// XDG data directory on Linux and `~/.agentbox` on macOS, where this command
+// has always kept it. Not the desktop config's default, which on macOS is
+// `~/Agentbox` and would open every existing Mac user on an empty inbox.
+// `--dir` and AGENTBOX_HOME are the escape hatches.
 const dataDir = path.resolve(
-  flag('dir', process.env.AGENTBOX_HOME ?? path.join(os.homedir(), '.agentbox')),
+  flag('dir', process.env.AGENTBOX_HOME ?? appHome()),
 );
 fs.mkdirSync(dataDir, { recursive: true });
 
@@ -56,6 +60,17 @@ if (!fs.existsSync(path.join(dist, 'index.html'))) {
 }
 
 const booted = await bootHeadless({ dataDir, appDir, userDir: dataDir });
+// ZERO_NO_SUPERVISOR: the desktop already honors this (main/main.mjs). This
+// entry is the same inbox, so a launch that asks for no agents must not start
+// them here either.
+if (!process.env.ZERO_NO_SUPERVISOR) {
+  // Whoever was signed in to the team last time is signed in again.
+  booted.team?.start().then(() => booted.supervisor.wake?.()).catch((err) => console.warn(`team: ${err.message}`));
+  // AND THE AGENTS' CLOCK, as the desktop starts it (main/main.mjs). Without it a
+  // tab only moved work when something woke the supervisor: a queued thread sat
+  // queued and a scheduled one never fired (found 2026-10-01 on a test copy).
+  booted.supervisor.start();
+}
 const token = newToken();
 const server = createServer({
   channels: booted.channels,

package/briefs/message-rules.md

@@ -51,13 +51,30 @@ failing to answer it.
 
 Never give a number you did not measure. "I don't know" is an answer.
 
-THE ANSWER IS IN THIS MESSAGE, NOT IN A FILE BESIDE IT.Write the finding, the
+THE ANSWER IS IN THIS MESSAGE, NOT IN A FILE BESIDE IT. Write the finding, the
 numbers and the recommendation here; make no report to hold them. What you
 would have made anyway, a design, an app running at a port, a change to
 review, gets its path or address on its own line, and a design or a change
 opens beside the message by itself. Not the source files you edited, which are
 no use to them.
 
+A PICTURE YOU SHOW IS SAVED IN THE PRODUCT'S DOCS FOLDER, the one your brief
+names, in designs/ under this task's id, and named by its full path. Not in
+your code checkout, which is deleted once the work ships, and never in /tmp,
+which the app will not draw at all.
+
+WHAT THE APP CAN SHOW, so you can lay out what you made the way it reads best:
+- A picture's path, anywhere in the message, is drawn right there at full
+  width, and a click opens it. It is drawn as a block, so inside a sentence or
+  a bullet it splits the line.
+- A folder's path on a line of its own draws its newest six pictures as a grid.
+- An html page in designs/ opens beside the message by itself, so one page can
+  set several options side by side with notes on each.
+- A sound or a film plays where it is named; a localhost address opens beside
+  the message. Headings, lists, tables and bold all draw.
+The arrangement is yours. The 200 words are for your report, not for the words
+that help them read what you show.
+
 Steps they must take are a numbered list, five at most, the first one doable now.
 
 If anything at all is left for them to decide, end with an Options section, in
@@ -74,8 +91,8 @@ ended up with, and read them back together: if someone said option one
 out loud, it has to answer line one. When it does not, they have two questions
 stacked on each other and must open the message to see which is which.
 
-Two options is a fine list and three is the most that helps. Mark exactly one
-recommended. Every option has to be something you would start on without asking
+Offer one to four options; two or three is usual, and one is fine. Mark exactly
+one recommended. Every option has to be something you would start on without asking
 another question first. Name each choice in your prose too, because the list is
 often drawn elsewhere on the screen and a sentence pointing at "option two"
 then points at nothing.
@@ -88,6 +105,10 @@ call the run settled to save yourself the asking, or make them type "merge it"
 because you did not offer it. The only run that ends with no options
 is one that changed nothing.
 
+NEVER OFFER WHAT YOUR RUN ALREADY DID. Shipped, merged or sent: line one says
+so, and no option offers it again. When only closing is left, offer the one
+option "Close this task", which closes it without starting another run.
+
 AND READING CHANGES NOTHING. Reading, searching, explaining and answering
 leave the world as they found it, so a question answered ends with no options,
 and that is the right ending and not a lazy one. NEVER INVENT A PICK OUT OF