Harness Router
Protocol Lattice · Coding · Productivity
Harness Router picks the next tool inside an AI agent harness you already run, using cached decisions, Jev routing, and optional MCTS. Execution stays with your loop.
About Harness Router
What Is Harness Router
Harness Router is an open source Python package that makes one decision inside an agent loop: which tool should run next. It takes the goal, the current observation, an optional last action, and the list of tools your agent can call. It returns a tool name, a confidence score, and a flag saying whether the choice should go back to the planner.
The split matters. A harness already handles arguments, permissions, approvals, retries, and the actual tool call. Harness Router doesn't touch any of that. It sits at a lifecycle boundary the host exposes, such as a prompt hook or a tool result callback, and supplies a nudge at the moment the next step gets chosen. Protocol Lattice publishes it under the MIT license, and the current build is labeled alpha.
This is a narrow tool for a specific problem. Agent tool selection gets harder as catalogs grow, because several tools can look reasonable for the same observation. A router that names one tool with a confidence score gives the harness something concrete to accept or reject. It won't write your code, run your tests, or decide what "done" means.
The project's own benchmark is worth reading before you install it. It found higher token use and longer run times in the tested skill-driven Codex integration, and most routed decisions fell back to the planner. Routing is not a free speedup, and the maintainers say so.
Getting Started
- Install the CLI with uv on Python 3.11 or later:
uv tool install --force --with 'mcp>=2,<3' 'git+https://github.com/Protocol-Lattice/harness-router.git@main'. The package exposeshar,harness-router, andharness-router-mcp. - Export
OPENROUTER_API_KEYin the environment the harness process will use. The default provider model istypesafe/jev-1.13, and routing calls fail over to a planner fallback when the key is missing. - Run the project hook installer for your provider, then copy the two adapter scripts it leaves out. Codex and Claude Code need
pre_decision.pyandstop.pyin their hooks folder, and the installer backs up any settings it merges. - Start a fresh session. The startup hook discovers the tool catalog, prompt and result callbacks precompute a choice, and the validation hook checks the stored decision without making another model request.
Product Information
A quick look at Harness Router's pricing, supported platforms, and performance.
Best for
The users, tasks, and scenarios where this tool fits best.
Users
- Developers running Codex or Claude Code on long tasks
- Teams whose MCP tool registry has grown past a couple dozen entries
- People building a custom agent loop
Tasks
- Choosing between similar read tools
- Getting an agent back on track after a failed test
- Comparing routing against a plain planner
Scenarios
- A debugging session with repeated states
- A tool registry that keeps expanding
- A first experiment with agent tool selection
Key features
A Next Tool Decision With a Confidence Score
Every call returns the tool name, its category, a confidence value, and a fallback flag. The host compares that score against two thresholds: 0.85 to accept a choice directly, 0.60 below which the request goes back to the planner. That gives the harness a clear rule for when to trust the router and when to ignore it.
Three Modes for Different Levels of Trust
hybrid mode accepts confident choices and falls back on uncertainty or handled provider errors. jev_only accepts anything above the fallback threshold and lets errors surface. planner_only skips the model call entirely. You can switch modes per request without touching the harness code.
Cached Decisions Before Any Model Call
The hook bridge builds a state key from the goal, observation, last action, and a compact tool catalog. A matching state reuses the stored choice, and the default cache holds 512 entries per session for 300 seconds. The library also has a smaller cache for high-confidence choices on an unchanged goal and tool set, which you can disable with obvious_cache_size=0.
Jev Routing Through OpenRouter
Jev is a decision model rather than a chat model. It receives a state and a closed list of options, then returns probabilities instead of prose, which suits classification work like tool choice. The default provider model is typesafe/jev-1.13, called through OpenRouter with your own key. When the catalog passes 24 tools, the router can choose a category first and then a tool inside it.
Optional MCTS Tool Search
Monte Carlo Tree Search helps when the best first move depends on what happens later. You supply a graph of predicted states and transitions, along with a simulation budget between 1 and 4,096 and a depth up to 8. The search runs on simulated outcomes, never on real tools, then returns the first action and a principal variation. Without a simulator, the choice goes back to the planner.
Adapters for Five Harnesses
Codex, Claude Code, ohmypi, Antigravity, and DeepSeek Harness each get an adapter built around the callbacks that host exposes. Codex and Claude Code use session start, prompt, tool result, and pre-tool validation hooks. ohmypi reads the live registry and swaps the active tool set. Antigravity uses invocation and result callbacks. A shared Stop hook can request another step when a fresh, confident decision is still valid.
Pros and cons
Pros
- MIT licensed with no account, subscription, or hosted service in the loop, so the full source is yours to audit and change.
- The fallback path is the default outcome. Low confidence, a missing key, or a provider error hands control back to the planner instead of forcing a bad tool call.
- One decision layer covers five harnesses plus a Python API, a CLI, and an MCP server, which saves rewriting the same chooser for each host.
- The published benchmark reports a negative result for one integration, which is rare enough to make the rest of the documentation more credible.
- Caching and category-first routing target the two cases where a router earns its keep: repeated states and oversized tool catalogs.
Cons
- In the tested skill-driven Codex setup, routing raised main-model tokens by 105.9% and pushed mean run time from 115.8 to 228.9 seconds, with 54 of 58 decisions falling back. Measure before you enable it on a live project.
- Routing sends the goal, observation, and tool descriptions to OpenRouter, and session files store that text under `.harness-router/`. Credentials and secrets shouldn't appear in those inputs.
- The project is alpha, has no tagged releases yet, and the hook installer still needs a manual copy step for Codex and Claude Code adapters.
- MCTS only works if you can supply a side-effect-free simulator. Most teams will run the cache and Jev paths and never touch the search tier.
Frequently asked questions
It chooses the next tool in an agent loop. You give it a goal, the current observation, and the available tools, and it returns one tool name with a confidence score or a planner fallback. The harness still builds arguments and runs the call.
Related content
Explore related tools, skills, and articles for Harness Router.
Harness Router Alternatives
Base Code
Base44 (Wix) · Coding · ProductivityBase Code is a shared cloud development environment from Base44. Teammates describe changes to an existing GitHub codebase in chat, preview them live and send them back as pull requests.
Google EmbeddingGemma 2
Google DeepMind · Writing · Image · CodingGoogle EmbeddingGemma 2 is a 740M-parameter open model that turns text, code, images, audio, and video frames into vectors in one 768-dimension space, running on phones and laptops.
GitGlow
GitGlow · Coding · ProductivityGitGlow is a local-first desktop Git client that lets independent developers review their own code and their AI agents' changes in one place before shipping.