Merced AI

What it is

Merced AI is a local-first broker for agent harnesses already installed on your machine. It discovers them safely, normalizes their non-interactive interfaces, validates Open Agent Profile documents, and binds profiles to harnesses to create portable bots you can chat with or run one-shot.

It also validates Agentic Graph documents and produces deterministic plans without executing them. Everything it does has machine-readable output alongside the human-readable form.

What it does not do is run an agent loop. The selected harness owns model access, tools, authentication, sandboxing, approvals, and final policy enforcement. That boundary is the whole design.

Why I built it

I had four agent command line tools installed and a growing irritation.

Each had its own configuration format, its own idea of what an agent is, and its own place to store definitions. An agent I had carefully shaped in one was unavailable in another. When I switched tools, or when a project needed a different one, I rebuilt the same reviewer, the same researcher, the same data agent. Each rebuild lost whatever the previous version had learned.

The obvious responses did not work. Standardizing on one tool is impractical and temporary; a better one arrives. Accepting duplication meant three copies of the same definition drifting apart within a quarter.

What I actually wanted was for the definition to be mine and the runtime to be a detail. That requires two things: a portable format for what an agent is, and something that can take that format and run it on whatever is present. The first became the Open Agent Profile. The second became Merced AI. They are the same project seen from two directions.

The restraint is the design

The strongest temptation in building this was to add an agent loop. It would have made demonstrations better and removed a dependency on other people's tools.

I think that would have ruined it, for a reason that is structural rather than aesthetic. A broker that runs agents is a harness competing with the harnesses it brokers. It then has an incentive to route work to itself, and every routing decision becomes suspect. The neutrality that makes a broker useful comes from having nothing to gain from the choice.

There is a second reason. Every harness I would be competing with has invested in things I did not want to rebuild: sandboxing, approval flows, provider handling, tool ecosystems, terminal experience. Reimplementing those badly in order to own the loop would produce a worse tool that also happened to be less useful as a broker.

So the rule I hold to is that Merced AI decides where work goes and never does the work. When I want an agent loop with specific properties, I build a harness, and I have built two of those separately.

Discovery

Merced AI performs safe executable and version discovery across a substantial list of harnesses, spanning widely used commercial coding agents, open source agents, and my own projects.

This turned out to be most of the work, which surprised me. Routing is easy once you know your options. Finding out what is installed, which version, how to invoke it non-interactively, and what that version actually supports is the hard part, and it stays hard because interfaces change between releases.

Doing it safely matters too. Determining a version usually means executing something, which makes a discovery scan a subprocess execution surface. Merced AI runs bounded subprocesses without a shell, with timeouts and cancellation, and supports explicit executable overrides so path resolution never has to guess. A discovery feature that quietly executes whatever it finds on your path would be a poor trade for convenience.

Profiles, bindings, and bots

The unit Merced AI works with is a bot, which is a profile plus a binding.

The profile carries the definition: role and instructions, model or capability tier, tool policy, permissions, and accumulated state. It is a file, following a published specification, readable by anything that implements it.

The binding carries the routing: which harness should normally run this bot and what to fall back to. Bindings can be project-local or user-global, which matches how people actually work. A project may require a particular harness while a personal assistant should run on whatever is present.

Keeping these separate is deliberate. Moving a bot to a different harness is editing a binding, not recreating an agent. The definition and the runtime preference change independently, which is the property that makes the whole arrangement worth having.

Projection reports

This is the feature I am most confident about and the one that took the longest to get right.

Harnesses do not support the same things. One enforces a tool allowlist natively. One has no permission system and documents that clearly. One supports skills; one does not. One takes a capability tier; one needs a specific model name. Projecting a profile onto a harness means some of it survives and some does not.

Merced AI reports the result in four states: native, projected, degraded, and unsupported. Per field, before anything runs.

My first version did not do this. It projected as best it could and ran. That is the tempting design because it always works, and it is dangerous in a specific way: a profile declaring a tool denylist would run on a harness that ignores denylists, and I would believe a boundary existed that did not. The tool had manufactured confidence.

The practical advice that follows: read the projection report. A degraded projection is a real change in what the agent can do, and skipping the report reintroduces exactly the problem the report exists to prevent.

Read-only graph planning

Merced AI validates Agentic Graph documents and produces plans with digests, dependency order, reachability, worst-case execution bounds, cost and tier summaries, and an explicit list of features it cannot support. It does not execute them, which is consistent with the broker position.

Planning without executing is more useful than it sounds. It answers what order steps will run in, which nodes are unreachable from the declared entry points, what the worst case costs if every retry path is taken, how much of the work needs an expensive model, and which parts of the document this environment cannot handle.

That last item is the broker-specific one. A graph written against a rich harness may use features a simpler one lacks. Knowing that before running is the difference between a planned adjustment and a failure at step nine.

Sessions and group conversations

Merced AI supports one-shot runs, multi-turn local chat, attributed multi-bot group conversations, and durable project-local sessions with resume.

I built one-shot execution first, assuming it would be the common case. It was not. Most real use is multi-turn work spanning more than one sitting, which made durable sessions with atomic writes a requirement rather than a nicety. An interrupted write that corrupts a session is worse than losing it, because it fails confusingly instead of obviously.

The group conversation is the feature I did not expect to care about. Several bots, potentially on different harnesses, in one conversation, with contributions attributed. It differs from the usual coordinator pattern in a way that matters: these are genuinely different agents with different definitions and different permissions, not personas of one system.

That distinction has a practical consequence. When three personas of one agent disagree, that is the same system being inconsistent. When three bots with different tool access disagree, that is information. And an implementer with write access and a reviewer with read-only access are genuinely different authority profiles, which collapsing into one agent would defeat.

What using it looks like

1. Initialize and take inventory. Scan for installed harnesses. Most people have more agent tooling than they remember.
2. Create a profile. A named agent with a description and instructions, as a file rather than as configuration inside a tool.
3. Bind it, with a fallback. Choosing the fallback deliberately rather than letting one be picked avoids surprises later.
4. Check the projection. Before running anything. This is the step that separates informed use from optimistic use.
5. Dry run. Validates the arrangement without model access, which makes it usable in continuous integration.
6. Run, one-shot or as a session. With durable records if the work spans more than one interaction.

Two things about that sequence are deliberate. The inspection steps come before execution, which is the same instinct as writing a plan before running it. And every step has machine-readable output, which turns the tool from a convenience into a component other things can script and build on.

When it earns its place

I would rather be useful than promotional, so here is the honest version of who should and should not use this.

It earns its place when you have more than one harness. That is the prerequisite, and everything else follows from it. Specifically:

• You are evaluating harnesses. Running the same bot on three runtimes and comparing is enormously easier than defining it three times, and the projection report tells you what each one actually supports rather than what its documentation claims.
• Your team has heterogeneous machines. Different people have different tools installed and the agent should work anyway.
• Different work needs different execution properties. A governed harness for anything touching real systems, a fast one for daily coding, with the same definitions across both.
• You want agent definitions to outlive tool choices. Which is the general case, and the one I care most about.

It does not earn its place for a solo developer using one harness. There, it is indirection without benefit, and I would rather say so than have someone install it and wonder what it was for.

The advice that applies to everyone, including people who will never use this tool: keep your agent definitions in a portable format. That is the durable part. A broker is one way to exercise portability, and the portability is what has value.

Limits and honest caveats

• Policy still lives in the harness. A profile denying a tool is only enforced if the target harness can enforce it. The broker can decline to route and cannot make a harness do something it does not implement.
• Fallback changes behavior. A second harness may mean different tools, different permissions, and different quality. Treat it as a configuration decision rather than a safety net.
• Harness interfaces move. Discovery tracks versions because an upgrade can change a non-interactive interface underneath you.
• You need at least one harness installed and authenticated. Inventory and dry runs work without model access; real runs do not.
• Profile state is data an agent wrote. Review it rather than trusting it, especially when a profile moves between environments.
• It is local-first by design. It discovers what is on the machine. It does not manage remote infrastructure, and I do not currently intend it to.

What it is not

Merced AI is not an agent harness. It does not run a loop, execute tools, or hold task state during execution. This is the point rather than a gap.

Merced AI is not a policy enforcement point. It bounds its own subprocess execution and defers authority to the harness, and it says so explicitly rather than implying otherwise.

Merced AI is not required in order to use profiles. If your harness implements the specification natively, use it directly. The broker earns its place when you have more than one runtime, which is also the point at which duplication starts.