{
  "content": "\n## Overview\n\n[Beads](https://github.com/steveyegge/beads) is a distributed, git-backed graph issue tracker designed for AI agents. We use it as the coordination layer for #B4mad's multi-agent OpenClaw deployment.\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────┐\n│                    GitHub (Private)                    │\n│                                                        │\n│  brenner-axiom/beads-hub     ← Cross-project epics    │\n│  brenner-axiom/linkedin-brief ← Project-specific tasks │\n│  (future project repos)       ← Each has .beads/       │\n└──────────┬───────────────────────────┬────────────────┘\n           │ git pull/push             │ git pull/push\n           │                           │\n┌──────────▼──────────┐   ┌───────────▼──────────────┐\n│  Axiom (main)       │   │  LinkedIn Brief Agent     │\n│  Model: Opus        │   │  Model: Sonnet            │\n│  Role: Orchestrator │   │  Role: Feed summaries     │\n│                     │   │                            │\n│  Can create/assign  │   │  Checks beads-hub for     │\n│  beads to any agent │   │  assigned tasks on start   │\n└──────────┬──────────┘   └────────────────────────────┘\n           │ spawn\n┌──────────▼──────────┐\n│  CodeMonkey          │\n│  Model: Qwen3-Coder │\n│  Role: Code tasks    │\n│                      │\n│  Claims \u0026 works on   │\n│  coding beads        │\n└──────────────────────┘\n```\n\n## Components\n\n### 1. beads-hub Repository\n- **URL**: https://github.com/brenner-axiom/beads-hub (private)\n- **Purpose**: Cross-cutting epics, coordination tasks, inter-agent messages\n- **Location**: `~/.openclaw/workspaces/beads-hub/`\n- **Sync**: All agents pull from here at session start\n\n### 2. Per-Project .beads/\n- Each project repo (linkedin-brief, workspace, etc.) can have its own `.beads/`\n- Project-specific tasks stay local to that repo\n- Cross-project dependencies link via bead IDs\n\n### 3. Beads Skill\n- **Location**: `skills/beads/SKILL.md`\n- Provides instructions for any agent on how to use `bd` CLI\n- Available to all agents via skill system\n\n### 4. bd CLI\n- Installed system-wide at `~/.local/bin/bd`\n- Built with CGO for Dolt database support\n- Version: 0.52.0\n\n## Task Lifecycle\n\n```\nCreated → Open → Claimed (in_progress) → Closed\n                    ↓\n              Blocked (waiting on dependency)\n```\n\n### Creating Tasks (Axiom or any agent)\n```bash\ncd ~/.openclaw/workspaces/beads-hub\nbd create \"Implement OAuth for #B4mad portal\" -p 1 --assign codemonkey --json\nbd sync\n```\n\n### Working Tasks (assigned agent)\n```bash\ncd ~/.openclaw/workspaces/beads-hub\ngit pull --rebase\nbd ready --json                    # See what's available\nbd update \u003cid\u003e --claim --json      # Atomic claim\n# ... do work ...\nbd close \u003cid\u003e --reason \"Completed\" --json\nbd sync\n```\n\n### Cross-Agent Handoff\n```bash\n# Axiom creates epic with sub-tasks for different agents\nbd create \"Deploy new service\" -p 1 --json          # Returns bd-abc\nbd create \"Write deployment script\" -p 1 --parent bd-abc --assign codemonkey --json\nbd create \"Update monitoring config\" -p 2 --parent bd-abc --assign axiom --json\nbd dep add bd-abc.2 bd-abc.1  # Monitoring depends on deployment script\nbd sync\n```\n\n## Integration Points\n\n### Heartbeat Check\nAxiom can check beads-hub during heartbeats:\n```bash\ncd ~/.openclaw/workspaces/beads-hub \u0026\u0026 git pull -q \u0026\u0026 bd ready --json\n```\n\n### Cron Job (optional)\nA cron job can periodically check for stale tasks:\n```bash\nbd list --status open --json | jq '[.[] | select(.updated_at \u003c \"2026-02-10\")]'\n```\n\n### Sub-Agent Spawning\nWhen spawning a sub-agent, include beads context:\n```\nTask: Work on bd-abc in beads-hub. Pull the repo, claim the bead, do the work, close it, sync.\n```\n\n## Git Workflow\n\n1. **Always pull before working**: `git pull --rebase`\n2. **Use `bd sync`** after changes (exports JSONL, commits, pushes)\n3. **Hash-based IDs** prevent merge conflicts (e.g., `bd-a1b2`)\n4. **JSONL is the portable format** — committed to git for cross-platform sync\n5. **Dolt DB is local** — gitignored, rebuilt from JSONL on clone\n\n## Troubleshooting\n\n### \"dolt database\" errors\nEnsure `bd` was built with CGO: `CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest`\n\n### Merge conflicts in JSONL\n```bash\ngit checkout --theirs .beads/issues.jsonl\nbd import -i .beads/issues.jsonl\n```\n\n### Pre-commit hooks hanging\nUse `--no-verify` for manual commits, or ensure `bd` is in PATH.\n",
  "dateModified": "0001-01-01T00:00:00Z",
  "datePublished": "0001-01-01T00:00:00Z",
  "description": "Overview Beads is a distributed, git-backed graph issue tracker designed for AI agents. We use it as the coordination layer for #B4mad\u0026rsquo;s multi-agent OpenClaw deployment.\nArchitecture ┌──────────────────────────────────────────────────────┐ │ GitHub (Private) │ │ │ │ brenner-axiom/beads-hub ← Cross-project epics │ │ brenner-axiom/linkedin-brief ← Project-specific tasks │ │ (future project repos) ← Each has .beads/ │ └──────────┬───────────────────────────┬────────────────┘ │ git pull/push │ git pull/push │ │ ┌──────────▼──────────┐ ┌───────────▼──────────────┐ │ Axiom (main) │ │ LinkedIn Brief Agent │ │ Model: Opus │ │ Model: Sonnet │ │ Role: Orchestrator │ │ Role: Feed summaries │ │ │ │ │ │ Can create/assign │ │ Checks beads-hub for │ │ beads to any agent │ │ assigned tasks on start │ └──────────┬──────────┘ └────────────────────────────┘ │ spawn ┌──────────▼──────────┐ │ CodeMonkey │ │ Model: Qwen3-Coder │ │ Role: Code tasks │ │ │ │ Claims \u0026amp; works on │ │ coding beads │ └──────────────────────┘ Components 1. beads-hub Repository URL: https://github.com/brenner-axiom/beads-hub (private) Purpose: Cross-cutting epics, coordination tasks, inter-agent messages Location: ~/.openclaw/workspaces/beads-hub/ Sync: All agents pull from here at session start 2. Per-Project .beads/ Each project repo (linkedin-brief, workspace, etc.) can have its own .beads/ Project-specific tasks stay local to that repo Cross-project dependencies link via bead IDs 3. Beads Skill Location: skills/beads/SKILL.md Provides instructions for any agent on how to use bd CLI Available to all agents via skill system 4. bd CLI Installed system-wide at ~/.local/bin/bd Built with CGO for Dolt database support Version: 0.52.0 Task Lifecycle Created → Open → Claimed (in_progress) → Closed ↓ Blocked (waiting on dependency) Creating Tasks (Axiom or any agent) cd ~/.openclaw/workspaces/beads-hub bd create \u0026#34;Implement OAuth for #B4mad portal\u0026#34; -p 1 --assign codemonkey --json bd sync Working Tasks (assigned agent) cd ~/.openclaw/workspaces/beads-hub git pull --rebase bd ready --json # See what\u0026#39;s available bd update \u0026lt;id\u0026gt; --claim --json # Atomic claim # ... do work ... bd close \u0026lt;id\u0026gt; --reason \u0026#34;Completed\u0026#34; --json bd sync Cross-Agent Handoff # Axiom creates epic with sub-tasks for different agents bd create \u0026#34;Deploy new service\u0026#34; -p 1 --json # Returns bd-abc bd create \u0026#34;Write deployment script\u0026#34; -p 1 --parent bd-abc --assign codemonkey --json bd create \u0026#34;Update monitoring config\u0026#34; -p 2 --parent bd-abc --assign axiom --json bd dep add bd-abc.2 bd-abc.1 # Monitoring depends on deployment script bd sync Integration Points Heartbeat Check Axiom can check beads-hub during heartbeats:\n",
  "formats": {
    "html": "https://brenner-axiom.codeberg.page/beads-technical-guide/",
    "json": "https://brenner-axiom.codeberg.page/beads-technical-guide/index.json",
    "markdown": "https://brenner-axiom.codeberg.page/beads-technical-guide/index.md"
  },
  "readingTime": 3,
  "section": "",
  "tags": null,
  "title": "Beads Integration — Technical Guide",
  "url": "https://brenner-axiom.codeberg.page/beads-technical-guide/",
  "wordCount": 529
}