As frequenters of the DoltHub blog know, we publish a blog article every weekday. I generally like this strategy but there are some days, like the day before Thanksgiving, that are unlikely to garner significant readership. Today is one of those days.

That said, I have an interesting observation I wanted to discuss. This isn’t some feature announcement or explainer. This is a curiosity I noticed with how Claude Code interacted with Dolt. It made me wonder if there was something more to learn here. What better place to collect my thoughts than in a blog article no one will read?

Claude Code and Dolt#

I recently published an article previewing how we plan on integrating “agent mode” into the Dolt Workbench. If you spin up a Claude Code terminal next to the Dolt Workbench, you start to feel like you are using Cursor for SQL. Dolt can help you build Cursor for Everything.

Claude Code can make writes to a running Dolt database and you can follow what it is doing via the Dolt Workbench UI. The days of handcrafting SQL are numbered.

The Issue#

The demo I go through in the article uses Claude Code to insert data related to a fake Dolt IPO. The demo works most of the time.

When the demo fails, it fails in one particular way. Claude Code is never sure which branch it’s writing to. So, sometimes the changes Claude Code makes will be on the master branch. Sometimes the changes Claude Code makes will be on a branch it created specifically for the task. If you specifically ask Claude Code to put the changes on a branch, it will always successfully make a new branch but it’s a 50/50 proposition whether the changes it makes actually end up on the newly created branch.

Why?#

The great thing about coding agents is you can observe their reasoning and the commands they are running. When you observe what Claude Code is doing when executing this demo, it uses the Dolt CLI to execute SQL against the running Dolt database using dolt sql. It controls what Dolt branch to write to using dolt checkout. Herein lies the problem.

dolt checkout is a bit different than git checkout. Unfortunately, dolt checkout does something slightly different depending on the context it is being run in. If there is no running Dolt server, dolt checkout <branch> changes the branch across your terminal session. Every subsequent dolt command will target <branch>. This works exactly like the equivalent git checkout <branch>.

However, if there is a running Dolt server, dolt checkout <branch> will fail.

$ dolt checkout add-dolthub-ipo 
dolt checkout can not currently be used when there is a local server running. Please stop your dolt sql-server or connect using `dolt sql` instead.

The reason it fails is because if there is a running Dolt server, dolt checkout changes the branch for the SQL session. When this command finishes the SQL session is over effectively making dolt checkout a no op in this case. Thus, Dolt explicitly fails the command and notifies the user.

More confusingly, dolt sql -q "call dolt_checkout(<branch>)" will succeed but will also be a no op. dolt sql -q "call dolt_checkout(<branch>)" changes the branch for the dolt sql command’s SQL session which is over after the call dolt_checkout() query completes. Any subsequent command will be operating on the default branch as if call dolt_checkout() was never run. To actually use that checked out branch you have to chain SQL queries in the same dolt sql command like dolt sql -q "call dolt_checkout(<branch>); select * from t; insert into t(foo) values ('bar')".

I’m sure at this point you are significantly confused and guess what? So is Claude Code.

Attempted Fix#

After my demo went awry a few times, I decided to update the AGENT.md that ships with Dolt to see if telling Claude Code about this dolt checkout nuance would help.

To use AGENT.md in Claude Code you run dolt docs print AGENT.md > CLAUDE.md. I built a new version of Dolt, ran the docs command, and Claude Code was still confused. I performed the demo a couple times with the new CLAUDE.md and it was still pretty random what branch Claude Code made changes on. dolt checkout behavior is truly confusing even after you explain it.

A Case for MCP?#

Dolt works pretty well with Claude Code just by interacting via the Dolt CLI or a MySQL client. This made me wonder if Dolt needs MCP at all. I decided that MCP was the standard and even if Dolt works without it, ignoring the standard would be folly. Dolt now ships with a built in MCP server. You add a section to your config.yaml and voila you get an HTTP MCP server on a port whenever you start a Dolt SQL Server.

I’m happy to report that using Dolt’s MCP server, Claude Code operates with branches more effectively. The Dolt MCP server exposes tools that make the branch Claude Code is writing to explicit. If you are having trouble getting agents to work with the correct branch in Dolt, try using Dolt’s MCP interface instead of the raw Dolt or MySQL client.

Fix the Confusing UI?#

Suggesting to use Dolt’s MCP server leaves me a little dissatisfied. The root cause of this issue is not “Claude Code is dumb”. Dolt’s behavior is genuinely confusing to both agents and humans.

Is the moral of the story not “If an agent keeps making mistakes trying to use your tool, your tool is broken”? This is the point I’m trying to make in this article. As more of our interactions with tools are brokered via an agent, we should be keen to observe the common stumbling blocks the agent encounters and use those stumbling blocks as prompts to assess our tools’ interfaces.

Unfortunately, in the particular case of dolt checkout, Dolt is locked into this confusing behavior. Branch and session management are deeply ingrained in the core of the product and changing them at this point would be both technically difficult and backwards incompatible. But, Claude Code identified a confusing UI and made me consider alternatives. That’s a win for Claude Code in my book.

Conclusion#

If an agent can’t use your tool, a human probably can’t either. You’re the tool. Fix your tool.

Happy Thanksgiving. Come by our Discord for more thanks.