Expert gets expert model
Every agent declares its own model: in agents/*.md, so a simple retrieval does not pay for reasoning capability it does not need, and a complex task does not settle for a small model.
openheronLocal-firstMulti-agent
Agent-as-tool multi-agent runtime
Every expert agent binds the model that suits it, while the parent agent only orchestrates and synthesises. Tokens are saved not by compressing prompts, but by drawing boundaries so content that should not cross does not cross — isolation is complete: an expert’s intermediate steps never enter any turn of the parent’s context.
Named after the heron: standing still for a long time, striking with precision in an instant.
$ openheron [main] config loaded: version=3f2a1b9c8d0e [main] frontend: embedded from web/dist > show me the top-level directories of this repo …
How it saves
Three mechanisms deliver the token saving
There are three ways to save tokens. openheron takes the third.
Tools are isolation
An expert agent is called as a bounded capability: its own tool loop and intermediate reasoning stay in its context, and the parent receives only the structured summary it wrote.
Structure is savings
Boundaries keep content from crossing — isolation is complete: an expert’s intermediate steps never enter any turn of the parent’s context.
Boundaries
Stating the boundaries up front is cheaper than explaining them afterwards
The token saving is largest on tasks that are decomposable with verbose tool output; on strongly order-dependent tasks a single agent may be faster and more accurate.
"41% cheaper" is a measured figure from openheron’s own benchmark: on three coding tasks with one price table, the multi-agent topology cost 0.587× what one strong model spent on the same work; in that sweep it passed 6 of 9 (the baseline passed 9 of 9, two of the failures being endpoint timeouts) — cost and reliability have to be read together.
"High performance" means useful output per token; it promises neither zero latency nor unlimited concurrency.
Expert-models-only pays off when the pairing is right: the factory configuration has two agents sharing one model. A wrong model pairing wastes more than no pairing.
Observability is equally complete: the expert’s reasoning and tool calls appear live in the interface (with attribution) and stay in the record.
Rules
The failure modes of multi-agent runtimes, turned into hard rules
Ambiguity about who may do what is the most common way multi-agent systems go wrong. These constraints hold from the factory configuration.
- 01
Tool permissions have two layers and are never merged
The outer policy/permissions.yaml sets the global ask/deny, and each inner agent narrows it with its own disabled_tools. The outer deny beats the inner one, and a sub agent cannot relax it.
- 02
Delegation has a depth cap
The entry agent is level 0, and an agent at depth d may spawn children if and only if d < max_depth; a topology over the cap is a startup error, never a silent truncation.
- 03
One session can run several agents
Independent work is dispatched in parallel; usage is accounted per agent.
- 04
Configuration is files
Model profiles, prompts and approval policy are files you can read and edit: review them, commit them — all local, visible only to you.
- 05
One binary, runs anywhere
The frontend is embedded into a single file, compiled statically across platforms, with no extra runtime dependencies.
Architecture
Architecture
A message travels from you to the toolbox through only a few layers, and the activity comes back along the event stream. What happens between layers is mostly none of your business — only "does this need your nod" is.
YouChat, approve and attach in the browser
Request
Interface layerOne resident run line per session · streamed events
Orchestrate
RuntimeMulti-turn, one turn at a time, resumable from checkpoints
Assemble
agentPrompt · model · tools · sub agents
Call
Read codeSearch, trace call chains
Edit files · run commandsNeeds your nod first
Delegate to sub agentsIn parallel or in series
Search the knowledge baseWith source citations
Event stream back to the browser
Actions that need your nodWhen the run reaches an action like "edit files · run commands", it stops on the spot and an approval card appears: approve and it resumes from the checkpoint, reject with or without a reason — a reason is sent back so the agent can take another route.
Human in the loop
When it wants to act, it stops and asks first
When an agent calls a tool marked ask, the turn stops and an approval card takes over the input box. Approve and it resumes from the checkpoint; reject with or without a reason — a reason is sent back to the model.
- Three tiers: allow passes through / ask needs your nod / deny is unavailable
- Precedence: deny → ask → fall back to allow
- The outer deny is global — a sub agent cannot relax it
This is the real approval card — go ahead and click it.
Approval model details →You
Change the port in internal/config.go to 9090
coder
Let me confirm the current implementation first.
read_fileinternal/config.go✓
⚠
Approval required
The agent is paused until you respond.
write_file
/your/project/internal/config.gocoder
✓ Approved · resumed from the checkpoint
write_fileinternal/config.go✓
The port is now 9090, the rest of the config is untouched.
coder
✕ Rejected · the reason was sent back to the model
Understood, I will leave that port alone — it is managed centrally in config.yaml. Should I change it there instead?
Capabilities
Core capabilities
Not a one-question-one-answer chat window, but a multi-turn runtime that can be interrupted, resumed, and held up by approvals.
Multi-round persistent session
Each session is a resident run line you can pick up at any time; history is persisted and survives closing the browser.
Context compaction
The conversation is compacted into a summary at the agent’s threshold (80% of the window by default), or on demand with /compact. The context shrinks; the transcript stays readable.
One turn per session
A session runs one turn at a time; a send from another window is refused (409 session_busy) without disturbing the running turn — stop it to take over.
Abort
Stop the current turn immediately.
Human in the loop
Actions like writing files or running commands suspend before executing; once approved, the run resumes from a checkpoint.
Multi-agent delegation
A parent agent splits work among sub agents (read-only retrieval / coding / review), in parallel where independent.
Knowledge base
Index your own corpus; agents retrieve with kb_search and cite sources.
Hot configuration reload
Edit llm/, agents/, policy/ and save — it takes effect without a restart.
Graphical config editor
Edit configuration files in the interface, validated before writing.
Slash commands and skills
/review, /explain, /fix and more out of the box; skills are yours to define.
Multi-agent
Two agents from the start
openheron init writes the main and task agents — main references task via subagents: [task], and a missing one is a hard startup error, so they are always written together.
| Role | What it does | Writes files |
|---|---|---|
main | Only decides and delegates, never writes files itself | No |
task | Executes against the task order | Yes |
quickstart
# Build (frontend + a single binary with the UI embedded)
make build
# Generate a minimal runnable configuration in your project
cd /your/project && openheron init
# Secrets are read from the environment only (deepseek by default)
export DEEPSEEK_API_KEY=sk-...
# Start, then open http://localhost:8080
openheronManual
The full user manual
Ten chapters, reference as needed. Every chapter links straight to its sections.