Use Jujutsu to Plan and Build with Claude

This week, I read about Steve Yegge’s Beads.

I was skeptical.

He writes like someone trying to prompt inject your LLM. But he’s always written that way.

I tried beads, and it was pretty good. I wrote all of uplift using beads.

But it was also pretty buggy. I noticed I had multiple bd daemons running and checking git status. Not cool.

Jujutsu

I shared beads with Nate Smith, and he said, “You could do that with Jujutsu.”

We both tried it and it rocks.

Here is my current CLAUDE.md , which teaches Claude to use Jujutsu to plan and track issue progress.

Jujutsu is a Git-compatible version control system. The graph foundation of Jujutsu makes it perfect for this kind of work because Claude can add empty TODO commits along the way and connect them to one or more tasks that also need to be done.

Here is the gist of the instructions Claude gets:

Planning Best Practices

Create Descriptive Empty Commits:Each commit description should fully explain what needs to be doneInclude acceptance criteria in the descriptionNote any dependencies or prerequisitesUse clear, actionable language

The steps for you are:

1. Enter plan mode and build a plan with Claude.
2. When you’re ready, tell Claude to make empty commits for each step in the plan.
3. Tell Claude to work through one commit at a time until it is done.
4. If at any point Claude struggles or decides to compact memory. Kill your session and start a new one with “We are in the middle of working through a to-do list created in jj. Find the task you were in the middle of and finish it, then move on to the next task until you are done.

On Friday, I refactored a small Ruby library with Claude and Jujutsu, and it was really nice. I knew what I wanted the end state to look like and described that to Claude. Claude then made a plan with detailed acceptance criteria for 12 distinct steps. Once I approved, Claude turned the plan into jj commits and worked through them.

Around step 7, Claude slowed down and suggested that steps 7 through 12 were tightly coupled. I ran /clear to start a new session and pick up where we left off. Claude still saw that steps 7 through 12 were coupled, but no longer tried to implement them all at once. It methodically worked through the steps.

At the end, Claude suggested a five-PR stack so developers could review PRs implementing the requirement in separate logical steps.

Why This Works (My Theory)

Steve Yegge is right about why this works, but more than a little off base about needing a whole buggy go program to do it.

Claude works better with this workflow because the context you send is focused and clear. A big old markdown doc is fine, but Claude has to read the whole thing multiple times to find the next task.

With the Jujutsu workflow, Claude can read a summary of what is done with jj log and pick up the following task with jj edit

The LLM on the other side of the Claude agent receives a more focused context. As the conversation continues, the thread narrows to specific tasks.

In past work, when I’ve used a plan.md or Claude’s default todo list, Claude struggles because it reads the entire plan every time, multiple times, since the whole chat is sent to the LLM with each message. This means the context gets bloated with planning and loses focus on accomplishing tasks.

With the Jujutsu workflow, planning shows up exactly once in the context. Then jj log shows incremental progress.

I Want This

It’s good! You should try it. Get Jujutsu set up and copy my CLAUDE.md.

If you don’t know how to use Jujutsu, Claude can learn by using jj help.

The most important thing to remember is: if you think the agent is lost, you’re probably lost too!

You can /clear your session, take a break, and start fresh. Claude will pick up where it left off because it knows to use jj log to find the next task.