I work on a lot of projects. Some are serious products; plenty are experiments and side projects that may or may not turn into something.

I use coding agents such as Codex and Claude across nearly all of them. Starting the work is rarely the problem. I can give an agent a design, write an execution plan, and drive a feature forward. The trouble starts as the project grows.

A defect appears in the middle of the plan. A design choice needs my input. I provide the missing context and the agent handles the immediate problem, but somewhere along the way the original work begins to drift. Active and completed execution plans stop reflecting what is really happening. The next session has to reconstruct the state from Markdown files, TODO lists, and old conversations.

I have tried to make that approach work across a lot of projects. It has never given me the continuity I want.

Beads clicked with me because it treats the work as a graph instead of another document. Created by Steve Yegge, Beads is a dependency-aware issue tracker built specifically for AI coding agents. The execution plan can still hold the design, but the graph drives what is ready, what is blocked, and what was discovered along the way.

I have now tried that approach on both new and existing projects. I am still learning the workflow, and I have not found the exact secret sauce yet. But I can plan work, step away, return in another session, or switch between Codex and Claude without watching the original goal slowly disappear.

What the Agent Actually Works From

Beads runs through the bd command-line tool. Each unit of work is a bead: a structured issue with a title, description, type, priority, status, dependencies, and history.

That sounds like Jira or GitHub Issues until you look at the operating model. Beads is local, CLI-first, scriptable, and built around the questions a coding agent needs answered:

  • What work has no open blockers?
  • Can I claim it without racing another agent?
  • What context belongs to this task?
  • What new work did I discover while implementing it?
  • What should the next agent see when this session ends?

The basic loop is small:

bd ready --json
bd show <id> --json
bd update <id> --claim --json

# Do the work. Preserve anything newly discovered.
bd create "Handle expired sessions" \
  --description="Found while implementing login refresh" \
  --deps discovered-from:<id> \
  --json

bd close <id> --reason="Implemented and verified" --json

An agent starts with bd ready, claims one item, records discoveries instead of hiding them in chat, and closes the bead when the acceptance criteria are met. The next session reads the same state.

What interests me here is continuity. The work has somewhere to live after an agent session ends without turning every experiment into a traditional project-management exercise.

The Missing Graph Between the Plan and the Work

I am a big proponent of OpenAI’s harness-engineering approach. Repository knowledge, execution plans, tests, and mechanical checks give an agent the environment it needs to do reliable work. I use those ideas across my own projects.

Execution plans are good at preserving design and intent. In my experience, though, the plan is not what drives or sequences the work, and it cannot connect a defect discovered today to the work that created it three sessions ago. That graph of the work is the missing link.

Most plans still reduce the implementation to an ordered list:

1. Add the database schema
2. Build the API
3. Create the UI
4. Write tests
5. Update the docs

The list implies one sequence, but real work rarely has one. The API may depend on the schema. The UI may depend on the API. Documentation can begin immediately. Some tests may be ready before the UI, while an end-to-end test remains blocked by all three.

A dependency graph represents those relationships directly. When the schema bead closes, Beads recomputes the ready frontier. The API becomes available while unrelated documentation work remains available too. An agent does not have to interpret a stale list or guess what the author meant by “next.”

That distinction becomes important once multiple agents are working. A list is something they all read and interpret. A graph gives them a shared view of what each one may safely claim.

The graph also changes how planning errors behave. If the dependency direction is wrong, bd ready exposes the mistake immediately by showing the wrong task or no task at all. In a prose plan, the same error can sit unnoticed until an agent starts implementing against a missing prerequisite.

Starting the Next Session Without Reconstructing Everything

Agent memory is usually treated as a prompting problem: write a better handoff, preserve more chat, or keep a larger context window. Those approaches help, but they keep the project state trapped in prose.

Beads makes recovery mechanical. An agent can run bd prime for workflow context, bd ready to see available work, and bd show <id> for the task’s details and history. It can reconstruct the operational state without replaying an entire conversation.

That has several useful consequences.

What survives compaction?

When a context window is summarized, the work graph remains intact. The agent can reload the task, its dependencies, and its recorded discoveries from the repository.

What belongs in a handoff?

A commit tells the next agent what changed. A bead can also explain why, what acceptance criteria were used, and what remains blocked.

Where does discovered work go?

Implementation always reveals more work: an edge case, missing validation, a migration, or cleanup that should not derail the current task. A discovered-from relationship preserves that finding and its origin without expanding the current scope.

How does the agent choose what comes next?

bd ready returns work with no open blocking dependencies. That is more reliable than asking an agent to scan a long backlog and make a judgment from incomplete context every time it starts.

The model has the same capabilities, but it returns to a much better source of truth.

One Work Graph Across Codex and Claude

Single-agent continuity is useful, but the graph becomes more valuable as concurrency increases.

Beads uses hash-based IDs, which avoid the central sequence-number collisions that appear when separate branches or agents create issues at the same time. Atomic claiming gives one agent ownership of a bead instead of relying on a message like “I’m taking task three.” Dependencies keep another agent from starting downstream work early.

The result is a simple coordination protocol:

  1. Query ready work.
  2. Claim one bead atomically.
  3. Work only inside its scope.
  4. Record newly discovered work as separate beads.
  5. Close the bead with verification notes.
  6. Query the graph again.

In my projects, this gives Codex and Claude the same work queue even though they do not share conversation context.

There is an important storage detail here. Beads uses Dolt, a version-controlled SQL database. That gives the issue graph history, branches, queries, and merge-aware synchronization. The default embedded mode is intentionally simple, but it supports one writer at a time. Teams that need truly concurrent writers should use Beads’ server mode or give agents isolated workspaces with an explicit synchronization strategy.

The database gives each session somewhere durable to leave its task state. I still have to coordinate the agents and make design decisions, but a new session no longer has to reconstruct the work from scratch.

Where Beads Fits Beside GitHub Issues

I would not automatically replace every existing tracker with Beads.

GitHub Issues is good at public discussion, contributor visibility, screenshots, notifications, and connecting work to pull requests. Jira and Linear are good at team planning, reporting, and stakeholder workflows. Beads is optimized for an agent operating inside a repository.

The useful distinction is audience:

System Primary audience Best at
Markdown plan One person or one session Fast, disposable thinking
GitHub Issues Maintainers and contributors Visible collaboration around a repository
Jira or Linear Product and engineering teams Planning, reporting, and organizational workflow
Beads Coding agents and their supervisors Durable task state, dependencies, and executable next-work queries

I still use public issues to describe user-facing problems and connect work to contributors. Beads tracks the implementation graph the agent needs to finish that work. Trying to make a chat transcript or flat checklist serve both audiences is where I have run into trouble.

Starting Fresh Is Easier Than Retrofitting a Project

Beads can be overwhelming when you first encounter it. Installing the CLI is only the beginning. There is storage to configure, collaboration behavior to understand, and a dependency model to get right. Someone also has to create beads with enough detail to be useful, close what gets finished, and avoid turning bad issue descriptions into durable bad context.

A greenfield project is the easier place to learn because the graph can grow with the work. Adding Beads to an existing project raises a harder question: how much of the current plan, backlog, and technical debt should become beads? Seeding that initial graph is a real planning task of its own.

I have tried both. My current approach is to use my Beads skill and agent harness to walk me through the tradeoffs before anything is created. I explicitly tell the agent not to create beads until it explains what it recommends, why each bead belongs in the graph, and how the dependencies fit together. I stay involved in that initial planning instead of handing the repository to the tool and hoping it organizes everything correctly.

The dependency command is also easy to read backward. In Beads, dependency direction describes a requirement: the dependent work requires its prerequisite. Thinking in chronological language such as “do A before B” can produce the opposite edge from what you intended. This is exactly the kind of mistake an agent instruction should prevent.

The project is evolving quickly, which creates another cost. Command names, setup behavior, storage guidance, and integrations can drift. Instructions copied from an old article may be plausible and still be wrong for the installed binary.

For a ten-minute change that will start and finish in one session, Beads may be more ceremony than value. I reach for it when at least one of these is true:

  • The work will span multiple sessions.
  • More than one agent may contribute.
  • Tasks have meaningful dependencies.
  • Implementation is likely to reveal additional work.
  • Losing the reasoning behind the plan would be expensive.

The longer the horizon and the more agents involved, the easier that tradeoff has been for me.

Why I Make the Agent Explain the Graph First

Beads solves the durable-work problem, but agents still need to operate it correctly.

At the version I reviewed, the CLI exposed 109 commands plus storage, synchronization, workflow, routing, and multi-agent concepts. The upstream documentation is extensive, and some of its agent guidance had fallen behind the binary. An agent should not load that entire corpus into every context window, but a two-page summary also leaves out the failure modes that matter.

I built beads-skill to sit between those extremes and to keep me involved in the decisions that matter.

Its entry-point SKILL.md contains the rules and commands needed in a normal session: create the bead before the code, use Beads as the task tracker, get dependency direction right, claim work, record discoveries, and close what is finished. Twelve deeper references stay out of context until the agent needs installation details, recovery steps, multi-agent coordination, workflows, or the full CLI.

I used both Codex and Claude to review the Beads code and documentation, then tested the claims in real projects that had not previously used Beads. The skill is version-pinned and tested against the real bd binary. That last part matters. During the review I found places where published guidance and shipped behavior disagreed, including stale commands and Codex setup behavior that could overwrite an installed skill. The skill records those conflicts and follows the binary.

This creates two separate layers:

  • Beads stores the project’s durable work state.
  • The skill teaches an agent how to maintain that state correctly.

I am still working out the right balance between those layers. The more I use them together, the better I get at deciding what belongs in the graph, what belongs in an execution plan, and where I need to stay directly involved.

What I Have Seen So Far

Most discussion about coding agents focuses on model capability: which model writes better code, uses tools more accurately, or fits more tokens into a context window. Those things matter, but capability alone has not solved the continuity problem for me.

A capable agent with no durable work state still begins each session by reconstructing the project. Multiple capable agents without a shared task graph can create more coordination work than they remove.

Beads addresses that missing layer by giving agents a structured answer to three basic questions: What exists? What is blocked? What can I safely do next?

So far, that has helped me plan work and drive it to completion with less drift. When a defect or design choice comes up, I can provide clarity, let the agent incorporate it into the graph, and allow the work to continue. That continuity has held across sessions and across coding harnesses in a way I was never able to get from Markdown plans, TODO lists, and agent conversations alone.

I am not claiming I have the workflow perfected. I am getting better at it the more I use it, and the concept behind Beads continues to hold up when I put it to work on real projects.

Try Beads, Then Tell Me Where It Breaks

If you want to try the workflow without teaching your agent the entire CLI first, the beads-skill repository contains the version-pinned skill, installation instructions, and detailed references for Claude Code, Codex, and other SKILL.md-compatible agents.

If you’re already using Beads with coding agents, I want to hear where it earns its keep and where it becomes overhead: context recovery, dependency modeling, agent handoffs, or coordinating multiple agents. Find me on X @mikezupper or email [email protected]. If you find something wrong or missing in the skill, open an issue on GitHub.