Beads Integration

Beads integration is optional. initech works without it. But when enabled, the TUI knows about work assignments and can detect when agents finish tasks.

What Is Beads

Beads is a git-backed issue tracker with a CLI called bd. Each unit of work is a "bead" with an ID (like ini-42), a status, and an assignee. Beads stores its data in a .beads/ directory inside your project, tracked in git alongside your code.

initech does not include or replace beads. It integrates with bd if it's installed and enabled. For the full bd command reference, see the beads documentation.

Enabling and Disabling

Beads integration is controlled by the beads section in initech.yaml:

# Enable beads with a project prefix
beads:
    prefix: ini

# Explicitly disable beads
beads:
    enabled: false

When beads.enabled is false, initech bead becomes a no-op. The TUI still works normally; you just don't get bead badges in the overlay.

When beads is enabled, initech sets the BEADS_DIR environment variable in each agent pane so bd commands find the database automatically.

What You Get With Beads

Agent bead display

Agents report which bead they're working on:

$ initech bead ini-42       # Set current bead
$ initech bead --clear      # Clear when done

The bead ID appears in the TUI title bar badge, the agent overlay panel, and the initech status output. At a glance, you see which agents are working on what.

Bead lifecycle

Beads flow through a status sequence that maps to agent workflow:

open -> in_progress -> ready_for_qa -> in_qa -> qa_passed -> closed

• An engineer claims a bead and moves it to in_progress
• After implementation and tests pass, the engineer marks ready_for_qa
• QA claims it, validates, and marks qa_passed
• The operator reviews and closes the bead

initech doesn't enforce this lifecycle. It reads bead state and displays it. The enforcement is in the agent CLAUDE.md files and the bd CLI.

Event detection

The TUI monitors agent JSONL session logs and detects work-state changes:

• Completion: An agent's output indicates they finished a bead (DONE comment pattern). The TUI can surface this as a notification.
• Stalling: An agent has been active on a bead for a long time with no progress. The TUI flags it.
• Error loops: An agent is stuck repeating the same error. The TUI detects the pattern.

Detection is aggressive, action is conservative. The TUI surfaces events to the operator. It does not auto-dispatch or auto-close beads.

Without Beads

initech works fine without beads. Agents still communicate via initech send / peek, the TUI still shows activity states, and all other features work normally. You lose bead badges and event detection tied to bead lifecycle. If you use a different issue tracker (Linear, Jira, GitHub Issues), you can still coordinate work through agent messages and CLAUDE.md instructions.

Last updated: April 2026