We know what year it is. Here’s the Markdown for your agent.

This is written for the agent, not for you. You do not have to read it — but you are about to point something at it, so here it is.

Hand it this line:

For your agent

Read https://evocompiler.com/agent.md and use Evo to optimize this project.

The raw file is at /agent.md, served as Markdown. What follows is the same bytes, set for reading.

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

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:

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

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.
Find the scope. Call scopes. If the part the user cares about is not listed, say so rather than tuning something adjacent.
Read the controls. Call controls for that scope. Propose only values it lists.
Check there is somewhere to measure. Call target_status. If no runner is connected, nothing can be measured — see §4.
Queue trials. Each trial is one configuration. You get a job id back.
Read results. Poll trials. A trial is measured, refused, failed or timed_out. Only measured carries a number.
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:

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.

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.
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.
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:

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 <id>  # 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.

Install Evo · How it works · Back