This post used to be a long tour of my OpenCode configuration. I am keeping the permalink, but the point has changed.

OpenCode was one of the first places where I treated AI tooling as a system instead of a single chat window. I had different agent roles, different permissions, shared prompts, MCP tools, and a Nix-based sync path between NixOS and macOS. Some of the concrete details are less important now. The useful part is what the setup taught me about boundaries.

What the setup looked like

The original configuration had three core roles:

  • ask for read-only explanation and inspection
  • plan for architecture and task decomposition
  • build for edits, tests, and implementation

Around those, I kept specialist agents for frontend, backend, ops, testing, debugging, code review, security, refactoring, documentation, migration, and exploration. The exact list changed often, which was the first lesson: a multi-agent setup is not stable just because it has many named roles.

The roles only became useful when their permissions were different. A read-only reviewer should not be able to patch files. A planning agent should not quietly run a destructive command. A builder needs write access, but it also needs verification habits. Without those boundaries, “multi-agent” becomes a fancy way to create more confusing failure modes.

Cross-platform sync was the real constraint

I was working across NixOS and macOS, so the configuration had to survive environment changes. The OpenCode files lived in my Nix repository and were copied into ~/.config/opencode on each machine.

That sounds mundane, but it mattered. If a tool only works on one laptop because the prompts, model settings, or agent definitions are manually edited there, the system is not really mine. It is just local state pretending to be a workflow.

Nix gave me a way to keep the moving parts inspectable. I could see which files were supposed to define the agent system. I could diff them. I could move between machines without rebuilding the whole setup from memory.

Protocols mattered because they reduced coupling

MCP was useful for a simple reason: it made external tools feel less like one-off hacks. Instead of giving each agent its own private integration story, MCP gave the setup a common way to expose tools and context.

I was also interested in editor-agent protocols for the same reason. If an agent is too tightly coupled to one editor, one chat UI, or one provider, every migration becomes expensive. Protocols do not solve the hard parts of agency, but they make the interface easier to reason about.

That has become a recurring theme in my tooling: I care less about a tool being impressive in isolation and more about whether it has a clean boundary with the rest of the system.

What changed later

My current workbench no longer treats OpenCode as the whole story. The ownership split is clearer now:

  • Codex handles interactive engineering.
  • Hermes handles recurring orchestration.
  • Obsidian holds the human-readable second brain.
  • CC Switch keeps shared tooling and provider plumbing aligned.

Seen from that later architecture, OpenCode was an earlier experiment in the same direction. It helped me notice that “one AI workspace” is usually too vague. The better question is: which component owns which state, and what is it allowed to write?

What I would keep

The durable lessons are small:

  • Agent names matter less than permission boundaries.
  • Cross-platform config should be versioned, not remembered.
  • Tool protocols are useful when they reduce coupling.
  • Orchestration needs observable state more than another layer of prompts.
  • A personal AI setup should be easy to audit when it fails.

That is why this post now sits next to the newer personal AI workbench article. OpenCode was not the final architecture. It was one of the experiments that made the architecture legible.