beads

Manages beads task issues across multi-repo umbrella workspaces via in-process beads_* tools.

Updated Jul 22, 2026
One-click install
npx skills add https://github.com/johnstegeman/pi-packages --skill beads-johnstegeman
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: beads
Source: https://github.com/johnstegeman/pi-packages/tree/main/packages/pi-beads/skills/beads
Command: npx skills add https://github.com/johnstegeman/pi-packages --skill beads-johnstegeman

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Coordinating issue tracking across a multi-repo umbrella workspace is error-prone: tasks live in per-repo beads databases while reads must span an aggregate view, and writing to the wrong repo breaks ownership and sync. This Skill provides the operating manual for reading, creating, updating, closing, and linking beads issues correctly through the in-process beads_* tools. ## Core Features & Use Cases - Cross-repo reads: Query ready, open, stale, or blocked issues across every repo from the aggregate view using beads_ready, beads_list, beads_show, and beads_deps. - Routed writes: Create, update, close, reopen, and comment on issues with automatic routing to the owning repo based on the id prefix, including ephemeral wisp creation and promotion. - Dependency and epic management: Link blockers within a repo, build epic hierarchies with parent/child tasks, and instantiate molecule workflows with gates. - Use Case: While triaging a sprint, call beads_ready with a label filter to find unblocked work, claim an issue, create subtasks under an epic in the correct repo, then close everything with a reason when done. ## Quick Start Ask the assistant to show ready beads tasks across all repos and claim the highest-priority one to start work.

Frequently Asked Questions about beads

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a beads task in the correct repo?

Pass the repo parameter to beads_create as either the repo folder name or the issue id prefix, such as repo:"crm-backend". If omitted, it defaults to the session cwd repo; from the umbrella root the repo parameter is required.

How do I find ready unblocked beads issues across repos?

Call beads_ready with an optional limit, repo, or label filter to list open and unblocked issues from the aggregate view spanning all repos. Adding claim: true atomically claims the first matching issue.

Can beads dependencies link issues across different repos?

No, beads dependencies only work within a single repo. For cross-repo ordering, write the required sequence in the issue description instead of using beads_dep.

What is an ephemeral wisp in beads and how do I create one?

A wisp is an ephemeral bead created with ephemeral: true in beads_create, which passes --ephemeral to bd. Wisps stay out of federation sync, are purged once closed, and can be promoted to permanent beads with beads_promote.

Why should I avoid running raw bd commands for reads?

The beads_* tools already read from the cross-repo aggregate and include blocker ids and epic progress. Shelling out to bd list or inspecting .beads/issues.jsonl bypasses the umbrella view and can show incomplete state.