clarity-ctl: keeping up with my coding agents

A Claude exchange

Me, looking at what Claude handed me as a “readable” log

Good lord, what is this?

Ok, well, what did we do before this?

Let me get that for you… here you go, it’s in /tmp/ambitious_yellow_zebra_plan.md

…how did you come up with… never mind. Parse this previous experiment log, bring that method into this one and retest.

10 minutes later, in a different tmux window

Did you check the… the yellow ambitious raccoon file?

Sorry, I don’t see that plan within the scope of this project. Are you sure you have the name right?

!@$&

This wasn’t working. I had no clue what state my projects were in anymore, and every project I added made it harder to work on things in parallel. I needed a system.

Not another system/framework, please!

One school of thought is to YOLO it all. I don’t need to know what the plan files are called; my agent should be the planner, coder, analyzer, executor and result parser. Why am I even trying to find the plan file? Blasphemous behaviour! I should just be hitting enter.

And quite honestly, I don’t want to learn another “system” any more than you do, especially because different projects have different structures, requirements and natures. I don’t want to spend my day figuring out how my project fits into someone else’s idea of one.

AND AND AND what if Claude/Codex/GLM went down, huh? What then, huh?

A valid point I make, but (playing devil’s advocate) even if Claude and Codex go down, I can run a 17-35B parameter model locally to parse, synthesize and explain these files (duh). You couldn’t pry my neural accelerators or tensor cores out of my cold, dead hands, after all.

Reading state myself, though? Forget about it.

But what if we settle on an (extremely simple and minimal) system that works for both of us? One that makes my agent less wordy and makes every project I’m working on, research or development, look the same. I know where to go to find a log, an experiment or a git worktree, and quick one-liners for everything we try are automatic and a given.

Clarity, where art thou?

Interestingly, these models like stories. I don’t need a comment in the final code telling me about the first 3 versions that didn’t work (and so didn’t make it in). That’s easily solved with global rules, configs, skills and so on, but the default behaviour is telling.

The truth is we all like stories, and research projects are often stories told in loops:

hypothesis → experiment → result → analysis → repeat

Instead of rejecting this behaviour altogether, why not channel it constructively and automatically? Then I can read the story so far (quickly), the agent knows what’s up next, and I never need to hear about flipping_jiminy_jackrabbit_plan.md again.

Enter clarity-ctl, where less is more

The model is simple:

Make every project look similar regardless of what it is: development or research, one repo or several, one agent working on it or 10.
Make projects readable for humans and agents (on the off chance I do want to read one).
Use git worktrees in a repeatable, reliable way, so code stays friendly to parallel work.
Keep a list of ideas and current work items available at all times, to view, append to or update easily.
Use good old-fashioned structured files and parsing for as much as possible.

Provide the minimum number of commands and state to sustain this, and don’t force people to learn yet another framework that tries to solve everything.

That’s the whole system: no global skills install (everything lives in the project), no MCP servers, a few lines in your AGENTS.md file, and a self-explanatory --help with a handful of commands.

But I already have an involved project. How do I move it into clarity?

Enter adopt. It’s a quick guide for Claude or Codex to work out (with optional input from you) a one-time migration that restructures your existing project. CMake paths and build systems may need a one-time adjustment, and after that they should just work.

Ok, I have a new idea I want to try. What now?

Well, pop an epoch! Add the idea to the list with a couple of lines of notes. When it’s time to try it out, clear the context and ask Claude/Codex/Pi/opencode to start a new epoch for idea 12. It knows what to do, it knows where to go… and so do you!

I’ve been testing it extensively on my own projects. In fact, I put everything else on hold until I had a basic version going, so I could get back to my workflows. Naturally it’s a work in progress and I keep finding little issues here and there, but the guiding principle stays the same: no one wants to learn a new framework or system, so keep this as minimal as possible, then get out of the way.

Give it a shot if you’d love some clarity, and please send feedback my way! I love it.