Workbench

Updated June 21, 2026

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 send one straight to the active agent. 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 ×.
  • Send to the agent: click the send icon on a row to drop its text (and description) into the active shard’s prompt, ready for you to review and run. Nothing is submitted automatically.

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 the drawer 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 with stable line indexes, 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 open                       # slide the panel into view

Also available: uncheck, cycle, delete, section, close, and toggle. Edits and panel controls are Guild-gated; list is free. See the CLI reference for the full command table.

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.