Worktable

Worktable

Worktable gives your terminal coding agent a local browser canvas. Instead of describing an architecture change or a bug fix in a wall of text, the agent draws it as a page you can open, read, and point at - and when you select something and ask about it, the question lands back in the terminal conversation.

Real footage: the agent draws a page, you select any part and ask, and the answer comes back anchored to what you pointed at.

Why

When a coding agent explains a big change - a new module boundary, a refactor, why a bug happened - it usually hands you a mountain of text. You have two options: trust it, or grind through the whole thing to check it. Neither is great. I kept hitting this myself: the model clearly understood the change, but I couldn't see it, so I couldn't audit it without re-reading everything.

A picture fixes that. Give me a diagram of the call path, a before/after of the module graph, a flowchart of the failure, and I understand in seconds what a page of prose was trying to say - and I can spot the part that's wrong.

Worktable's whole job is to make that the default. It nudges the model to render its work as a local page you can actually interrogate. You shouldn't have to trust the wall of text - you should be able to look at it.

Plenty of tools draw diagrams. What matters here is the loop - a local canvas, a way to point at any part of it, and your question landing back in the agent's conversation anchored to exactly what you pointed at.

What it looks like

The agent publishes an artifact and the canvas opens on 127.0.0.1. Select any region - a box in a diagram, a line of a plan, a cell in a table - and an "Ask about this" pill hands off to a side drawer where you type the question. It travels home to the terminal anchored to exactly what you selected, and the agent's answer fills in next to your question. It works from inside a model-drawn HTML page too, not just plain prose.

Install as a Claude Code plugin

The quickest path, and all an end-user needs. Add the self-hosted marketplace, then install the plugin:

/plugin marketplace add dannykim32/worktable
/plugin install worktable@worktable

That wires the MCP server, the ask-back hook, and the canvas guidance skill in one step — the plugin ships a committed bundle/, so it works right after Claude Code clones the repo. Restart Claude Code, run /mcp to confirm worktable is connected, then ask for something visual — "walk me through this architecture."

• Update: /plugin update worktable@worktable, then restart Claude Code.
• Uninstall: /plugin uninstall worktable@worktable. To also remove stored

data, see [Local data](#local-data).

• Other hosts (Codex CLI, etc.): the two-line install is Claude Code only. Other

MCP hosts need a one-time manual setup — see [docs/install.md](docs/install.md#codex-and-other-mcp-hosts).

• Firewalled / no npm: use the self-contained tarball — see

[docs/install.md](docs/install.md).

Local data

Worktable keeps all state under ~/.worktable// (0700 dirs, 0600 files) and it never leaves your machine: the capability token, every published artifact version, the ask-back queue and answers, and any pasted images. Nothing is auto-expired — versions and images are retained until you remove them. To clear one project's data, delete its workspace directory; to wipe everything, remove ~/.worktable. (Do it while Claude Code isn't running; the server recreates what it needs on next launch.)

Build from source (contributors)

Everything below is for hacking on Worktable itself — end-users don't need it. Requires Bun for dev and Node 20+ to run.

bun install
bun run build
bun test          # ~282 tests

Register the canvas with Claude Code for every session:

./install.sh

To also wire a specific project so the agent uses the canvas proactively (drops in a guidance snippet + the ask-back hook):

./install.sh /path/to/your/repo

Restart Claude Code, run /mcp, and worktable should show connected. Then ask the agent to show you something - "walk me through this architecture on the canvas."

Firewalled machine with no npm access? docs/install.md covers the self-contained bundle and a network-free registration helper.

How it works

Terminal agent  ──MCP (stdio)──▶  Canvas Server  ──127.0.0.1──▶  Browser canvas
 (Claude Code)                    (this project)                  (you read + select)
      ▲                                                                  │
      └──────────────  ask-back, anchored to your selection  ◀───────────┘

The terminal stays the driver; the canvas is a companion, not a chat client. The agent publishes versioned artifacts to a capability-gated local server, which serves them to the browser. Your selection-anchored questions - ask-backs - flow back into the conversation.

There are exactly three artifact types, on purpose:

• html - the primary type. A self-contained, model-authored HTML/CSS/SVG page:

bespoke layout, real diagrams, whatever the content needs. The model writes it with the same design process it uses for native artifacts.

• prose - a long markdown answer, for substance that reads better as text.
• absence - honest absence. When the model can't render something truthfully,

it declines and says why instead of faking a picture. A first-class outcome, not an error.

Security

Model-authored HTML is untrusted input, so Worktable never trusts it into the page. An html artifact is served verbatim from a second 127.0.0.1 origin into an iframe that is sandbox="allow-scripts" and never allow-same-origin, under a header-delivered CSP whose script-src is a per-response nonce the model never sees. The model's own ` and onclick` have no nonce, so they never run - script execution is impossible by construction, not by filtering. The capability token lives only in the parent origin and never enters the frame.

Anything that could phone home without a click - `, an external - is rejected at ingest by a zero-dependency guard that **rejects the whole artifact rather than silently stripping it**, because a stripped artifact can tell a different story than the one you reviewed. That boundary is backed by 80+ adversarial test fixtures. See docs/adr/ for the reasoning and src/server/frameGuard.ts` for the code.

Live model JavaScript (Tier 2) is deliberately deferred - the static surface is what ships today, and it's labeled as such.

Layout

| Where | What | |-------|------| | CONTEXT.md | The domain glossary - the exact terms used in code and docs | | docs/adr/ | Every architectural decision, with the why and the rejected alternatives | | docs/STATUS.md | Current status, milestone history, and open follow-ups | | src/server/ | The Canvas Server (MCP) - artifact store, canvas HTTP, the frame-isolation boundary | | src/canvas/ | The browser canvas - renderers, gallery, ask-back drawer | | hooks/ | The Claude Code UserPromptSubmit hook that delivers queued ask-backs | | docs/history/ | The original PRD, issue tracker, and QA evidence, kept for the record |

Status

{html, prose, absence} is the surface; the full loop works end to end. For the running log, milestone history, and known follow-ups, see [docs/STATUS.md](docs/STATUS.md).

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for build, test, and the ADR convention.

License

MIT - see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dannykim32
• Source: dannykim32/worktable
• License: MIT

Install and usage instructions live in the source repository linked above.