I verified how far task progress management can be automated with Beads

Introduction

When using AI coding agents, you end up writing handoff documents. Whether named HANDOFF.md, handover.md, or session-handoff.md, the purpose is the same: documenting the current state and remaining work so the next session can resume from zero context.

I was doing this too, but I had doubts about the approach. Long handoff documents are tedious for humans to read afterward. Since AI will be reading them anyway, high readability shouldn't be necessary.

Task progress management is, at its core, state management. State management is a problem humans have wrestled with long before AI, which is why various approaches like Kanban have been invented. I wanted to avoid reinventing the wheel. Assuming someone had already thought this through, I decided to research existing solutions before building my own.

That's when I found Beads. In this article, I migrate handoff documents from an existing project to Beads and verify how far state management can be automated. To state the conclusion upfront: restoring state at session start could be automated, but state updates did not happen automatically and still required human intervention.

What is Beads

Beads is an issue management tool designed for AI coding agents. The command is bd. It treats dependencies between issues as a first-class concept, distinguishing between issues ready to work on and those blocked. State is stored in a local database and automatically injected into the agent's context at session start.

Verification Environment

• macOS 26.5.2
• bd 1.1.2 (Homebrew)
• Claude Code 2.1.220

Target Audience

• Those who aren't satisfied with how they manage AI coding agent handoff documents
• Those troubled by context dropping during compaction
• Those considering adopting a state management tool for AI agents

References

• Beads repository
• Beads documentation
• Integration with Claude Code

Background: The Limits of Handoff Documents

The motivation for this was context dropping during compaction. Compaction is the process where Claude Code replaces conversation history with a summary when a conversation grows long and context approaches its limit.

Every time compaction runs, the agent re-reads past knowledge, consuming large amounts of tokens each time. The agent attempts to restore state by tracing the conversation, but conversations go back and forth, making them unsuitable as the authoritative source of state.

Sometimes I have subagents summarize due to the volume, but important parts get omitted, or when searching by hunch, the crucial pieces don't get retrieved.

Handoff documents themselves have flaws too. When dependencies and blockers are expressed in prose, the reader must mentally reconstruct them every time. It's not immediately clear what's finished and what can be started now.

Items also fall through the cracks with each new generation. A handoff document for one project I was involved with was split across three generations. A typo fix for a design document noted in an older version was never carried forward to the latest version, leaving the typo uncorrected for roughly two weeks.

Once migrated to Beads, that item should keep appearing as an issue until it's marked complete.

Findings: State Restoration and Updates

The migration itself went well. Upon completing it, I had registered 34 issues and 41 persistent memory entries across 8 existing projects.

At session start and after compaction, a list like the following is automatically injected into the agent's context:

○ status-manager-u4l ● P1 Review and commit changes for my-claude-code-rules v3.0.0
○ status-manager-2uv ● P2 [epic] Migrate 10 existing handoff.md files to Beads

--------------------------------------------------------------------------------
Ready: 2 issues with no active blockers

State is restored without relying on conversation history. This worked as expected. Only specified issues are retrieved — there's no need to load the entire database.

However, updates did not happen automatically. As a workaround, I would tell the agent things like "update the task progress," filling in the gaps myself each time.

The lack of automatic updates has a larger impact when combined with compaction.

Automatic compaction triggers when context approaches its limit, so it can occur mid-task. Monitoring the timing is not practical. Since compaction replaces conversation history with a summary, some content is lost in the summarization process. While hooks that run immediately before compaction do exist, they cannot inject instructions to prompt recording.

Findings: Where to Record

There were also instances where settled discussions were revisited. This shouldn't happen if decision logs are properly maintained.

Investigating the cause, I found that the records themselves existed. However, they were buried inside completion notes written when closing an issue.

Completion notes are not injected into the next session. Only persistent memory and incomplete issues are injected. Information had been written to a location that would never be read.

Countermeasures

Based on the above, I implemented three countermeasures.

1. Changing when records are written

   • Stopped batching writes until the end of work; now write as soon as facts are confirmed
   • Record at each milestone: a decision made, a test passed, a blocker identified

2. Never end a conversation without recording

   • A hook checks the recording status just before the agent finishes a response
   • If an in-progress issue hasn't been updated for 15 minutes or more, the response is paused to prompt recording

3. Specifying where to record

   • Decisions received from the user must always be written to areas that are automatically injected

Whether these countermeasures improved the experience is something I hope to cover in a follow-up article.

Summary

I migrated state management from handoff documents to Beads and ran it on existing projects. While state restoration at session start was successfully automated, state updates did not happen automatically, prompting the countermeasures described above. I hope to write another article on the experience going forward.