README
¶
hrn: run coding agents, keep every run, compare them
hrn is one Go binary that hands a coding task to an agent (Claude Code, Codex, Gemini, opencode, agy, or its own Anthropic API loop), saves everything that happened, and lets you watch it live, replay it, run several in parallel, and score agents against each other.
How a run works
flowchart LR
you[You, or another agent] -->|hrn run or hrn batch| hrn[hrn]
hrn --> backend{Backend}
backend --> api[hrn's API loop]
backend --> cli[Claude Code, Codex, Gemini, opencode, agy]
hrn --> wt[Its own git worktree and branch]
wt --> gates[Gates: your build and tests]
gates --> record[(Run record)]
record --> watch[hrn watch: live dashboard]
record --> evals[hrn eval and hrn eval diff]
- You give a task. A prompt, from the command line or a batch file.
- hrn picks a backend. Its own API loop, or an agent CLI you already have installed and signed in to. Each uses its own plan or credentials.
- The agent works in its own worktree. A batch gives each task a separate git worktree on its own branch, so parallel agents never step on each other.
- Gates check the result. Your build and tests run after the agent finishes. A failing gate can trigger a retry.
- Everything is recorded. Prompts, tool calls, answers, tokens, cost and timing go to a run record on your disk. The record stays local; the agent's own requests still go to its provider.
- You review and compare. Follow a run live, replay it, merge the branches that passed, or
run the same task set across backends and models with
hrn evaland diff the results.
Try it in a minute
You need Go 1.26.4 or later, and at least one backend. Install hrn, then see which backends it can use:
go install github.com/cristiangirlea/harness/cmd/hrn@latest
hrn backends
Run a read-only task in one of your projects:
cd path/to/your/project
hrn run -b codex --mode readonly "Explain this project and its main entry points."
Open the dashboard in another terminal, then go to http://127.0.0.1:8089:
hrn watch
It shows runs started through hrn, as they happen. For a tour of the pages, see hrn watch and Ada, in pictures.
Prefer the terminal? hrn runs lists recent runs, hrn show <run-id> replays one, and
hrn show -f <run-id> follows a run live.
Backend setup, with each agent's login and what it costs, is in backends.
Updating an existing install is hrn update; see hrn update.
What you can do
- Run and revisit tasks. Save prompts, tool calls, answers and usage. Continue a run on the same backend, or hand it to another.
- Watch progress. A built-in local dashboard shows runs, batches and tool calls as they happen.
- Split work across agents. Run a batch in separate git worktrees, with build and test gates and retries.
- Compare results. Evaluate backends and models against the same tasks and checks.
- Connect through MCP. Give the API loop any stdio MCP server's tools, or expose hrn itself as an MCP server so another agent can delegate work to it.
The Go code uses only the standard library. Agent CLIs are optional external programs: install the ones you want.
Where it fits
hrn is one part of a small set of AdaNext tools. Only the first two links below exist in code today; the rest are planned, and each README says so.
| Repository | How it relates to hrn | Status |
|---|---|---|
| hrn-evals | The eval suites hrn runs. Each suite is an hrn eval spec, and the diff between two runs is how a regression shows up. |
In use |
| harness (this repo) | The engine: runs, records, batches, evals, the dashboard. | In use |
| adanext-exec | A planned gate every agent shell command goes through: policy, limits, and an audit log. Its README names hrn as a first user. | Being designed |
| adanext-map | A planned code map for agents. Its README says hrn will hand the map to every backend it runs. | Being built |
| AdaNext OS | The desktop workspace that runs an agent on a feature branch and brings back verified changes. | Early |
Choose your next step
| I want to… | Read |
|---|---|
| Find commands, flags and budgets | Command reference |
| Choose a backend or continue a run | Backends and continuation |
| Understand what an agent is allowed to do | Permissions and command guard |
| Connect hrn to an MCP host or tools | MCP integration |
| Run parallel tasks and manage their branches | Batches and worktree cleanup |
| Reuse a few worktrees per repository instead of making new ones | Reusable workspaces |
| Use the dashboard, phone view or Ada bot | Live dashboard and Ada |
| See the dashboard and Ada in pictures | hrn watch and Ada, in pictures |
| Score tasks or compare models | Evaluations and reports |
| Inspect or prune saved data | Run records |
| Integrate hrn with a supervising program | Exec protocol |
| Find, write or verify a kept script | Kept scripts |
Permissions and privacy
Start with --mode readonly and read the backend-specific permission
modes. The command guard is a guardrail, not an
operating-system sandbox, and the same mode does not mean identical permissions on every backend.
Run records can contain source code, prompts and tool output, so treat the records folder as
you would the code itself. The dashboard listens on loopback by default. --lan lets anyone on
the selected network read the records without a login. With --public, the page is reachable
beyond loopback only through a Cloudflare Tunnel and Access application that you set up; see
watch exposure. Security boundaries and how to report a
vulnerability are in SECURITY.md.
Contributing
See CONTRIBUTING.md for source builds, checks, the repository layout and releases. PLAN.md records the work queue and past decisions.
License
MIT.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
hrn
command
Command hrn is a personal agent harness: one CLI that runs a coding task on the harness's own API agent loop or on an installed agent CLI, and records every run the same way.
|
Command hrn is a personal agent harness: one CLI that runs a coding task on the harness's own API agent loop or on an installed agent CLI, and records every run the same way. |
|
internal
|
|
|
agent
Package agent defines the shared backend contract.
|
Package agent defines the shared backend contract. |
|
batch
Package batch is the orchestrator: it runs a set of tasks against one git repository, N agents at a time, each in its own worktree on its own branch.
|
Package batch is the orchestrator: it runs a set of tasks against one git repository, N agents at a time, each in its own worktree on its own branch. |
|
eval
Package eval is the scoring layer: one task set run across a matrix of backends, models and efforts, repeated, and judged by the same gates a batch uses and, optionally, by a model reading each diff against a rubric.
|
Package eval is the scoring layer: one task set run across a matrix of backends, models and efforts, repeated, and judged by the same gates a batch uses and, optionally, by a model reading each diff against a rubric. |
|
execproto
Package execproto serves one recorded run over the supervisor JSONL protocol.
|
Package execproto serves one recorded run over the supervisor JSONL protocol. |
|
followup
Package followup plans a run that continues an earlier one, on the same backend or another.
|
Package followup plans a run that continues an earlier one, on the same backend or another. |
|
gc
Package gc finds the git worktrees whose work is already merged and removes them, with their build output.
|
Package gc finds the git worktrees whose work is already merged and removes them, with their build output. |
|
gitenv
Package gitenv keeps git run by hrn on the repository of the directory it runs in.
|
Package gitenv keeps git run by hrn on the repository of the directory it runs in. |
|
gitretry
Package gitretry handles Git's brief exposure of incomplete worktree metadata.
|
Package gitretry handles Git's brief exposure of incomplete worktree metadata. |
|
hrnmcp
Package hrnmcp exposes hrn itself as an MCP server, so a Claude Code session (or any MCP host) can delegate tasks to any backend, several at a time, fan a set of tasks out into worktrees with batch, and read the records back.
|
Package hrnmcp exposes hrn itself as an MCP server, so a Claude Code session (or any MCP host) can delegate tasks to any backend, several at a time, fan a set of tasks out into worktrees with batch, and read the records back. |
|
limits
Package limits keeps work going when a CLI backend reaches its plan's usage limit.
|
Package limits keeps work going when a CLI backend reaches its plan's usage limit. |
|
mask
Package mask removes secret-looking values from human-facing text only.
|
Package mask removes secret-looking values from human-facing text only. |
|
mcp
Package mcp is a dependency-free implementation of the Model Context Protocol over its stdio transport: JSON-RPC 2.0 messages, one per line.
|
Package mcp is a dependency-free implementation of the Model Context Protocol over its stdio transport: JSON-RPC 2.0 messages, one per line. |
|
prefs
Package prefs stores backend preferences without depending on execution or records.
|
Package prefs stores backend preferences without depending on execution or records. |
|
purpose
Package purpose says what a run was for (review, debug, implement, ...) from its prompt, with ordered keyword rules: the first rule that matches wins.
|
Package purpose says what a run was for (review, debug, implement, ...) from its prompt, with ordered keyword rules: the first rule that matches wins. |
|
qr
Package qr makes QR codes (ISO/IEC 18004) for short text such as a link: byte mode, error correction level M, versions 1 to 10 (up to 213 bytes), and the mask the standard's penalty rules prefer.
|
Package qr makes QR codes (ISO/IEC 18004) for short text such as a link: byte mode, error correction level M, versions 1 to 10 (up to 213 bytes), and the mask the standard's penalty rules prefer. |
|
report
Package report aggregates the run and batch records into tables: how often each backend or model passes, what it costs and how long it takes.
|
Package report aggregates the run and batch records into tables: how often each backend or model passes, what it costs and how long it takes. |
|
retrieval
Package retrieval defines the dependency-free control-service wire contract.
|
Package retrieval defines the dependency-free control-service wire contract. |
|
route
Package route builds purpose routing tables from measured eval results.
|
Package route builds purpose routing tables from measured eval results. |
|
route/table
Package table stores routing rows without depending on execution or eval.
|
Package table stores routing rows without depending on execution or eval. |
|
runlog
Package runlog records every run to disk so runs can be listed, replayed and compared later (the eval and orchestrator layers read these records).
|
Package runlog records every run to disk so runs can be listed, replayed and compared later (the eval and orchestrator layers read these records). |
|
scripthint
Package scripthint names the kept script that covers an inline script an agent is about to run, for an advisory Claude Code PreToolUse hook.
|
Package scripthint names the kept script that covers an inline script an agent is about to run, for an advisory Claude Code PreToolUse hook. |
|
shape
Package shape makes conservative, locally checked summaries of tool text.
|
Package shape makes conservative, locally checked summaries of tool text. |
|
tools
Package tools provides confined API tools.
|
Package tools provides confined API tools. |
|
update
Package update moves every hrn binary on this computer to another build: it reads what each copy says with `version`, swaps the file under a backup, and restarts a running hrn watch.
|
Package update moves every hrn binary on this computer to another build: it reads what each copy says with `version`, swaps the file under a backup, and restarts a running hrn watch. |
|
watch
Package watch follows hrn's run and batch records while they are written: a tail of a run's events.jsonl for hrn show --follow, and a local web page for hrn watch that streams the same timeline with Server-Sent Events.
|
Package watch follows hrn's run and batch records while they are written: a tail of a run's events.jsonl for hrn show --follow, and a local web page for hrn watch that streams the same timeline with Server-Sent Events. |
|
ws
Package ws keeps a fixed set of reusable worktrees ("slots") per repository, at <main checkout>/.hrn/slots/<n>, so a checkout keeps its build output from one task to the next.
|
Package ws keeps a fixed set of reusable worktrees ("slots") per repository, at <main checkout>/.hrn/slots/<n>, so a checkout keeps its build output from one task to the next. |
|
name: answers summary: Provide JSON test summaries and bounded TCP probes for Bash entry points.
|
name: answers summary: Provide JSON test summaries and bounded TCP probes for Bash entry points. |
|
comment-check
command
name: comment-check-main summary: Check Go comments against the repository rule and baseline.
|
name: comment-check-main summary: Check Go comments against the repository rule and baseline. |
|
tool-shapes
command
name: tool-shapes-defs summary: Measure the api loop's tool definitions against the recorded context per model call.
|
name: tool-shapes-defs summary: Measure the api loop's tool definitions against the recorded context per model call. |
Click to show internal directories.
Click to hide internal directories.