Project board
The project board is a Beads-backed Kanban view for each main repository. Switch to Kanban from the titlebar, create tickets with prompts, drag cards across lanes, and launch agent sessions with Create & Start or Start work.
Opening the board
| Option | What it does |
|---|---|
Option+4 | Switch to Kanban view (rebindable in Settings → Hotkeys) |
Kanban titlebar tab | Workarea view alongside Agents, Source, GitHub |
Quick sessions do not have a Kanban project view — the titlebar tab is disabled with tooltip: Quick sessions do not have a Kanban project view.
The board loads in a bundled WKWebView (tasks-placeholder.html) with a native Beads bridge.
Board UI
| Option | What it does |
|---|---|
Board | Active view tab |
Automations / Runs / Triage | Disabled — Coming soon! |
+ Ticket | Create new ticket (board tab) |
Refresh project | Manual board refresh icon |
Search tickets | Filter field in ticket filters bar |
Filter by priority | All, Urgent, High, Medium, Low |
Filter by estimate | All, None, XS, S, M, L, XL |
Auto-refresh runs every 8 s; labels refresh every 60 s. All bd commands run through bundled gxserver Beads — not a shell bd on PATH.
Kanban lanes
| Option | What it does |
|---|---|
Backlog | Beads status: backlog |
Todo | Beads status: open |
In Progress | Beads status: in_progress |
Test | Beads status: test |
Review | Beads status: review |
Done | Beads status: closed |
Lane headers show ticket count and a + button (aria: Add ticket to {lane}). Cards display IDs like ZMX-12 from beadsDisplayKey, plus priority, labels, estimate, and conversation link when present.
New Ticket dialog
| Option | What it does |
|---|---|
Priority | Ticket priority metadata |
T-shirt | Estimate (XS–XL) |
Labels / Blocking / Blocked by | Beads relationship fields |
Title | Optional — auto-generated from prompt when empty |
Prompt | Required — becomes agent work context |
Start work | Footer section — agent + location selectors |
Create | Create bead only, refresh board |
Create & Start | Create bead, close dialog, launch agent immediately |
Cmd+Enter submits in ticket dialogs. Escape clears the search field.
Create & Start workflow
- Fill Prompt (required) and optional metadata.
- Start work section — pick Agent (aria: Agent for Create and Start) and Location.
- Location: Current project or New worktree.
- Create & Start closes the dialog immediately, creates the bead, then launches agent with buildAgentWorkPrompt().
- Session focus matches sidebar session-card behavior after terminal is ready.
- Title generation and label assignment are secondary — prompt drives the session.
Edit ticket & Start work
- Edit ticket dialog — same metadata plus Conversation section and Add comment.
- Footer: Delete (two-click confirm), Start work / Go to Session, Save.
- Right-click card context menu — Start work / Go to Session, Delete.
- Go to Session when a conversation link already exists; Start work launches a new agent run.
Beads setup notices
| Option | What it does |
|---|---|
Initialize Beads for this project | Shows copyable bd init command when .beads is missing |
Beads CLI unavailable | Broken bundled Beads binary |
Project board unavailable | Other gxserver or bridge errors |
gxserver runs prefix reconciliation (ensureIssuePrefix) before create/list so ticket IDs use your configured display key.
Project settings
Settings → Projects → per main project:
| Option | What it does |
|---|---|
beadsDisplayKey | Ticket key prefix — 3 letters like ZMX (Save Ticket Key) |
beadsDirectory | Absolute path to .beads directory (Save Beads Directory) |
Settings → Agents → Default Prompt Agent drives board Start Work, Create & Start, and Git helper prompts.
Shortcuts
| Option | What it does |
|---|---|
Option+4 | Switch to Kanban view |
Cmd+Enter | Submit in New Ticket / Edit ticket dialogs |
Escape | Clear ticket search field |
Workarea views use Option+1..4: Agents, Source, GitHub, Kanban — all rebindable in Settings → Hotkeys.
Tips
- Run bd init in the repo root before first board use — Ghostex shows the exact command when Beads is missing.
- Use New worktree location for isolated feature work tied to a ticket.
- Set beadsDisplayKey early so ticket IDs stay stable across the team.
- Create & Start is the fastest path from idea to running agent — Create alone is for backlog grooming.
- Conversation links on tickets enable Go to Session for resuming prior agent work on the same bead.