# Eukhe > Eukhe is an agent harness that works a task with no person watching, counts it done only when the user's checks pass on the final code, and gives a report at the end. ## What it is Eukhe is εὐχή, Greek for wish. You write the wish as rules in `AGENTS.md`, as a goal and as commands that must pass. When one of those commands fails, Eukhe gives its output to the agent and runs another turn, until every command passes or the run reaches a limit. A session is an append-only log on disk, so it survives a crash and `eukhe --continue` reopens it. The `eukhe` command runs a coding agent on Eukhe's core in your terminal. The `eukhe-sdk` Rust crate runs sessions on it inside your own process. ## Wish - Eukhe reads `AGENTS.md` in the project and puts it in the system prompt. - `eukhe --goal "objective"` keeps running turns until the goal completes (with acceptance checks: when they all pass) or its responses reach `--goal-token-budget` tokens; the agent then wraps up and the run ends at its next final answer. - `eukhe --autonomous --autonomous-gate "cargo test"` runs `cargo test` after each turn and runs another turn while it fails, up to the limits that `eukhe --help` lists. ## Laws [spec/README.md](https://eukhe.com/spec/README.md) numbers the requirements. A law is a theorem that the core, the part of Eukhe written in [Bend](https://bend-lang.com), meets one of those requirements. `PROOF.bend` holds a proof of every law, and `bend PROOF.bend` checks them. The proofs cover the Bend core and say nothing about what the model writes. ## SDK [`eukhe-sdk`](https://eukhe.com/crates/eukhe-sdk/) is a Rust crate that runs sessions inside your process. [`eukhe-client`](https://eukhe.com/crates/eukhe-client/) is a Rust crate that connects to the Eukhe daemon over its socket. A program in any language starts `eukhe --mode ` and talks to it over stdio. The crates are not on crates.io. Their API may change with any release. ## Components [Durable](https://eukhe.com/spec/durable/), [Memory](https://eukhe.com/spec/memory/), [RLM](https://eukhe.com/spec/rlm/) and [Autoresearch](https://eukhe.com/spec/autoresearch/) have requirements and laws. Loop, the code behind `--autonomous` and `--goal`, has no requirements, spec files or laws yet. Planned and not built: confinement of the programs the agent runs, checks the agent never sees, review of the process for gaming, capability security, replayable record, orchestration at scale, stable SDK contract. ## Install `curl -fsSL https://eukhe.com/install | sh` on macOS (Apple Silicon) or Linux (x64, arm64). With Nix: `nix run github:gildrb/eukhe`. Eukhe does not run on Windows. It runs model-written Python and shell with the user's permissions and has no sandbox: use it in trusted repositories only. ## How to read this site - [Home page as Markdown](https://eukhe.com/index.md) (also `Accept: text/markdown` on https://eukhe.com/): Eukhe's README, with the site's epigraphs - [About](https://eukhe.com/about.md), [Contact](https://eukhe.com/contact.md), [Privacy](https://eukhe.com/privacy.md) - [Source](https://github.com/gildrb/eukhe), MIT license ## The home page # Eukhe Source: [https://github.com/gildrb/eukhe](https://github.com/gildrb/eukhe) > μὴ παντάπασιν ἡμᾶς εὐχὰς εἰρηκέναι, ἀλλὰ χαλεπὰ μέν, δυνατὰ δέ πῃ. > That we have not spoken mere wishes, but things hard, yet somehow possible. (Plato, Republic 7.540d) Eukhe is an agent harness that works a task with no person watching, counts it done only when the user's checks pass on the final code, and gives a report at the end. ## Install ```sh # macOS (Apple Silicon), Linux (x64, arm64) curl -fsSL https://eukhe.com/install | sh ``` ## Use ```sh cd project # start; /login at the first start eukhe # script; exit 0 only when all checks pass eukhe -p --accept-cmd 'npm test' "fix the failing tests" ``` In a session, `/accept cmd --protect tests/app.test.js npm test` sets a check. Then type the task. `eukhe --help` shows all commands. ## Checks

Task: "sort the list"
Sixteen bars sort in four rounds; the agent says done; the check fills each bar blue from left to right: checks passed
The agent says done. The check passes.

Next task: "make the sort faster"
The faster sort takes two rounds and leaves two bars swapped; the agent says done; the check stops red at the pair; the agent swaps them back
Two values are out of order. The task goes back to the agent.

Before a pass counts:
Eukhe drops the last merge round on purpose; the check stops red where the two halves meet; the break is undone and the check passes
Eukhe breaks the code on purpose. The check finds the break.

The agent cannot set, change, skip or remove a check. A check that finds less than 80 % of the breaks is weak, and the task ends `checks passed, not certified`. After 3 failed checks in sequence, the task ends `failed`. When every check finds enough breaks, up to two attackers each write a version of a changed file that they claim is wrong, and a command that shows it wrong. An attacker is a model request that does not see the agent's reasoning or answer. When such a version passes every check, its command shows it wrong and a separate model request agrees, the task ends `checks passed, not certified`. ## Limits

A $5 budget with $1 kept for the report; each round reserves its cost, spends, frees the rest; the third round would need the kept money and does not start; the report says two rounds done, two left
/budget set cost=5 time=2h: a step that needs the money kept for the report does not start.

Each step reserves its maximum cost before it starts. The report gives the work done, the work not done and the limit that stopped it. ## Models When a model cannot continue because its retries are used up, its login expired or its usage limit is reached, the run continues with another model that the user configured and is logged in to. Eukhe shows each change. When no model is left and the provider reports when its usage limit resets, the run waits for the reset; a script run stops at its wait limit and leaves the session waiting. Any other failure ends the run with its report. ## Crash recovery

The run stops in the middle of a round; it starts again with the completed rounds in place; the interrupted round runs again; the check passes
After a crash, completed steps stay complete. An interrupted step runs again when that is safe.

Eukhe settles an interrupted step from its evidence: the file content, the git ref or the job exit. A step that is not safe to repeat is recorded as not run, and the run continues. `/effects` shows these steps. ## Parallel work

The agent gives each half of the list to a child; both children sort their half at the same time; the halves come back and the agent merges them; the check passes
Two child agents each sort one half at the same time. The parent agent merges the halves.

Each child works on its own files in its own copy. A parent can set the checks of a child. ## Report At the end, one report gives the agent's final answer and the result of each check. **Target:** each step runs without a question in the terminal, the browser, the phone and a script; one message at the end lists each irreversible effect. **Status:** being built. **Target:** `/undo` puts the files back to their state before a prompt and names the irreversible effects that it cannot undo. **Status:** being built. ## Limitations > ἃ μὴ οἶδα οὐδὲ οἴομαι εἰδέναι. > What I do not know, I do not think I know either. (Plato, Apology 21d) There is no sandbox. Code that the agent runs has the user's permissions and can change the files that a check reads; a check fails on a change only to its `--protect` files. A check that finds the breaks can pass on wrong code that is not similar to a break and that no attacker writes, for example a hard-coded answer. A model request that a crash interrupts is not sent again, and its reserved cost stays counted until its usage is known. A limit that is not set has no maximum. ## Credits Eukhe is a fork of Prime Intellect's [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent), built on Mario Zechner's [pi](https://github.com/earendil-works/pi). The memory design is Victor Taelin's [OptChat](https://gist.github.com/VictorTaelin/91837951a5ce5b38f341ec1ba1df6449) and [OptMem](https://github.com/VictorTaelin/OptMem). The edit tools, the tokenizers and the harness design come from [oh-my-pi](https://github.com/can1357/oh-my-pi), and the Claude tokenizer vocabulary from Sander Land's [ctok](https://github.com/sanderland/ctok). Made by [Gil Rodrigues](https://gildrb.com). Notices: [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES). ## License Apache-2.0. See [LICENSE](LICENSE). Source: [https://github.com/gildrb/eukhe](https://github.com/gildrb/eukhe)