04.26Work tracking
Beads skills: Claude Code skills for the Beads issue tracker
Two Claude Code skills AR Labs built for the Beads issue tracker: one routes tracker operations through our policy, one links a session to its task.
On this page
These are two Claude Code skills AR Labs wrote for working with Beads, Steve Yegge's open-source issue tracker for coding agents (AI agents that write code, such as Claude Code or Codex). Use the first, vox-beads, before any agent reads or changes tracker state; use the second, link-session, when you want a Claude Code conversation recorded on the task it serves so it can be resumed from that task later. A bead is one tracked task in Beads; beads form a tree of parents and children with dependency edges between them, and everything is operated through the bd command. Beads itself is Steve Yegge's work; the two skills are ours. How we use Beads to plan coding work is described in task graphs with Beads.
How they work
vox-beads is six numbered lines long. It holds no rules of its own; it tells the agent where the rules are. Before any tracker operation, the agent reads our Beads policy document and uses the installed bd command's own --help for exact syntax. Before its first write, it runs bd context and checks which repository, database and server it is about to write to. If a bead carries metadata owned by a particular methodology (a namespaced set of fields that a process such as our coding pipeline owns), the agent loads that methodology's rules before interpreting or changing it.
link-session records the current Claude Code session's name, its identifier, the time of linking and the terminal it was running in (tmux, iTerm or similar) as metadata on a chosen bead, and appends the same facts as a comment so that earlier links are kept when a session is re-linked. Later, the bead tells you which conversation to resume. The skill only links to a task-level bead: an epic, the container that groups tasks, is used to navigate to the right task and is never itself the target.
flowchart LR
A["Agent needs tracker state"] --> V["vox-beads: load policy, check target"]
V --> M{"Methodology metadata?"}
M -->|"Yes"| L["Load that methodology first"]
M -->|"No"| G["Generic operations only"]
S["Current conversation"] --> K["link-session"]
K --> B["Bead holds session name and ID"]The judgement they encode
Keep three kinds of rule apart. Facts about the vendor's tool, our own policy, and the contract of any methodology are maintained in separate places, and the router copies none of them, so none can drift from its source.
A label is not a mode. A project or classification label identifies work; it does not select how the work should be run. Only an explicit choice activates a methodology.
Preserve what you do not own. Unknown namespaced metadata is kept intact. If its owner is not available, the agent limits itself to safe reads and ordinary fields.
Check where you are writing. Before the first write, the agent verifies the repository and database, because an inherited setting can point a session at the wrong one.
Name a conversation before linking it. Claude Code resumes a named session reliably and an unnamed one less so, so if the session has no name, link-session warns and offers to stop while you rename it.
Example
Illustrative example. Linking a session:
> /link-session
This session is not linked yet.
Which epic does this work belong under?
> Skills pages for the website
Children of that epic:
1. Write the skills section pages (open)
2. Diagrams for the skills section (open)
Link to which task, or create a new one?
> 1
Linked. Session "skills-pages-writing" is stored on the task, with
its ID and terminal. Resume later with: claude --resume "skills-pages-writing"