I’ve been thinking about this a lot. We’re in this weird moment where everyone’s building agent harnesses, everyone has opinions, and most of the opinions are wrong. Or at least incomplete.
So what actually matters? What makes a harness good?
Light and opt-in
This is the big one. Minimize bloat. Read, write, edit, execute. That’s all you need 99% of the time.
LSP is amazing. I’m not anti-LSP. But let me identify the pain first. Let me opt in. Don’t add things to my context until I want them there. Every feature you add by default is context rot I didn’t ask for.
A cool thing Claude Code does here is notice when you could be using something you’re not. If you keep hitting compiler errors at build time, it’ll suggest enabling the LSP. It doesn’t force it. It watches for the pain and says hey, this might help. That’s the model. Notice the friction, offer the tool, let me decide.
And yet. Claude Code CLI already feels bloated compared to two months ago. Every time it tells me to use my “free passes” I cringe. This is an ad in my IDE! Get out of here! Stop! What are you doing?? I’m trying to work. I don’t need you trying to get me to do marketing for you.
Why does staying light matter so much? Context is expensive. Not just token-wise. Attention-wise. Mine and the model’s. The more stuff in play, the more places things can go wrong. Start minimal. Add complexity when you feel the need for it.
Per-project, per-person tooling
Your monorepo is not my monorepo. The way I test is not the way you test. The deploy scripts are different. The linters, the formatters, the whole shape of the workflow.
But it’s not just per-project. It’s per-person. Different people on the same project want different tools and different contexts. A repo-wide AGENTS.md in a big team is a nightmare. You’re deciding for everyone what context matters and you have no idea what I’m actually doing right now. Maybe I’m debugging a gnarly race condition. Maybe I’m writing docs. Maybe I’m refactoring auth. These require wildly different context. Don’t decide for me.
A good harness knows this. It lets you configure per-project and per-person. Your CLAUDE.md, your skills, your hooks. The harness adapts to the codebase and to you, not the other way around.
This sounds obvious but so many tools get it wrong. They have one way of doing things and you’re supposed to bend your project to match. That’s backwards. The tool should disappear into your workflow.
More than a TUI
Exposes itself through more than just a terminal interface. ACP is cool. There are cases where you’ll want to use a traditional IDE (like Cursor or Zed or maybe even VSCode). Not offering that is annoying.
I’m not saying terminals are bad. I use agent CLIs in terminals all day. But sometimes you need to look at a file diff in a real GUI. Sometimes you need the git integration VSCode gives you. Sometimes your pair programming partner doesn’t want to learn vim keybindings.
A harness that only exists in one interface is a harness you’ll eventually work around. The best tools meet you where you are. Terminal when you want speed. IDE when you want context. Web when you need to share. Being opinionated about interface is different from being limited to one.
I get the sense we’re trying to build walled gardens around the models in these CLIs and it makes me nervous. Imagine if Facebook banned editing React outside of… did Facebook not really make any other devtools? Weird. Imagine if Google never let us edit Go outside of… Antigravity I guess? The analogies are breaking down but you get it. Don’t lock the model behind one interface.
Open source (or at least extensible)
Here’s the thing. I’ve had two occasions in the past two months where editing a coding agent unblocked significant issues for me. Not configuring it. Editing the actual agent code.
This is not going to slow down. If anything the need to customize is accelerating. Your specific workflow, your specific edge cases, your specific pain points. No agent can anticipate all of them. You need to be able to get in there and change things.
I guarantee within the next year almost every large-scale monorepo with large teams will have its own custom coding agent embedded directly into it. Not using an agent. Having one. Part of the repo like your CI config or your docker-compose. Tuned to that codebase, those patterns, that team’s way of working.
Remember when Facebook built custom Mercurial tooling because git couldn’t handle their monorepo? Or Google with their internal Piper system? When the scale demands it, you build your own. Same thing is about to happen with agents. The off-the-shelf harness won’t cut it for complex codebases. You’ll need something custom.
You will benefit from this today. Not eventually. Today. Start experimenting with modifying your harness. Tune it to your workflow. Add the hooks you need. I promise your competitors are :)
Grows with you
This is related to open source but slightly different. A good harness grows with you as you get better at using it.
Day one you need hand-holding. Day thirty you’re annoyed by the hand-holding. Day ninety you want escape hatches everywhere. The harness should accommodate all three stages.
Progressive disclosure. Simple by default, powerful when you need it. The commands you use most should be fast. The commands you’ll use once a month can be buried in config somewhere. Don’t optimize for the tourist experience when your actual users are residents.
What’s missing from this list?
Probably speed? Reliability? Those feel table stakes. A slow harness is a bad harness. A flaky harness is a bad harness. But everyone knows that already.
I think pi coding agent is a lesson the industry will learn quickly. Do yourself a favor and clone it. Spend an afternoon toying with it. Don’t just install it (you should!) but clone it, run it, edit it. The simplicity of these things will astound and delight you.