# Gc Work

> Finding, creating, claiming, and closing work items (beads)

- Skill: `gastownhall/gc-work` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gastownhall/gc-work`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gastownhall/gc-work/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gastownhall (https://skillmd.com/u/gastownhall)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gastownhall/gc-work

---


# Work Items (Beads)

Everything in Gas City is a bead — tasks, messages, molecules, convoys.
The `gc bd` CLI is the primary interface for bead CRUD.

## Rig-scoped beads

Each rig has its own `.beads/` database with its own ID prefix (e.g.
`fe-` for frontend, `be-` for beads). **A bead must live in the
same database as the agent that will work on it.** When you sling a bead
to a rig-scoped agent, sling operates on the agent's rig database — so
the bead must already exist there. The bead ID prefix tells you which
rig it belongs to.

Use `gc rig list` to see rig names, paths, and prefixes.

## Creating work

**Use `--rig` to create beads in the right database.** If the work will
be dispatched to a rig-scoped agent, create the bead in that agent's rig:

```
gc bd create "title" --rig frontend         # Create in frontend's db (fe- prefix)
gc bd create "title" --rig beads            # Create in beads db (be- prefix)
gc bd create "title"                        # Create in current directory's .beads/
gc bd create "title" -t bug                 # Create with type
gc bd create "title" --label priority=high  # Create with labels
```

## Finding work

```
gc bd list                                # List beads in current .beads/
gc bd list --rig <rigname>                # List beads in a specific rig
gc bd ready                               # List beads available for claiming
gc bd ready --label role:worker           # Filter by label
gc bd show <id>                           # Show bead details
gc ready                                  # Same frontier, federated over every store the city uses
```

On a city that serves a coordination class from its own `[storage]` binding,
`gc bd ready` (and `gc bd list --ready`) is refused with exit 1: it reads one
ledger and the city's ready set spans more than one. Use `gc ready` there. It
takes `--assignee`, `--unassigned`, `--metadata-field`, `--exclude-type`,
`--exclude-label`, `--sort`, `--limit`, `--include-ephemeral`, `--status` and
`--json` — not the label, parent, type or priority selectors `gc bd ready`
forwards.

## Claiming and updating

```
gc bd update <id> --claim                 # Claim a bead (sets assignee + in_progress) — races in a multi-agent city; prefer `gc hook --claim` there
gc bd update <id> --status in_progress    # Update status
gc bd update <id> --add-label <key>=<value>  # Add/update labels
gc bd update <id> --append-notes "progress..."  # Append a note (does not replace existing notes)
```

## Closing work

```
gc bd close <id>                          # Close a completed bead
gc bd close <id> --reason "done"          # Close with reason
```

## Hooks

```
gc hook [agent]                        # Show routed work for an agent (defaults to $GC_AGENT)
gc hook --claim                        # Atomically claim one routed work item onto this agent's hook
```