Git

• Beads: Git-Native Issue Tracking for AI-Assisted Development

  If you’re working with AI coding agents like Claude Code, you’ve probably noticed a friction point: context.

  Every time you start a new session, you’re rebuilding mental state. What was I working on? What’s blocked? What’s next?

  I’ve been using Beads, and it’s changed how I manage work across multiple AI sessions.

  What Makes Beads Different?

  Beads takes a fundamentally different approach. Issues live in your repo as a .beads/issues.jsonl file, syncing like any other code. This means:

  • No context switching: Your AI agent can read and update issues without leaving the terminal
  • Always in sync: Issues travel with your branch and merge with your code
  • Works offline: No internet required, just git
  • Branch-aware: Issues can follow your branch workflow naturally

  The CLI-first design is what makes it click with AI coding agents. When I’m working with Claude Code, I can say “check what’s ready to work on” and it runs bd ready to find unblocked issues. No copying and pasting from a browser tab.

  Getting Started

  Getting up and running takes about 30 seconds:

  # Install Beads
  curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
  
  # Initialize in your repo
  bd init
  
  # Create your first issue
  bd create --title="Try out Beads" --type=task
  

  From there, the workflow is straightforward:

  • bd ready shows issues with no blockers
  • bd update <id> --status=in_progress to claim work
  • bd close <id> when you’re done
  • bd sync to commit beads changes

  Why This Matters for AI Workflows

  The real power shows up when you’re juggling multiple tasks across sessions. Your AI agent can:

  1. Pick up exactly where you left off by reading the issue state
  2. Track dependencies between tasks (this issue blocks that one)
  3. Create new issues for discovered work without breaking flow
  4. Close completed work and update status in real-time

  I’ve found this especially useful for longer projects where I’m bouncing between features, bugs, and cleanup tasks. The AI doesn’t lose track because the state is right there in the repo.

  Is It Right for You?

  Beads isn’t trying to replace GitHub Issues for team collaboration or complex project management.

  It’s designed for a specific workflow: developers using AI coding agents who want persistent, agent-friendly task tracking.

  If you’re already working with Claude Code, Aider, or similar tools, give it a try. The setup cost is minimal, and you might find it solves a problem you didn’t realize you had.

  Jan 14, 2026 / Productivity / AI / Developer-tools / Git

  Enjoyed this?