Skip to main content
Understanding beads’ collision-resistant ID system.

​
The Problem

Traditional sequential IDs (#1, #2, #3) break when:
  • Multiple agents create issues simultaneously
  • Different branches have independent numbering
  • Forks diverge and later merge

​
The Solution

Beads uses hash-based IDs:
Properties:
  • Globally unique (content-based hash)
  • No coordination needed between creators
  • Merge-friendly across branches
  • Predictable length (configurable)

​
How Hashes Work

IDs are generated from:
  • Issue title
  • Creation timestamp
  • Random salt

​
Hierarchical IDs

For epics and subtasks:
Benefits:
  • Clear parent-child relationship
  • No namespace collision (parent hash is unique)
  • Up to 3 levels of nesting

​
ID Configuration

Configure ID prefix and length:

​
Collision Handling

While rare, collisions are handled automatically:
  1. On import, if hash collision detected
  2. Beads appends disambiguator
  3. Both issues preserved

​
Working with IDs

​
bd comment requires the full id

Every command above resolves an abbreviation the same way — but bd comment <id> "text" (and its bd comments add twin) is the one deliberate exception: it accepts only a full, exact id, never an abbreviation. This is a policy trade for an agent fleet, not an oversight: an abbreviation that happens to be a leading-prefix match for the wrong issue would silently write the comment there instead of erroring, and a comment write has no confirmation step to catch it before the message lands on the wrong issue. Reads and every other mutation (show, close, update, …) keep accepting abbreviations as documented above.
A reserved word (list, add, rm, delete) as the id positional is refused the same way, for a related reason: bd comment list "text" almost always means the caller confused the singular shorthand with the plural bd comments list/bd comments add <id> "text", not that an issue is literally named list.

​
Migration from Sequential IDs

If migrating from a system with sequential IDs:

​
Best Practices

  1. Use short references - bd-a1b2 is usually unique enough, except on bd comment writes, which require the full id (see Working with IDs above)
  2. Use --json for scripts - Parse full ID programmatically
  3. Reference by hash in commits - Fixed bd-a1b2 in commit messages
  4. Let hierarchies form naturally - Create epics, add children as needed