# Evo, for agents You are a coding agent. This page is written for you, not for the person you are working with. They do not need to read it. The canonical copy of this file is https://evocompiler.com/agent.md. Re-read it rather than remembering it; it changes when the product does. Evo makes a program faster on the machine it will actually run on, by choosing compilation settings for one scope of one project and **measuring** each choice on that machine. It keeps what measured faster and discards what did not. If you take one thing from this page: **Evo never tells you something is faster. It tells you what it measured.** Every number you get back came from running the user's code. Nothing here is a model's estimate. --- ## 1. Check that Evo is available ```bash evolve --version # the management CLI evocc --version # the compiler driver, gcc-shaped evolve auth status # who this machine is signed in as ``` If `evolve` is not found, the user has not installed Evo. Tell them to run: ```bash curl -fsSL --proto '=https' --proto-redir '=https' https://api.evocompiler.com/install.sh | sh ``` That one command installs both binaries, signs them in, and connects Evo to the coding agents on the machine — including you. It is safe to run again. If `evolve auth status` says the machine is not signed in, run `evolve setup`. It opens a browser. Do not try to authenticate on the user's behalf any other way, and never ask them to paste a token to you. --- ## 2. What you have One tool, over HTTP MCP at `https://mcp.evocompiler.com/mcp`: ``` evo_region(action, project_id, arguments?, idempotency_key?) ``` `account_id` is derived from the credential, never from your arguments. You cannot name another account's project, because the field you would have to set is not one you supply. ### Actions | Action | What it does | | --- | --- | | `projects` | List the projects on this account. | | `project_create` | Create a project. Safe to call twice for the same repository — it returns the existing one. | | `scopes` | List the scopes in a project. A scope is a named part of the program you can tune independently. | | `controls` | The compilation control parameters you may set for a scope, with each one's legal values and what it emits. **Fetch this before proposing anything** — it is per compiler family, and guessing produces refusals. | | `policies` | The constraints in force for this project. | | `target_status` | Whether a runner is connected and able to measure. | | `trial` | Queue one measured configuration. Returns a job id; it does **not** return a measurement. | | `trials` | Read back what has been measured. This is where results appear. | | `diagnostics` | Why something refused. | | `freeze_version` | Freeze what measured best into a versioned artifact. | | `versions` / `select_version` | List and choose frozen versions. | | `query_reuse` | Ask whether existing work applies here. | The action set is closed. An action outside it is refused, not attempted. --- ## 3. The shape of a session ``` project -> scopes -> controls -> trial (queue) -> trials (read) -> freeze_version ``` 1. **Find or make the project.** Call `projects`. If none matches this repository, call `project_create`. Do not ask the user for a project id — you have the repository, which is what identifies it. A project is a *reuse boundary*, not a source tree: it does not own the user's checkout. 2. **Find the scope.** Call `scopes`. If the part the user cares about is not listed, say so rather than tuning something adjacent. 3. **Read the controls.** Call `controls` for that scope. Propose only values it lists. 4. **Check there is somewhere to measure.** Call `target_status`. If no runner is connected, nothing can be measured — see §4. 5. **Queue trials.** Each `trial` is one configuration. You get a job id back. 6. **Read results.** Poll `trials`. A trial is `measured`, `refused`, `failed` or `timed_out`. Only `measured` carries a number. 7. **Freeze**, if the user wants to keep the result. ### Do not - Do not report a speedup you did not read out of `trials`. - Do not add region wins together to produce a whole-program number. If you do not have an end-to-end measurement, say `unmeasured`. It is a real value, not a zero. - Do not describe a measured result as proved, verified, or guaranteed. It is evidence about one run on one machine. - Do not retry a refusal without reading `diagnostics` first. Refusals carry their reason and are usually telling you something specific. --- ## 4. Where measurement happens Evo does not run the user's code. **A runner on the user's own machine does.** ``` you -> hosted MCP -> queue -> the user's runner -> their target -> result ``` - A **target** is where a measurement runs: the same Mac or Linux box, or a board over USB, or a simulator. - An **adapter** is a small program *the user owns* that knows how to build their code, run it, check it, and report a number. - A **runner** is the local process that claims queued trials and executes them. If `target_status` says nothing is connected, the user needs a runner. For the common case — measuring on the machine they are already sitting at — this is one command and you may run it for them: ```bash evolve setup measure # scaffolds a host-local target and starts a runner ``` For anything else, **ask one concrete question rather than teaching them Evo's architecture.** Good questions: > What command do you normally use to benchmark this? > Should this run on this Mac, or on the board plugged into it? > How do I tell whether a run produced the right answer? Bad question: anything that requires them to know what an adapter is. ### The adapter is their code, and it must check correctness The scaffolded adapter has a step where the user's own check goes — their test suite, a golden-output comparison, whatever they already trust. **A trial that does not check correctness measures whether the wrong answer arrives sooner.** If the user has no check, say that plainly and help them write one before tuning. This is the one place where slowing down is right. An adapter is arbitrary code running with the user's permissions. Registering one says *this project may execute it*. That is a coherence boundary, not a safety check. Do not tell the user it has been validated as safe, because it has not been. --- ## 5. Hardware If the target is a physical board, three things are true and none of them are negotiable. 1. **The board runs the user's code many times, in orders and timings nobody chose.** It must be disconnected from anything it could drive before a run starts. Say this before the first hardware run, every time — not once. 2. **You may prepare a hardware run. You may not start one.** Evo will disclose the exact command and stop. The user runs it in their own terminal. Do not work around this, and do not present it as a bug. 3. **A measurement is about that board, that day.** Numbers from a host-local target do not transfer to a board, and numbers from one board do not transfer to another. --- ## 6. What is true today **Works.** Sign-up and browser sign-in. Automatic agent connection. Projects. Scopes and control catalogues. Queued trials against a connected runner, measured and read back. Freezing a version. `evocc` as a `gcc`-shaped driver resolving a project's `.evolve/` directory. **Limits, stated plainly.** - The tuning surface is **compilation control parameters over a scope**. Evo chooses settings and measures them. It does not rewrite the user's source. - Measurement needs a runner the user is running. There is no cloud fleet. - One tool, one action set. If you want something outside it, it does not exist yet — say so rather than approximating. - A frozen version is tuned for the program it was measured on. How much survives on a different program is a question only measurement answers. - If nothing beats the user's ordinary build, the ordinary build is the answer. That is a normal, correct outcome. Report it as one. --- ## 7. When something goes wrong | What you see | What it means | What to do | | --- | --- | --- | | The tool is not listed at all | Evo is not connected to this client | Have the user run `evolve setup` | | `unauthorized` | The machine is signed out, or the connection was revoked | `evolve setup` — it re-authenticates | | No project matches this repo | Normal on the first run | `project_create` | | `target_status` reports nothing connected | No runner | `evolve setup measure`, or ask where they want to measure | | A trial is `refused` | A control value or a policy | Call `diagnostics` and read the reason before changing anything | | A trial is `failed` | Their build or their check failed | Show them the adapter's output. This is usually their code, not Evo | | `timed_out` | The runner stopped, or the workload does not terminate | Check the runner is still up | The user's own escape hatches, if you need to hand them one: ```bash evolve setup # fix whatever is missing, safe to re-run evolve auth status # who this machine is evolve auth logout # end the session; connected agents keep working evolve mcp connections # what is connected to this account evolve mcp revoke # disconnect one agent ``` --- ## 8. Rules - Never print, log, echo, or send a credential — not to the user, not to a file, not into a commit. You do not need to see one; the connection is already made. - Never modify the user's MCP configuration by hand. `evolve setup` owns it. - Never start a hardware run. Prepare it and hand it over. - Never claim a number you did not read from `trials`. - Never call a measurement a proof. - If the user asks for something Evo cannot do, say so in one sentence and stop. Do not build a workaround that produces a number nobody measured.