How I Plan AI Agent Projects With Beads

Most people plan projects in a Google Doc or a Notion page. Write a list of things that need to happen, add some checkboxes, and start working through them.

That works fine when you’re the one doing the work. But when you’re directing AI agents to build something (where each piece depends on other pieces, different tasks need different tools, and one agent picks up where another left off) a flat list falls apart fast.

The real problem is memory. Agents forget. A long project spans multiple sessions, and every time the context window fills up or a new agent takes over, the plan in the agent’s head evaporates. You re-explain what you’re building, what’s already done, and what depends on what, over and over.

I’ve been using a tool called Beads to fix this, and it’s changed how I plan projects.

What Is Beads? (The Plain-English Version)

Most people call Beads a task tracker for AI agents. That undersells it. Beads is persistent memory for agents, a place where the plan, the dependencies, and everything the agents have learned live outside any single conversation.

Instead of a flat to-do list, it builds a graph: tasks that know about each other, with dependencies, priorities, and status that agents read and update on their own. And it survives. Close your laptop, hit a context limit, hand the work to a different agent tomorrow, and the plan is still there exactly as it was. Any agent can run bd prime to reload the project’s workflow and stored decisions, then check live task state with bd ready and bd show.

Think of it this way. A normal to-do list says “do these 12 things.” Beads says “do these 12 things, but #4 can’t start until #2 is done, #7 needs a different skill than #3, here’s the exact status of every piece right now, and here’s what we learned last time we touched #9.”

Agents claim tasks, update status, track dependencies, and remember decisions without you micromanaging. You set up the plan, and they work through it across days and sessions without losing the thread.

Everything lives in a local, version-controlled database inside your repo (a .beads/ directory), synced through your normal git remote with bd dolt push and bd dolt pull. There’s a plain-text issues.jsonl export you can read or diff, though the database, not the export, is the source of truth. No separate cloud service, no account.

Why a Flat List Breaks (Once Agents Are Doing the Work)

A Google Doc, a Notion board, even Claude Code’s /plan mode all produce the same thing: a plan that lives in one place, for one moment. That’s fine for a human, or for a single focused session. It breaks the moment autonomous agents execute over time, in four ways:

An agent will happily start a blocked task. Nothing in a flat list stops it. Order is a suggestion, not a rule. So an agent builds the article template before the design system exists, and you clean it up later.
“What’s ready right now?” isn’t a question you can ask a document. A human can eyeball a Notion board and figure out what’s unblocked. An agent can’t query it, so it either asks you or guesses.
Skill and tool context gets re-explained every prompt. “Use the ElevenLabs skill for this one, the design skill for that one.” A flat list has nowhere to put that, so it lives in your head and gets typed out over and over.
Context dies between sessions. The plan the agent understood at 2pm is gone by tomorrow. The next run re-derives it, usually a little differently than last time.

Beads closes each of these. The graph computes ready-versus-blocked on its own, so blocked tasks don’t show up in bd ready and an agent working the ready queue won’t start them. bd ready --json is machine-readable, so the agent just asks. Skill tags travel with each task. And because it’s persistent, bd prime reloads the workflow and stored decisions, so you’re not re-explaining the project every session.

Beads vs `/plan` (the one that matters)

If you use Claude Code, the closest thing you already reach for is /plan mode, so be clear about what each is for.

/plan is for thinking a task through before you build it. The agent researches, proposes an approach, you approve. It’s good at that. But what it produces is a document for one run. It isn’t a dependency graph that enforces order, it isn’t machine-readable state a second agent can query with bd ready, and it doesn’t carry memory forward across sessions the way Beads does.

Beads is where that plan goes to live and execute: persistent across sessions, a dependency graph that enforces order, queryable by any agent, with memory that accumulates as you go.

They’re not rivals. Use /plan to think. Use Beads to remember and execute. Plan the work in plan mode, then materialize the result as beads so it outlives the session.

Beads vs Linear / Notion

If you run projects in Linear or Notion, you’re not wrong. They’re built for human teams and they’re good at it. The gap shows up when AI agents do the execution:

Agents can’t natively query “what’s unblocked and ready?” from a Notion database.
Dependencies in Notion are tracked by hand, not enforced. An agent can start a blocked task.
Skill requirements aren’t a first-class concept, so you re-explain them in every prompt.
There’s no shared, machine-readable memory that carries decisions forward across sessions.

Beads makes each of those first-class. bd ready is a command an agent can call, dependencies are enforced by the graph, skill tags ride along with the task, and bd remember gives the project a memory that persists.

This holds for content workflows, marketing campaigns, and business planning, not only code. If your project has tasks, dependencies, and multiple execution agents (human or AI), the graph structure helps. I’ve used it for the littlemight.com content pipeline, not just engineering builds.

The 7-Step Beads Workflow

This is the workflow I run, on a real example: building out the littlemight.com website.

Step 1: Plan the Project

Before touching any tools, I think through what needs to happen. Usually that means talking out loud (via Wispr Flow for voice-first planning) to an agent:

“I need to build out the littlemight.com site. We need a landing page, article pages, a podcast page, a newsletter signup, and a custom 404. The landing page is the entry point. Articles need cross-linking. The podcast page needs a booking form and a short audio trailer to launch it.”

The agent helps me structure this into a clear scope. We go back and forth until it makes sense.

What does 30 minutes of planning look like? I open Claude, describe the project in plain language, and ask it to break the work into discrete tasks. Then I push back: “What did we miss? What depends on what?” That back-and-forth is the planning session. It’s exactly where /plan mode shines, and the output is what I feed into Beads next so it survives.

Step 2: Create the Beads

Now we turn the plan into beads: individual tasks with dependencies.

bd create "Build landing page" -p 0           # Priority 0 (highest)
bd create "Create article template" -p 1
bd create "Build podcast page" -p 1
bd create "Produce podcast trailer audio" -p 1
bd create "Add newsletter signup" -p 2
bd create "Create custom 404" -p 2
bd create "Cross-link articles" -p 2
bd dep add bd-f2a1 bd-c3b2                     # Podcast page depends on template

Each bead has a hash ID (like bd-a1b2), a priority, and a list of what blocks it. bd dep add <child> <parent> reads as “the child depends on the parent,” so above, the podcast page (bd-f2a1) is blocked until the template (bd-c3b2) is done. Agents read the graph and know exactly what’s ready at any moment.

Step 3: Fable Reviews the Plan

I hand the full bead graph to Fable, Anthropic’s most capable model, and ask it to review the plan like an architect:

“Here’s my project plan in beads. Review it for missing dependencies, sequencing issues, and anything I forgot.”

Plan review is exactly the kind of work Fable is built for: deep reasoning over a long horizon, not speed. Its job is to catch what you can’t see yet, like “you need a design system before you build the article template” or “the newsletter signup needs an email provider configured first.”

Step 4: Codex Reviews It

Then I run Codex (OpenAI’s coding agent) over the same plan for a second opinion. Codex approaches it differently, more focused on technical implementation, build order, and what’s going to break. It asks “can this actually run?” rather than “does this make sense?”

Two models reviewing the same plan almost always surface something one of them missed. If you haven’t tried a two-model review workflow, this is the most natural place to start.

Step 5: Claude Updates the Beads

Based on the reviews, Claude updates the bead graph. It adds the beads Fable and Codex flagged: a design-system task the template now depends on, an email-provider task the newsletter signup needs, and the podcast booking form that never got created. It adjusts dependencies and reorders priorities. The plan gets tighter.

bd ready --json    # What can we work on right now?

Step 6: Codex Reviews the Beads (Round 2)

After the beads are updated, Codex reviews the actual structure: the specific tasks, dependencies, and sequencing in the database, not the plan in the abstract.

The second pass is where the real gaps surface. Almost every time, it catches two or three things that weren’t obvious during planning. A dependency is backwards. A task is too big and should be split. Something was assumed but never made explicit.

It’s the difference between a plan that sounds good and one that works when agents start executing.

Step 7: Assign Skills to Each Bead

Last, I go through each bead and tag it with the specific skills or tools it needs.

Podcast page → the design skill, the Astro skill
Podcast trailer audio → the ElevenLabs skill (voiceover + noise cleanup)
Newsletter signup → the ConvertKit skill
Deploy to Cloudflare → the Cloudflare deploy skill
Article SEO → the SEO skill

The bead becomes self-describing. The skill that knows how to do the work is named on the exact task that needs it, and those skills come from completely different worlds. The podcast page pulls the design and Astro skills. The trailer audio pulls the ElevenLabs skill for voiceover and noise cleanup. An article pulls the SEO skill. A database task on a different project would pull a Postgres skill. When an agent picks up a bead, it already knows which of those to load, not everything and not the wrong thing.

This solves a real problem. A design task and an audio task have almost no skills in common, and you don’t want every skill loaded for every bead or the agent drowns in context it doesn’t need. Tagging each bead with the skills it needs means each task tells the agent which context to pull, at the moment it’s needed. The plan carries both what to do and how to do it.

bd-a1b2  Landing page             [design, astro]          ready
bd-c3b4  Podcast trailer audio    [elevenlabs]             ready
bd-e5f6  Newsletter signup        [convertkit]             blocked by bd-a1b2
bd-g7h8  Deploy to Cloudflare     [cloudflare]             blocked by bd-a1b2

When a bead is done, the agent closes it with bd close bd-a1b2, which unblocks anything that was waiting on it. Dependents move from blocked to ready and show up on the next bd ready call. You don’t manage that transition; the graph does.

The Beads Commands You’ll Actually See

You barely type any of these yourself. Once Beads is installed, it sets up your agents’ hooks and guidance so the agent runs the commands for you: checking bd ready, claiming work, closing beads, updating status. Treat this section as a map of what’s happening under the hood, not a list to memorize.

With that said, here are the ones worth knowing, grouped by what you’re doing (there are more; bd --help has the full set).

Set up the project and wire in your agents:

bd init                     # Create the beads database in your project
bd setup claude             # Install Claude Code hooks + settings
bd setup codex              # Install the Codex skill, AGENTS.md guidance, and hooks
bd setup cursor             # (also: factory, mux)

bd setup claude and bd setup codex do the heavy lifting. They install the hooks and guidance that teach your agent the loop, so it checks bd ready, claims work, and updates status as part of how it works, instead of waiting for you to prompt each command.

Plan and shape the work:

bd create "Build landing page" -p 0    # Create a task at priority 0 (highest)
bd dep add <child> <parent>            # child depends on parent (enforced)
bd show bd-a1b2                         # Task detail + full audit trail

Tasks can be typed (bug, feature, message) and nested into epics with hierarchical IDs: bd-a3f8 is an epic, bd-a3f8.1 a task under it, bd-a3f8.1.1 a sub-task.

Execute (this is what agents run):

bd ready                    # List tasks with no open blockers
bd ready --json             # Same thing, machine-readable for agents
bd update bd-a1b2 --claim   # Agent claims a task (assigns it, marks in-progress)
bd close bd-a1b2            # Mark done; auto-unblocks its dependents

Remember (the part flat lists can’t do):

bd prime                    # Print agent workflow context + stored memories
bd remember "Posts are MDX in src/content/posts; edit them in Keystatic locally"

bd prime is how a fresh agent picks up the project’s workflow and the decisions you’ve told it to remember; it pairs with bd ready and bd show for live task state. bd remember is how those decisions get stored. Together they’re the memory that survives across sessions.

Sync across machines:

bd dolt push                # Push the beads database to your git remote
bd dolt pull                # Pull the latest state

There’s more (stealth mode with bd init --stealth to keep Beads files out of the code repo, contributor mode to route planning to a separate repo), but those commands are the whole day-to-day loop.

From Plan to Execution

Once the bead graph is locked, you run it. Two options I reach for.

codex-build is my free, open-source Claude Code skill for disciplined execution. Your orchestrator drives, Codex writes all the code, tests have to pass before every commit, one task per commit, one PR at the end. Beads is the plan; codex-build is how the plan gets built without giant unreviewable diffs. Install it as a Claude Code plugin (/plugin marketplace add cathrynlavery/codex-build, then /plugin install codex-build@codex-build), or clone and symlink it, then point it at a plan.

Conductor is the parallel option, a Mac app that runs several agents at once, each in its own isolated git worktree. Beads plans the work and tracks completion; Conductor runs the agents at the same time without collisions. If you’re moving fast across three or four workstreams at once, that’s the combo.

Why This Works Better Than a To-Do List

Three reasons.

1. Less slips through. The layered review (Fable once, Codex twice) catches things a solo planning session would miss. It’s like having two senior engineers read your plan before you write a line of code.

2. Agents can self-serve. When an agent asks “what should I work on?” the answer is bd ready. No ambiguity, no waiting on me to assign tasks. The graph knows what’s unblocked and highest priority, and bd prime gives a brand-new agent the project’s context to start from.

3. The right skills are named up front. Because each bead lists the skills it needs, the agent doesn’t waste time working out its tools. It picks up a bead and already knows what to load.

The Honest Part

This workflow costs about 30 to 45 minutes of upfront planning. That’s more than most people spend.

But the time you spend planning with agents is almost never the time that hurts. The time that hurts is re-planning, when something was missed, a dependency was wrong, or an agent went down the wrong path. Thirty minutes of structured planning saves me hours of cleanup later, every time.

And to be fair, Beads is overkill for small work. A three-task afternoon project doesn’t need a dependency graph; /plan mode or a scratch list is fine. Beads earns its keep once a project spans multiple sessions or multiple agents, which is exactly when a flat list would have quietly fallen apart on you.

Installing Beads

Beads is open source and free, and you don’t have to install it by hand. Point your coding agent at the Beads GitHub repo and tell it “install and set up Beads in this project.” The agent reads the repo, installs Beads, runs bd init, and wires in the hooks for your agent (bd setup claude or bd setup codex). You don’t have to remember any of the CLI, which is the whole idea.

If you’d rather do it yourself, it’s a few commands:

brew install beads              # macOS/Linux (recommended)
npm install -g @beads/bd        # or via Node
bd init                         # Initialize in your project
bd setup claude                 # Wire in your agent (or: bd setup codex)
bd create "My first task" -p 0  # Create a task
bd ready                        # See what's ready

Either way, you don’t have to be technical to use it. If you’re reading littlemight.com, you already point agents at problems. This is one more.

Beads on GitHub →

Related:

codex-build — my free skill for turning a locked plan into test-gated commits, one task at a time
Why I Use Two AI Models to Review Every Piece of Code — what happens after your agents build something

This is part of the Little Might workflow series: how I actually plan and execute projects using AI agents.