If you’ve got a project and you want a coding agent (an AI tool that writes code changes) working on it safely, this page is for you. You’ve watched the demo. Now for your own code. This page takes you from nothing to an agent working on a goal in your project, and it’s mostly one command and one “yes”.
1. Start Evolve
If you haven’t yet, start Evolve on your machine: make up in the folder you downloaded it to (see Run the demo). Then put bin/evolve, Evolve’s command, on your path so your terminal can find it, and run source .evolve/env so the command can reach Evolve’s server.
2. Let it read your project
In your project’s directory:
evolve init
Evolve reads the project and suggests how to judge it, as numbered lines. It’s working out the policy: the rules every change to this project will be judged by.
Evolve would set up shortener:
1 name shortener
2· project the repository's top level, on branch trunk
3· language go (go.mod)
4 service ./cmd/shortener (serves HTTP)
5 build go build -o {{output}} ./cmd/shortener
6 start -addr 127.0.0.1:{{port}}
7 health /healthz
8 tests go test ./...
9 protected evolve.yaml, verification/, go.mod, go.sum, vendor/; existing **/*_test.go
10 latency p95 of GET /healthz under load, at most 500 ms
11 deploy none: verify only (add an environment later)
12 commit yes: commit evolve.yaml and verification/ to the current branch
What it works out:
- The service: the program that answers web requests (HTTP), how to build it, how it’s told which port to listen on (a flag or
$PORT; a port is the numbered door requests come in through), and which address says it’s up and running. - The tests, which become a trusted check: a test that runs on every change, which agents can’t alter.
- What agents must never touch: your dependencies (the other people’s code your project uses), and Evolve’s own policy and checks. Your tests that already exist are on the list too (that’s the
existingpart), though agents may add new tests for what they build. An agent that could edit those could pass anything. - A speed check, which is what gets tightened when you ask for something faster.
If it can’t work something out, it says so under the list.
3. Change anything, then say yes
Don’t like a line? Type its number to change it, or give the changes on the command line:
evolve init 8 "make test" 10 200
Say yes, and Evolve writes the policy to evolve.yaml and its checks to verification/, commits exactly those files (saves them into your Git history), and registers the project with Evolve’s server. Want to read the files first? evolve init --plan writes them and stops. In a hurry? --yes accepts without asking.
Not a Go service? That’s fine. Your tests still become a trusted check, run with your project’s own tools, its toolchain. evolve init writes toolchain: node, python or rust into evolve.yaml for you. A project whose tests run with make test gets toolchain: none: only the basic system programs (the ones in /usr/bin and /bin) are there when its checks run, so whatever else the tests need has to be in the repository. Evolve judges the agents’ changes and you merge them into your code. Putting changes live in production is only for services that build into one program file, today.
4. Give an agent a goal
Just say it in a sentence, in your project’s directory:
evolve run "make link lookups respond in under 50 ms"
Evolve turns that into a goal it can check, and shows you before anything starts:
goal make link lookups respond in under 50 ms
target p95_ms at most 50 ms (check "latency")
measured on GET /healthz (verification/load.yaml)
↳ only the health check: point the load profile at the requests this goal is about
must pass build, tests, contract
policy tighten check "latency" from 500 to 50 ms, and commit evolve.yaml
agent claude-code
Notice the policy line. If your goal is stricter than the project’s trusted speed check, the only way to hold an agent to it is to tighten the check. So Evolve offers that as a line of its own, and commits it only if you say yes.
A goal without a number works too. evolve run "add an expiry to short links" keeps the speed check as a guard, and the other checks as things that must keep passing. When you want a goal written out in full, see goals.
If every agent leaves the code as it was, the run says so. The goal may already be met, and evolve run show has their reasons.
Where the run ends depends on whether there’s somewhere to deliver to:
- Nowhere yet? The run ends verified. The chosen change passed every check, and the run tells you the
git pullcommand that merges it into your code. - Got an environment, a place Evolve can put the change live? A new agent starts supervised, so the chosen change waits for your approval. Read the evidence on the run’s page or with
evolve run show <run>, then approve it there, or withevolve run approve <run>. After a streak of clean promotions (changes that went live and stayed healthy) it ships by itself (earned autonomy).
When you want more say
Everything evolve init decided is in evolve.yaml, with comments, and you can change every line: more checks, stricter limits, a canary (trying a change on a small share of real traffic first) with your own steps, or an A/B experiment (comparing the new and old versions on real users). The policy file lists every setting.
The checks it names live in verification/. Two worth doing early: add the requests your users make most to verification/contract.yaml (the list of requests and the answers they must get), and point verification/load.yaml (the speed test) at a real address in your service before you set speed goals.
Starting from nothing instead? See A new project, from nothing.
To put changes live, whoever runs Evolve (the operator) adds an environment to the operator config, Evolve’s own settings file. Where it runs explains the choices. Then you set line 11, or the deployment section of evolve.yaml, to it.