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

Introduction

When using AI coding agents, you end up writing handoff documents. Whether they're called HANDOFF.md, handover.md, or session-handoff.md, they all serve the same purpose: documenting the current state and remaining work so that 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 after the fact. Since AI will be reading them anyway, high readability shouldn't be necessary.

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

That's how I found Beads. In this article, I migrate an existing project's handoff documents 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, allowing you to distinguish between issues that can be started and those blocked by blockers. State is stored in a local database and automatically injected into the agent's context at the start of each session.

Verification Environment

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

Target Audience

• Those who are not satisfied with how they manage handoff documents for AI coding agents
• Those troubled by context dropping due to compaction
• Those considering adopting state management tools for AI agents

References

• Beads Repository
• Beads Documentation
• Integration with Claude Code

Background: The Limits of Handoff Documents

The motivation for this came from context dropping due to compaction (context compaction). Compaction is the process by which Claude Code replaces conversation history with a summary when a conversation grows long and the context approaches its limit.

Every time compaction runs, the agent re-reads past knowledge, consuming a large number of tokens each time. The agent tries to restore state by tracing the conversation, but conversations go back and forth, making them ill-suited as a source of truth for state.

Sometimes I have a sub-agent summarize the content due to its volume, but important parts can be omitted, or when searching by heuristic, the key information doesn't get carried over.

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

Items also get dropped with each generational handoff. A handoff document for one project I was involved in was split across three generations. A correction to a typo in a design document mentioned in the older version was never transferred to the latest version, and the typo remained uncorrected for about two weeks.

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

Verification Results: State Restoration and Updates

The migration itself went smoothly. Upon completing the migration, I was able to register 34 issues and 41 persistent memory entries across 8 existing projects.

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

○ status-manager-u4l ● P1 my-claude-code-rules v3.0.0 の変更をレビューしてコミットする
○ status-manager-2uv ● P2 [epic] 既存 handoff.md 10 件を 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, so there is no need to load the entire database.

However, updates did not happen automatically. I had no choice but to supplement manually, telling the agent things like "update the task progress."

The fact that updates are not automatic becomes more impactful when combined with compaction.

Automatic compaction runs when the 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 inevitably lost in the summarization process. While hooks that run immediately before compaction do exist, they cannot inject instructions to prompt recording.

Verification Results: Where to Record

There was also behavior where previously settled discussions were reopened. This would not happen if decision logs were being managed properly.

Upon investigating, I found the records themselves did exist. However, they were buried inside the completion reason written when closing an issue.

Completion reasons are not injected into the next session. What gets injected is only persistent memory and incomplete issues. The records were being written to a location that would never be read.

Countermeasures

Based on the above, I implemented three countermeasures.

1. Changing the timing of recording

   • Stopped writing everything in a batch at the end of work, and switched to writing as soon as facts are confirmed
   • Records at each milestone: a decision is made, a test passes, or a blocker is identified

2. Not ending a conversation without recording

   • A hook checks the recording status just before the agent finishes responding
   • If an in-progress issue has not been updated for more than 15 minutes, the response is temporarily halted to prompt recording

3. Specifying where to record

   • Decisions received from users must always be written to a region that is automatically injected

I hope to write a follow-up article on whether the user experience improved after these countermeasures.

2026-09-05 Update
The follow-up is here.
What I've Learned About Using Beads After About 1 Month: Priority Judgment and Notes Management

Summary

I migrated state management from handoff documents to Beads and operated it on existing projects. While restoring state at session start could be automated, state updates did not happen automatically, so countermeasures were implemented. I hope to write another article about the user experience after that.