
I Tested How Far Task Progress Management Can Be Automated with Beads
This page has been translated by machine translation. View original
Introduction
When you use an AI coding agent, you end up writing handoff documents. Whether it's called HANDOFF.md, handover.md, or session-handoff.md, the purpose is the same: to write down the current state and the remaining work so that the next session can resume from zero context.
I used to do this too, but I had doubts about this approach. Having a human read a long handoff document later is a hassle. Since it is going to be read by an AI anyway, it shouldn't need to be highly readable.
Task progress management is, after all, state management. State management is a problem humans were already struggling with before AI, and that is exactly why various methods, starting with Kanban, have been invented. I wanted to avoid reinventing the wheel. Thinking that someone must have already worked on this, I decided to research it before building my own.
What I found was Beads. In this article, I move the handoff documents of existing projects to Beads and check how far state management can be automated. To state the conclusion first: restoring the state at the start of a session could be automated, but updating the state was not done automatically, and a human still needed to fill that gap.
What is Beads
Beads is an issue tracking tool designed for AI coding agents. Its command is bd. It treats dependencies between issues as a first-class concept, and can distinguish between issues that are ready to start and issues that are stuck on blockers. The state is stored in a local database and is automatically injected into the agent's context at the start of a session.
Test environment
- macOS 26.5.2
- bd 1.1.2 (Homebrew)
- Claude Code 2.1.220
Intended audience
- Those who are not satisfied with how they manage handoff documents for AI coding agents
- Those who are troubled by context being lost to compaction
- Those considering adopting a state management tool for AI agents
References
Background: The limits of handoff documents
My motivation for adopting it was that context was lost to compaction (context compaction). Compaction is the process in which Claude Code replaces the conversation history with a summary when the conversation grows long and the context approaches its limit.
Every time compaction runs, the agent rereads past knowledge. Each time, it consumes a large number of tokens. The agent tries to restore the state by tracing the conversation, but conversations go back and forth, so it is unreasonable to treat them as the source of truth for state.
Because the volume is large, I sometimes had a subagent summarize it, but important parts would be dropped, or the search based on a guess would fail to bring back the crucial points.
Handoff documents themselves also have flaws. When dependencies and blockers are expressed in prose, the reader has to reconstruct them in their head every time. It is not clear at a glance what is finished and what can be started now.
Items are also dropped with each generation change. The handoff document of a project I was involved in was split into three generations. A correction of a typo in a design document that was written in the old version had not been carried over to the latest version, and the error remained unfixed for about two weeks.
If this were moved to Beads, this item should keep appearing as an issue until it is completed.
Results: Restoring and updating state
The migration itself went well. By the time the migration was finished, I had registered 34 issues and 41 persistent memories across the 8 existing projects.
At the start of a session and after compaction, a list like the following is automatically placed 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
The state comes back without relying on the conversation history. This was as expected. Only the specified issues are retrieved, and there is no need to load the entire database.
However, updates were not done automatically. I had no choice but to say things like "update the task progress" and fill in the gaps myself each time.
The fact that updates are not automatic has a bigger impact when combined with compaction.
Automatic compaction runs when the context approaches its limit, so it can occur in the middle of work. It is not realistic to watch for the timing. Because compaction replaces the conversation history with a summary, some of it is lost in the summarization process. A hook that runs right before compaction exists, but it cannot inject instructions prompting the agent to record.
Results: Where to record
There was also behavior where a discussion that had already been settled was reopened. This is behavior that should not happen if decision logs were being managed properly.
When I investigated the cause, the record itself had been kept. However, it was in the completion reason written when an issue was closed.
The completion reason is not injected into the next session. Only persistent memories and open issues are injected. I had been putting it in a place where what I wrote was never read.
| Where recorded | Injected into the next session? |
|---|---|
| Persistent memory | Yes |
| Open issues | Yes |
| Completion reason | No |
| Additions to completed issues | No |
Countermeasures
Based on the above, I introduced three countermeasures.
-
Change the timing of recording
- I stopped writing everything at the end of the work and now write as soon as a fact is confirmed
- I record at each milestone, such as when a policy is decided, when verification passes, or when a blocker is identified
-
Do not end a conversation without recording
- Right before the agent is about to finish its response, a hook checks the status of the records
- If an issue in progress has not been updated for 15 minutes or more, the response is stopped for the moment and the agent is prompted to record
-
Specify where to record
- I stipulated that decisions received from the user must always be written in an area that is automatically injected
As for whether the usability improved after the countermeasures, I would like to write a follow-up in another article.
2026-09-05 Update
The follow-up is here.
What I Learned About Using Beads After About One Month: Priority Decisions and Notes Operation
Summary
I moved state management from handoff documents to Beads and used it in existing projects. While restoring the state at the start of a session could be automated, updating the state was not done automatically, so I implemented countermeasures. I hope to write another article about how it feels to use afterward.
