ClawCodex Web: The Coding Agent in a Browser Tab

What Shipped

ClawCodex v1.6.0 adds a browser client. A three-column shell — session tree, conversation, details — with streaming replies, collapsible reasoning, live tool cards, permission approvals, a prompt queue for follow-ups typed mid-turn, a context meter, slash-command completion, session resume, and light/dark/system themes.

clawcodex web --build      # build the bundle, then serve and open a browser
clawcodex web              # once built

That is the boring half. The half worth writing about is the second view — Trajectory — and the honesty problem we had to solve in the backend before it could exist.

It Is Not a Second Server

The easiest way to build a web UI for an agent is to stand up a web service beside it. We deliberately didn't. clawcodex web is clawcodex serve — the JSON-RPC gateway the desktop app has talked to since v1.5.0 — with the built bundle mounted on it.

  browser  ──HTTP/WS──▶  clawcodex serve  ──▶  in-process agent
   ui-web                /api/ws                 the same one the TUI runs

So a browser tab drives the same in-process agent, over the same socket, against the same saved sessions. One config, one session store, one skills set, one permission system. A session you start in the terminal resumes in a tab, and the reverse. The backend change is additive and gated: with no bundle built, serve is byte-for-byte the desktop backend it always was.

The entire coupling to the protocol lives in four client files — the wire types, the socket client, a tool-name vocabulary, and a pure events-to-nodes reducer. Everything above them is ordinary UI that knows nothing about JSON-RPC. That constraint is what makes a third front end cheap rather than a second codebase to keep in sync.

Trajectory: The Run as a Metered Ledger

Chat answers what was said. Trajectory answers what happened, and where did the time go. It is the same session, replayed as every model request and tool call in order, with what each cost and how long each phase took.

Timeline

Three lanes — input, model, tools. With Duration off, every operation gets equal width and you see the run's shape; with it on, real elapsed widths with idle removed show where the time actually went. A model bar is drawn two-tone: the pale head is time waiting for the first token, the solid tail is generation. Drag across it to filter the ledger to a time range.

Ledger

One line per operation, foldable by turn and by step.

Inspector

Summary (tokens, model, stop reason, request timing), Preview (rendered content), and Raw (the record as JSON).

The single most useful thing it does is separate model time from tool time. "41 seconds" is not actionable. "41 seconds of model, 22 seconds of tools" tells you which half to go look at — whether you are chasing a slow provider or a test suite that takes a minute to run.

The Backend Was Throwing the Numbers Away

Making that view honest required data the gateway had been discarding. The result event only ever reported whole-turn totals, which made a ten-request turn and a one-request turn indistinguishable — you could see what a turn cost in total, but not that most of it went to one runaway request.

So the internal envelope now carries the usage, model, and stop_reason it had already computed and was dropping on the floor, and the gateway translates them into a per-request step.complete event. Both changes are strictly additive: a message without those fields produces exactly the envelope it always did.

Where the Numbers Come From — and Where They Don't

This is the part we want to be precise about, because an observability view that quietly guesses is worse than none.

• Token counts are the backend's own per-request accounting, carried by step.complete. They are not estimates.
• Timings are observed on the client. The gateway reports what happened, not when — so client-side timings include the loopback socket's transport, which is far below the resolution these numbers are read at.
• A metric that could not be measured says so. "First token unavailable" rather than a zero.
• A resumed session rebuilds exactly what its transcript can support. Saved messages carry wall-clock stamps, so tool spans and step spans are recovered; first-token times, per-step usage, and the model id are not in the file, so they stay null and render as the absence they are — never as a zero.

Serving It, and the Token

The gateway is token-gated, and a browser has no way to learn that token on its own. So GET / serves the app with the token inlined as a page global — the same one the desktop shell already scrapes to adopt a running backend. The client reads it, or takes a ?token= from the URL and strips it from the address bar.

That page hands out the token, which is safe exactly as long as the server is reachable from this machine only. clawcodex web therefore refuses a non-loopback --host unless you pass --allow-remote and put your own authentication in front of it. If you want this on a network, that is a decision you make explicitly, not one a default makes for you.

A pip-installed ClawCodex does not ship a built bundle yet: clawcodex web looks for a source checkout's dist, then a packaged one, and tells you how to build it when it finds neither. --build runs the npm build for you, so Node is required for that path.

Working On It

Live reload runs the client against a real backend rather than a mock, which is the only way the protocol layer stays honest:

clawcodex serve --host 127.0.0.1 --port 8317 --token dev
npm run dev            # http://127.0.0.1:5175/?token=dev  (proxies /api to 8317)

Credit Where It Is Due

The visual design and several structural ideas are adapted from the DeepSeek Harness web client, which is MIT licensed. Specifically: the design-token architecture (raw palette to semantic aliases to surface roles, with only the aliases moving between themes), the three-column concession solver, the single-scrollport conversation column with its sticky composer seat, and the tool-card family. The protocol layer is ClawCodex's own gateway, which is a different contract entirely — and the branding, plugin runtime, and module system are not used.

Conclusion

A browser tab is a convenience. A ledger that tells you which request in a turn consumed most of its tokens, and how much of the wall clock was the model rather than your test suite, is a tool. ClawCodex Web ships both, on the same open-source backend the terminal has always run — so you can point it at your own sessions and check the numbers yourself.