Help us improve
Share bugs, ideas, or general feedback.
Share bugs, ideas, or general feedback.
Share bugs, ideas, or general feedback.
By gastownhall
Manage an AI-supervised issue tracker directly from the CLI — create, close, and update tasks with dependency tracking, labels, epics, and decision records, while an autonomous agent claims and completes ready work across sessions.
npx claudepluginhub jmagar/.agents --plugin beadsLog and label agent interactions (append-only JSONL)
Show blocked issues
Close a beads issue that's been completed.
View or manage comments on an issue
Reduce database size by summarizing closed issues no longer actively referenced.
Uses power tools
Uses Bash, Write, or Edit tools
Share bugs, ideas, or general feedback.
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge.
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge.
Sign in to claimBased on adoption, maintenance, documentation, and repository signals. Not a security audit or endorsement.
Configure Claude Code to track work using Beans.
Cotask — task management with TASKS.md kanban dashboard
Install and manage TaskYou — a personal task management system with Kanban board, background AI execution, and git worktree isolation.
Convert design documents, PRDs, and task lists into beads issues with lossless conversion, proper epic hierarchy, validated dependencies, and three independent subagent review passes.
Plan-only mode and GitHub-issue-to-Beads workflow. Provides planning without auto-execution and structured work decomposition into Beads epics, tasks, and sub-tasks with verifiable acceptance criteria.
AI-Driven Engineering workflow commands for managing issues, tasks, implementation, and PRs.
Join and participate in the Wasteland federation — browse work, claim tasks, submit completions, earn reputation. Uses dolt + DoltHub only (no Gas Town required).
Distributed graph issue tracker for AI agents, powered by Dolt.
Platforms: macOS, Linux, Windows, FreeBSD
Docs: https://gastownhall.github.io/beads/
Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.
# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
# Initialize in YOUR project
cd your-project
bd init
# Optional: install richer instructions for your agent
bd setup codex # Codex CLI - creates/updates AGENTS.md
bd setup claude # Claude Code - installs hooks/settings
bd setup factory # Factory.ai Droid - creates/updates AGENTS.md
Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.
bd init creates or updates AGENTS.md by default so agents can discover the beads workflow. It skips agent files only when you pass --skip-agents or --stealth, or when you configure a custom agent file. Use bd setup --list to see supported integrations, including bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor, and more. See Agent and IDE setup.
Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun bd init/bd setup, or custom instruction files. In those cases, run bd onboard and paste the printed snippet into the file your agent reads.
If your agent is not covered by bd setup, add this minimal AGENTS.md section:
This project uses bd (beads) for issue tracking.
- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.
bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.--thread), ephemeral lifecycle, and mail delegation.relates_to, duplicates, supersedes, and replies_to for knowledge graphs.| Command | Action |
|---|---|
bd ready | List tasks with no open blockers. |
bd create "Title" -p 0 | Create a P0 task. |
bd update <id> --claim | Atomically claim a task (sets assignee + in_progress). |
bd dep add <child> <parent> | Link tasks (blocks, related, parent-child). |
bd show <id> | View task details and audit trail. |
bd prime | Print agent workflow context and persistent memories. |
bd remember "insight" | Store project memory that bd prime injects later. |
Beads supports hierarchical IDs for epics:
bd-a3f8 (Epic)bd-a3f8.1 (Task)bd-a3f8.1.1 (Sub-task)Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects. See Git-Free Usage below.
Contributor vs Maintainer: When working on open-source projects:
bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.brew install beads # macOS / Linux (recommended)
npm install -g @beads/bd # Node.js users