Beads Task Tracker

Use beads to quickly capture tasks, ideas, and bugs without losing context across sessions.

When to Use

• User says "add a todo" or "remember to fix"
• User wants to see open tasks or what's ready to work on
• User mentions a bug, idea, or feature during conversation
• Any task tracking request that should persist across sessions

Project Labels

When creating tasks, always include a project label using -l <project>.

Project labels map to directories via .beads/project-dirs.json:

• cjp-website → code/cjp-website
• quantum-dungeon → games/quantum-dungeon
• arxivite → code/arxivite
• chimera-chat → code/chimera-chat
• med-docs-v2 → code/med-docs-v2
• workspace → root (for general tasks)

Task naming convention:

• Title should be descriptive and standalone
• Description should include context about what needs to happen
• Labels should include the project and optionally auto (for executor-eligible tasks)

Example:

cd ~/.openclaw/workspace && bd create "Integrate language translator" -p 1 -t feature -l cjp-website,auto -d "Allow users to view pages in regional Indian languages. Use Google Translate or similar widget."

Executor-eligible tasks: Add the auto label if the task can be safely executed by the cron executor without human review. Tasks requiring design decisions or major architecture changes should NOT have the auto label.

Commands

Always use bd with the workspace .beads/ database. The workspace root is initialized with --stealth so .beads/ is gitignored.

Add a task

cd ~/.openclaw/workspace && bd create "Title" -p 1 -t task -l project-label

Priority levels: 0=critical, 1=high, 2=normal, 3=low Types: task, bug, idea, feature, refactor, docs

Add an idea or bug

cd ~/.openclaw/workspace && bd create "Idea: something" -p 2 -t idea -l project-label
cd ~/.openclaw/workspace && bd create "Bug: something broken" -p 0 -t bug -l project-label

List ready (unblocked) work

cd ~/.openclaw/workspace && bd ready

Show all issues

cd ~/.openclaw/workspace && bd list

Show specific issue

cd ~/.openclaw/workspace && bd show <id>

Claim a task (mark in-progress)

cd ~/.openclaw/workspace && bd update <id> --claim

Close a task

cd ~/.openclaw/workspace && bd close <id> --reason "Done"

Add dependency

cd ~/.openclaw/workspace && bd dep add <child> <parent>

Store a persistent memory/insight

cd ~/.openclaw/workspace && bd remember "insight text"

Get workflow context

cd ~/.openclaw/workspace && bd prime

Workflow

1. When user mentions a task/idea/bug → capture it immediately with bd create
2. When user asks what's pending → run bd ready or bd list
3. When user completes something → run bd close on the relevant item
4. Use bd prime to inject context when starting a new work session

Integration with Memory Bank

• Beads: Granular, actionable tasks for the current project/workspace. What's the next thing to do?
• Memory Bank: Long-term context, design decisions, session history, identity. Why did we do it this way?

Both systems complement each other. Beads tracks what needs to happen; memory bank tracks what happened and why.