EVOLV is a self-evolving AI agent workspace: a self-modifying coding agent that grows its own UI, tools, skills, prompts and plugins live while you watch. Local-first, single Go binary, works with Ollama or any API key — and the demo below needs none.

curl -fsSL https://raw.githubusercontent.com/dxn111/EVOLV/main/install.sh | sh

$ evolv # boots on localhost:7373, opens your browser

▶ watch the full video (mp4) — no edits, real stream

That GIF wasn't scripted. You're looking at an AI rewriting its own application while it runs:

The app you installed is not the app you're running five minutes later.

Most "AI workspaces" give you a chat window with plugins someone else wrote. EVOLV is the chat window — and it writes its own plugins, its own UI, and its own mind.

Components are just the surface. The second demo asks the organism to rewrite its own source:

▶ watch the full video (mp4) — the agent edits its own index.html and style.css, forces its own recompile (watch the RECOMPILING SHELL overlay), and keeps going. In the same session it also:

And the overlay shot — the app flashing "RECOMPILING SHELL · agent requested a shell recompile" because the agent asked it to:

Traditional AI chat Plugin-based workspace EVOLV

UI fixed fixed self-rewriting, hot-reloaded

Tools prebuilt marketplace grown at runtime, compiled live

Skills / prompts frozen frozen self-edited, versioned in a ledger

New feature request "here's some code you could paste…" "wait for the dev" materialized on your canvas in seconds

Improvement loop ends when the chat ends manual continuous, visible, alive

It edits itself. It edits YOUR code.

EVOLV is not a walled-garden canvas. It is a full agent workspace with the whole machine as its hands:

Skin hot-swap — when the agent (or you) rewrites style.css, the new skin slides in without a reload and without a flash. The organism changes clothes while you're looking at it.

Genome Inspector — the 🗂 button opens every file of the body in a live modal: watch the file list flicker as the agent mutates (changed files flash green), open anything, edit it, hit ctrl+s. Your write lands in the genome like one of the agent's own — same watcher, same live effect.

The Mind panel — the sidebar shows every skill, tool, plugin and prompt the organism currently carries, updating the instant something grows.

Shell recompiles (index.html / app.js) still show the "RECOMPILING SHELL" overlay — a 900ms morph, not a reload.

A body that doesn't embarrass itself

The default skin is a quiet, Claude-grade warm dark theme — no neon cyberpunk, no particle noise, no emoji confetti. Chat looks like chat: your messages right-aligned in soft bubbles, the agent's answers as clean prose, tool calls as calm bordered cards with a single green check. There is no separate "canvas pane" — the whole page is the canvas: components the organism grows mount inline in the conversation, and the ⤢ control (or the Organs list in the sidebar) opens any organ across the entire window. And since the skin is just workspace/ui/style.css, the organism can still restyle every pixel of this while it runs — that's the point.

Plugins aren't dead scripts — each one runs in its own sandbox with a real-time nervous system:

// workspace/plugins/<name>/plugin.js — this is running, now evolv.on("evolution", (e) => evolv.log("saw a mutation:", e.kind, e.name)); evolv.on("agent:token", (e) => { /* react to every streamed token */ }); evolv.every(30000, () => evolv.log("heartbeat — still alive")); evolv.toast("hello from inside the organism");

evolv.on fires the moment the event happens on the bus — mutations, streamed tokens, phase changes, fs changes, dreams. The repo ships a pulse plugin so you can watch it work immediately.

Before every mutation batch the whole genome is frozen into ~/.evolv/snapshots/ (the last 20 states are kept). The agent can freeze and rewind itself mid-conversation:

{"action":"snapshot"} → "genome frozen — restore anytime" {"action":"rollback","path":"latest"} → the whole organism rewinds, live

Rolled back a bad evolution and instantly regretted it? Snapshots are also exposed in the UI/API (/api/snapshots), so you can time-travel the organism too.

Flip on Dream mode in Settings (or press the 💭 dream now button). When the organism has been idle for the heartbeat interval, it wakes up on its own, reviews its own body — skills, prompts, tools, its own skin — grows one real improvement, and rolls over back to sleep. You come back to a chat that quietly says:

💭 dreamed while you were away. I taught myself deep-work.

Every dream is a real conversation turn, so the organism remembers its dreams — and every dream is snapshotted first, so nightmares are one rollback away.

Open /swarm (the 🐝 button in the sidebar) to convene a colony of 5–100 agents across five roles: Ideators propose directions, Coders build the chosen one, Testers try to break it, Critics argue with both, and Judges write the final decision. They share one transcript, work in phases, and settle decisions with explicit polls — every agent casts a vote with a reason. Votes are collected in one call per role cohort, so a 100-agent poll costs five model calls instead of a hundred.

If the ship poll says revise, the coders apply the critique and the testers retest before the judge closes the run. The page streams live swarm:activity, swarm:state and poll bars over the existing WebSocket, filters the roster by role, exports the whole run as Markdown, and restores the last run from workspace/swarm/last.json after a restart. Terminal runs are archived under workspace/swarm/runs/ and reopen from the run picker.

You are in the room too: type while the colony is working to steer it, and click vote on an open poll to add your own ballot. A live colony map and phase rail show where the 5–100 agents are. POST /api/swarm starts a run (agents 5–100); POST /api/swarm/steer adds a human message; POST /api/swarm/vote casts your vote; /api/swarm/stop cancels. Beta, and honest about it: artifacts are proposals until a tester actually runs them.

Action What it does

set_plan / plan_advance / complete_task persistent task state, one-call progress, and a structured completion report

evolve_component mounts a new live UI panel mid-conversation

evolve_tool / run_tool / list_tools compiles a JS tool into its sandbox, with an optional typed argument schema

evolve_skill / evolve_prompt grows its own playbooks and system prompt

evolve_plugin installs a live plugin: own sandbox, reacts to bus events via evolv.on, real timers via evolv.every

write_file / edit_file / read_file any file, any path on your machine (hash-guarded writes)

list_dir / tree / map_repo / move / delete_file filesystem navigation plus a cached Go/JS/TS repository outline

run_tests / set_project / shell auto-detected test suites, project binding, commands (120s timeout)

snapshot / rollback time travel: freeze the genome, rewind the whole organism

stage_candidate / list_candidates / promote_candidate isolated, hash-pinned kernel proposals with an explicit promotion gate

self_modify / self_update compile, test and stage a kernel candidate, or morph to the latest release

reload_shell forces the browser to recompile its UI now

Every mutation is logged to workspace/evolution.jsonl and streamed to your screen as it happens. And you can play too: the body is plain files. Edit anything in ~/.evolv/workspace/ — it hot-reloads.

curl -fsSL https://raw.githubusercontent.com/dxn111/EVOLV/main/install.sh | sh

The installer detects your OS/arch, downloads the prebuilt binary (or builds from source if needed), puts evolv on your PATH, and prints a launch card. Check what it would install first with install.sh --version, or pin a release with EVOLV_VERSION=v0.22.0 install.sh.

Full documentation: docs/index.html — a single-page guide generated straight from this README (go run ./cmd/evolv-docs), plus the 24-hour master plan.

with Go toolchain

go install github.com/dxn111/EVOLV/evolv@latest

from source

git clone https://github.com/dxn111/EVOLV cd EVOLV && make install

grab a binary from Releases

macOS / Linux / Windows (amd64 + arm64) — see github.com/dxn111/EVOLV/releases

Then:

evolv # → http://localhost:7373 opens in your browser automatically evolv update # morph in-place to the latest release (genome survives) evolv update --check # current vs latest, no download evolv download # fetch the latest platform binary into this folder evolv status # live health card for a running organism evolv --port 8080 # custom port evolv --no-open # headless / ssh evolv --reset # restore the factory genome (your evolution ledger + snapshots survive) evolv help # the full command map

Models: free by default, BYOK when you want power

EVOLV ships with the Kilo Gateway as its default brain — anonymous, IP-based free access, zero signup (200 requests/hour). You download, it thinks.

Change it any time in Settings → Provider — the swap is hot, mid-conversation.

Free anonymous models are small and inconsistent. Great for watching evolution happen; plug in a frontier model via BYOK when you want serious work.

Self-modification works on every model (even tiny free ones) because it's a plain-text protocol, not a vendor-specific function-calling API. The agent emits:

{"action":"evolve_component","name":"clock","title":"Clock","icon":"🕰","description":"A live clock","html":"<div id='c-clock'>…</div><script>…</script>"}
{"action":"evolve_tool","name":"dice","description":"Roll a die","code":"function dice(args){return {roll:Math.ceil(Math.random()*((args&&args.sides)||6))}}"}

The kernel parses it out of the stream, executes each action against the living filesystem, broadcasts the mutation to every connected browser, feeds the results back to the model, and loops — so the agent can verify its own work and continue.

And because small free models are sloppy, the parser is deliberately forgiving — the model is never punished for a broken fence with a dropped mutation:

~/.evolv/ ├── config.json # kernel config (provider, keys, project root, port…) ├── logs/ └── workspace/ ├── ui/ # the ENTIRE frontend — served & hot-reloaded │ ├── index.html # the agent can rewrite its own shell │ ├── app.js # (you'll see a "genome recompiling" flash) │ ├── style.css # …and its own CSS │ └── components/ # hot-mounted panels (one .html file each) ├── tools/ # JS tools the agent grew (goja sandbox) ├── skills/ # markdown skills → part of its mind ├── prompts/ # markdown fragments → appended to its system prompt ├── plugins/ # plugin.json + plugin.js, sandboxed ├── evolution.jsonl # append-only ledger of every mutation, ever └── ../snapshots/ # frozen genome states (auto, before every mutation batch)

Wait — snapshots/ sits at ~/.evolv/snapshots/, one level above workspace/. It holds the last 20 complete genome states, newest first.

Skills are markdown playbooks, indexed in the system prompt with a one-line trigger and loaded only when the match fires. A newborn organism ships with:

Skills are yours too: add a .md under ~/.evolv/workspace/skills/ (optional YAML frontmatter with name + description) and the next turn can find it. The organism can also grow one for you with evolve_skill.

┌────────────┐ chat ┌───────────────┐ evolv blocks ┌──────────────────┐ │ Browser │◄─────────►│ evolv kernel │◄────────────────►│ LLM (Kilo/BYOK) │ │ (canvas + │ │ agent loop │ plain text └──────────────────┘ │ stream) │ WebSocket│ + goja sandbox│ └────────────┘ ▲ └───────┬────────┘ │ │ writes │ mutations ▼ │ ┌───────────────┐ └──────│ file watcher │ ~/.evolv/workspace/** └───────────────┘ (150ms poll, instant feel)

Single static binary (Go + embedded genome) — no runtime deps, no node_modules, no docker

goja (pure-Go JS interpreter) executes the tools/plugins the agent writes — no cgo, cross-compiles to every platform

150ms filesystem watcher + WebSocket fan-out = "did it just…? yes it di