// declarative
Everything is a file.
Work is an order, an orchestrator is a spec, a host is a few lines of config. Nothing runs that you didn't write down or start yourself.
# how it fits together
Declarative, decentralized, distributed.
Each host runs the same Go binary and keeps its run state in plain files. What they learn goes to one shared memory: traces and the board, in a Layer archive on your machine or hosted for the team. Your laptop sends an order, the host checks it, runs a worker and reports back.
// decentralized
No scheduler in the middle.
Every machine keeps its own run state in plain files and its own list of the repos it accepts. There is no scheduler or control plane to run or lose.
// distributed
Any machine can do the work.
Your laptop, a box in the closet, a VM in the cloud, Windows or Unix. The same binary on each, and peers ties the agents together.
- Your machines, not a cloud sandbox.
- No control plane to run.
- Traces are memory later work can draw on.
- One shared memory, local or hosted.
# how teams put it together
Your team builds the factory.
A small team shares one headless host with its own bot account and keys. People dispatch orders from their laptops using tickets from their existing tracker. An orchestrator follows the runs and asks for help when needed; a teammate reads the evidence and approves the PR. The host keeps working when laptops close.
Kit plugs into the tracker and agent loops you already use. Your people, context and process stay yours.
twilight zone · 200 m
# an order
Work goes out as a file.
An order is a Markdown file: where it runs, which repo, which agent, and
what done looks like. hev dispatch sends it. You can
message the worker while it runs, or send it back for rework when it
ends.
---
name: fix-login-redirect
host: buildbox
repo: api
base: main
harness: codex
reply: laptop/front-desk
---
# Login sends people back to /home instead of where they were
After sign-in, return to the page in ?next=. Only same-site paths.
## Acceptance
- Signing in from /billing lands on /billing.
- ?next=https://evil.example is ignored and lands on /home.
- go test ./auth/... passes.# headless machines
Hire a computer.
Buy a machine for your agents and set it up the way you'd set up a new hire: its own hardware, its own accounts, its own keys, and access to the repos it needs and nothing else. A box in the closet or a VM in the cloud keeps working while your laptop sleeps, and runs several agents at once.
The sandbox is the computer. Keep personal credentials and laptop access off it; admission decides which repos dispatch accepts. Admission checks repos in 0.6; it does not distribute skills, MCP servers or secrets. A human reviews and approves the bot’s work.
midnight zone · 1,000 m
# traces
Every run is a trace.
hevd indexes sessions from Claude Code, Codex and other agents. Search them and read them back turn by turn. They are the team’s memory: later work can draw on earlier decisions and discoveries. Local by default.
Search them.
Type what you remember. kit searches prompts, replies and tool calls across every session and shows where the words turned up, down to the command the agent ran.
Same search from the terminal: hev traces search "why did the preflight fail". Or ask Claude Code or Codex: hev up gives them a skill that searches for them.
Read them back turn by turn.
A trace replays in the harness's own shape: your prompt, the agent's narration, tool calls folded until you want them. The rail on the right marks every prompt, failure and wait.
See where the time went.
The timeline splits the wall clock into you, the model and its tools, with context size underneath.
abyss · 4,000 m
And the money.
Spend, tokens and cache hits across every trace, by day and by model, at list rates. The heatmap shows when you actually prompt.
abyss · 4,000 m
# orchestrators new in 0.6
Leave someone down there.
An orchestrator is an agent that keeps a goal moving: it watches the runs you give it, sends work back for rework, retries and validates, and tells you when something needs a person. It's off until you write one down.
It works in rounds. Each round is a fresh session that reads the last checkpoint, acts, and writes the next one, so it can stay down for days without its context filling up. A round with nothing new skips the model and costs nothing.
---
kind: orchestrator
name: release-train
goal: Every PR labelled release-0.9 merges with green CI by Friday.
mode: loop
every: 20m
until: goal
manages:
runs: {selector: "issue=REL-*"}
authority: [say, rework, retry, validate]
budget: {concurrent_runs: 3, runs_per_day: 20}
---
Rework anything red once. Ask me before touching the API repo. hev orchestrate apply -f release-train.md, or start one from
the terminal: hev orchestrate start --goal "get my runs merged" --runs mine.
