Workbench

The Workbench gives every gem a running list of work: a drawer that slides out from the right edge of the terminal. Add items, check them off, and turn one into a scheduled agent run. The list is backed by a plain WORKBENCH.md at the project root, so the agent reads and writes the same file you do.

Projects created before the rename keep their BACKLOG.md and keep working; the drawer reads whichever file the project already has, and crystl backlog still works as an alias for crystl workbench.

How it works

The Workbench is not a private UI database. It’s a WORKBENCH.md file committed at the project root. The drawer renders that file as an editable list and writes every change straight back to it. Because the file is the source of truth, both you (through the drawer) and any agent in a shard work from the same list.

The format is standard GitHub-flavored markdown:

## To Do
- [ ] Wire up the /login route
  Email + password, redirect to dashboard
- [ ] Add rate limiting to auth endpoints

## Done
- [x] Scaffold the Next.js app

• ## Section headers group items. Use whatever sections you like (To Do / In Progress / Done is common).
• - [ ] is an open task, - [x] is done. One task per line.
• Lines indented under a task are its description.

Anything the drawer doesn’t recognize (prose, notes, blank lines) is preserved verbatim. The parser only touches section headers and task lines, so a hand-edit or an agent edit round-trips losslessly.

Opening the drawer

A small pull-tab sits on the right edge of the terminal. Click it to slide the Workbench in; the terminal shrinks to make room. The drawer header names the current gem, and a count shows how many items are still open. The drawer follows the active gem: switch gems and it shows that project’s list.

Working the list

• Add an item: type into the field at the bottom and press return. It joins the last section.
• Add a description: expand a row to reveal an editable description line beneath the title.
• Check it off: click the checkbox. The file is updated immediately.
• Delete: hover a row and click the ×.
• Schedule it: click the clock icon on a row to open the schedule panel prefilled with the task, so a fresh agent completes it at a time you pick. Nothing runs until you save the schedule.

The agent collaborates

When crystl sets up a project for agents, it adds a short note to your CLAUDE.md / AGENTS.md explaining that WORKBENCH.md is the project’s editable task list and how it’s structured. From there the agent treats the Workbench as shared state:

• Reads it to see priorities before starting work.
• Checks items off by editing the file as it finishes them.
• Marks items in progress (- [~]) when it starts one, so you can see what it’s on.
• Appends new items when it finds follow-up work mid-task, so nothing gets lost.
• Claims a task by appending @<shard-name> to its line; the panel shows the claim as a coloured pill (clearable with a click), so you can see which worker took which task during a fan-out.

Because crystl watches the file, every one of those edits shows up live: you see the agent check a box or add a task the instant it writes the file. Edits you make in another editor, or changes from a git operation, are picked up the same way.

This works with any CLI agent that can read and write files. Claude Code, Codex, and Antigravity CLI all collaborate on the Workbench the same way.

From the CLI

Agents (and scripts) don’t have to hand-edit the markdown. crystl workbench reads and updates the list by line index or by stable id, and can drive the panel itself:

crystl workbench list                       # parsed tasks with indexes (free)
crystl workbench add "fix login" --section "Next"
crystl workbench start 12                   # mark [~] in progress
crystl workbench check 12                   # mark [x] done
crystl workbench comment 12 "confirmed on staging"
crystl workbench open                       # slide the panel into view

Also available: uncheck, cycle, uncomment, delete, section, archive, close, and toggle. The edits are Guild-gated. list is free, and so are the panel controls open, close, and toggle: showing you the panel changes nothing. See the CLI reference for the full command table and CLI command tiers for what each one costs.

start, check, and uncheck report the task’s actual state on the server rather than the state you asked for, and they exit non-zero when another agent got there first. In --json mode a failure prints nothing at all, so scripts have to branch on the exit code. Details in state changes report what the server did.

A task’s file index shifts as the list changes, so every task also carries a stable #<hex> id (crystl workbench heal-ids mints one for any task that predates it, and for its comments). Pass --id <hex> instead of an index on cycle, start, check, uncheck, delete, comment, and uncomment; comment and uncomment address a specific comment by its own id the same way. cycle, check, and comment also take --ref <rowRef> to cite the transcript work behind a completion or a comment. Full flags in the CLI reference.

Tasks and comments also carry a few review-oriented fields on the wire (verdict, evidence, verifiedAgainst, severity, reviewRound, duplicateOf, relatesTo, and a per-edit history log), visible in --json output. There’s no dedicated CLI verb for setting them yet.

Why a committed file

A task list that doesn’t show up in the repo tends to die. WORKBENCH.md lives in version control with the rest of the project: it diffs, it travels with the branch, and it’s readable without crystl open. The drawer is a convenient surface on top of it, not a lock-in.