Philosophy

Opair has three principal objectives that deviate from the aims of most other coding harnesses:

1. Minimise autonomy for the agent.
2. Minimise tool scope for the agent.
3. Minimise feedback loop duration for the human.

Why?

The rationale that underpins those objectives runs through shared ownership, technical debt and the first-idea fallacy.

Shared ownership

Shared ownership is the main reason Opair exists. It rests on the conjecture that it's a good thing when humans who maintain software systems understand how they work. Then, if the underlying models are unavailable because of an outage or some other reason, the humans can continue working effectively without them. They also have the option of using less powerful, cheaper models, because LLMs have not replaced critical thought. It's fine to disagree with this position but you can probably stop reading now because Opair is not for you.

Once you accept shared ownership as a worthwhile aim, it calls into question some of the practices that are commonly applied to working with LLMs. It's widely understood that big changes are harder to understand than small ones. If a co-worker dumps a 5,000 line pull request on you, you'll rightly ask them to break it down into smaller chunks. The same standard should apply when code is written by an agent.

Continuing this train of thought further, pair programming exists in part because some people realised that it's easier to understand code if you actually contributed to it and that when multiple people contribute the result is better code. The tools we use with LLMs can apply this principle too.

Technical debt

Technical debt exists and usually, the longer it's allowed to hang around, the harder it is to pay down. It accrues interest. The cost of that debt is work becoming harder and taking longer. Sometimes it can lead to bugs in production. But it's not always immediately obvious when debt will be incurred. Or it is but incurring it is the easiest way to implement something. These are matters engineering teams should be aware of and discuss at the earliest opportunity.

LLMs amplify technical debt because they shrink the cost of writing code. Code is written faster and in greater volume but it still needs to be read and understood to evaluate technical debt. Your answer might be to delegate that task too to the agent, in which case I refer you back to the section on shared ownership. At some point a human needs to enter the loop and the sooner that happens, the better.

First-idea fallacy

An engineer's first idea is rarely the best one to actually implement. Ideas are cheaper to fix before they've been committed to code, which is why we have RFCs, design reviews and whiteboard sessions. LLMs affect this equation because implementation is essentially free, so it's tempting to view planning and design as less important now. If an idea turns out to be bad, you can just implement your way out of it later. It rarely works out like that in practice though, because implementation is also inertia. Other things depend on it, there might be a cost to changing those too and so on.

When humans are implementing, they often refine their ideas at the same time. Sometimes that means small tweaks here and there, sometimes it means switching to a fresh branch to refactor something and land it in advance of the main change, sometimes it means scrapping an idea completely and going back to square one. All those tradeoffs can be lost when an agent works autonomously.

How?

Driver/navigator separation

Opair separates the roles of driver and navigator, granting the agent specific permissions that match its current role. Most of the time the user navigates and the LLM drives, but the roles can be swapped at any point by pressing Shift+Tab.

In driver mode, the agent has access to tools that can write to the file system, although execution is gated by user approval. In this mode Opair is similar to other harnesses, but with less autonomy for the LLM.

In navigator mode, the LLM has no access to writable tools. Instead it monitors the project for changes and is instructed to act as a thinking partner. The agent is notified when project files are changed and it then comments on the diff.

Role-based permissions

We touched on driver and navigator roles already, but there are also roles for planning, code review and documentation. These all have independent permission sets, defined as JSON files in the loops/ directory. For example, the plan and document roles have a special permission that grants them automatic write access to files they've created. This allows them to update their own generated output, without forcing the user to approve every time. The project write permission can be opted in to auto-approval, for cases when you really do just want the agent to get on with something.

Restricted tools

There's no tool that grants shell access in Opair. The agent can't run arbitrary executables. Instead it has access to a limited set of engineering-related tools, dependent on the capabilities of the host system. If you have the Go toolchain installed, the agent can run go build, go test, go vet etc. If Rust is detected, it can run cargo and so on. If a tool you want doesn't exist yet, creating new tools is as easy as writing new JSON files in the tools/ directory.

Out of the box, there are no tools that enable the agent to run git commit or even git add. The whole point of Opair is for the human to be an active contributor. That means understanding enough to be able to write a decent commit message yourself.

Prompting

Opair's prompts frame everything in terms of partnership and pair programming. The LLM is encouraged to share its thinking early and minimise feedback latency with the user. The result is an experience that should feel like collaboration, not issuing instructions and then getting on with something else.

The prompts are also just text files on disk. You're encouraged to edit them, so they're better tuned for your own ways of working. Prompt changes are hot-reloaded while Opair is open.

Isn't this much slower?

Using Opair will write lines of code more slowly than using a harness with more autonomy, yes. But writing lines of code is not the point of software engineering; working software is. Optimising time-to-PR doesn't necessarily improve time-to-done.

Getting to working software is rarely a straight line from a to b. If you try to automate humans out of the process, that journey can take longer. Opair is a bet on the opposite approach, that active human involvement will produce better software, faster.