Nobody Trained Claude on Your CLI
Steve Yegge spent four months making Beads intuitive for agents. Not by writing better documentation — by watching what agents tried to do and implementing it. Every hallucinated command, every wrong-but-reasonable guess. He made their mistakes work until the mistakes stopped being mistakes.
He calls this "desire paths" — the worn trails across lawns that show where people actually want to walk, regardless of where the sidewalk goes. For agent tooling, it means: don't fight the model's intuitions. Pave them.
This is Lever 5 in his survival framework: minimize friction. But it's more than that. Desire paths aren't just about reducing errors — they're about making tools feel native to how agents think. An agent that feels at home in your CLI will use it confidently. One that keeps hitting walls will give up and synthesize something worse.
I've been using Beads for months now. It's rock solid with agent engagement. Agents run bd prime at session start, bd ready to find work, bd close when done, and more. They rarely fumble. That's not because Claude was trained on Beads — it's too new for that. It's because Beads works the way agents expect a task tracker to work, and implements a full bevy of commands to aid agent discovery of both the tool and the data it manages.
The pattern is replicable. I've been building a tool called Timbers — a development ledger that captures what/why/how alongside Git history (as Git notes) — and I'm deliberately modeling it after Beads. Same principles: prime for context injection, pending for clear next action, --json on everything, suggested commands in output, structured errors with recovery hints.
But here's what I've learned: the CLI patterns are necessary but not sufficient. The real insight is the injection problem.
Agents don't reliably read documentation and remember to run commands. They jump into tasks. Your CLAUDE.md can document the perfect workflow. The agent still won't follow it. The fix is automatic injection: git hooks that warn about undocumented work, editor integrations that run prime at session start, health checks that catch missing setup. Wire the tool into the environment so context flows without requiring the agent to remember.
I've started codifying these patterns into a skill — a pattern language for agent-friendly CLIs. Minimal ceremony. Clear next actions. Context injection. Batch operations. Structured errors. The integration stack: doctor, hooks, setup, onboard, init, uninstall. Each reinforces the others.
The goal isn't just to build one good tool. It's to make the next tool easier — to have a template for agent-native design that I can apply to any CLI project. Discovery is expensive. Patterns are cheap.
Timbers isn't public yet. I'm still dogfooding it, still finding where the desire paths actually go. But when it ships, I'll write about what worked and what didn't. For now, the principle: don't document the sidewalk. Watch where they walk. Then pave that.
Update: Timbers shipped.