---

What you just watched

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

1. A human asked for a pomodoro timer.
2. The agent didn't paste code back. It wrote a real component into its own source tree (~/.evolv/workspace/ui/components/pomodoro.html) and logged the change in an append-only evolution ledger.
3. A filesystem watcher caught the write the instant it happened and pushed it over WebSocket — the new panel appeared in the conversation itself, with no refresh, no rebuild, no restart.
4. Then it grew a playable Flappy Bird the same way. The whole page is the canvas — every component mounts inline where it was born, and any organ can be opened across the entire window from the sidebar.

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.

Part 2: it edits its own codebase — and you see it in real time

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:

• grew a Prompt Library button — template cards that drop into the composer — plus the skill for using it (one batch, two mutations);
• installed ghost-log, a live plugin in its own sandbox that pops a toast every time the organism mutates;
• grew a playable Flappy Bird onto its canvas. A video game, written by the app into itself, live:

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

More views of the organism

---

Why this is different

	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:

• Own body, every byte. Its chat shell, its CSS skin, its tool call cards, its front-brain JS, its panels — all plain files it rewrites live. Say "make your tool call cards look exactly like Claude's" and it opens its own style.css, rewrites the card section, reloads its shell — and the new skin lands in under a second, no refresh.
• Even the launcher. If the EVOLV source tree is on the machine, it detects it and can read and edit its own Go kernel (cmd/, internal/) — the code that runs it. Then go build ./cmd/evolv. A program that patches its own bootloader.
• Your projects. Point it at any folder ("work on the project at ~/my-app", or set_project): it reads, edits, runs tests and ships code there like any serious coding agent — while still being the workspace it lives in.

Zero refresh. Ever. You see every change as it happens.

• 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 that are actually alive

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.

Time travel: every state of the organism is kept

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.

Dream mode: it evolves itself while you're away

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.

The full action list

Action	What it does
evolve_component	mounts a new live UI panel mid-conversation
evolve_tool	compiles a JS tool into its sandbox and calls it
evolve_skill / evolve_prompt	grows its own memory 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
list_dir / tree / map_repo / move / delete_file	filesystem navigation plus a cached Go/JS/TS repository outline
set_project / shell	binds your project root, runs commands (120s timeout)
snapshot / rollback	time travel: freeze the genome, rewind the whole organism
reload_shell	forces the browser to recompile its UI now
self_update	morphs itself to the latest released binary mid-chat

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.

---

Install

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.

Other ways in

# 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 --port 8080 # custom port
evolv --no-open   # headless / ssh
evolv --reset     # restore the factory genome (your evolution ledger + snapshots survive)

---

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.

Provider	Key needed	Notes
Kilo Gateway (default)	none	kilo-auto/free rotates the live free-model pool for you
Kilo Gateway + BYOK	kilo	unlocks kilo-auto/frontier, Claude, GPT, GLM, Kimi, Qwen, Grok, DeepSeek…
OpenAI	openai	any OpenAI-compatible endpoint via custom base URL
Anthropic	anthropic	native Messages API
OpenRouter	openrouter	hundreds of models, one key
Groq	groq	absurdly fast
Ollama	none (local)	your machine, your weights, your rules
Custom	custom	any OpenAI-compatible URL
Mock	none	offline evolution demo — mutates with no brain at all

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.

---

The evolv protocol

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:

```evolv
{"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:

• a fence left unterminated (the model streams past the closing ```) still executes;
• raw {"action":…} JSON leaked into chat prose — no fence at all — is salvaged and executed, and the UI renders it as a clean tool card instead of garbage;
• objects separated by }{, trailing junk, braces inside strings — all handled by a string-aware brace scanner;
• the prompt hard-chains the loop: read → edit → test → next batch, never one tool call and a shrug.

Genome layout

~/.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.

Under the hood

┌────────────┐   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 did"
• Per-plugin goja sandboxes with a live event bus (evolv.on / evolv.every) — plugins react while the organism thinks
• Everything local. Nothing phones home except the model provider you choose.

---

It updates itself too

The kernel polls GitHub Releases at boot and every 6 hours. When a newer version exists, a live banner drops into every open browser — a program telling you it can become a better version of itself, mid-session:

🧬 a newer organism exists: v0.3.0 — [morph now]

Click morph now (or run evolv update) and the latest binary is downloaded and swapped over the running one. Your genome — every evolution it ever made — survives untouched. Restart once and the new body is live.

---

Security (read this)

EVOLV is a self-modifying agent running on your machine — that's the entire point, and it comes with real teeth:

• The agent can run shell commands and read/write any file on the machine — that's what makes it a real workspace, not a toy. It binds to 127.0.0.1, and the browser UI only exposes what the kernel serves.
• Free anonymous models may route through providers that log prompts — don't paste secrets into demo-tier chats.
• evolv --reset restores the factory genome if an evolution goes feral.

Treat it like a very eager intern with root: brilliant, fun, supervise accordingly.

---

Roadmap

• Ambient heartbeat — shipped in v0.4.0 as Dream Mode (idle → autonomous self-evolution)
• Evolution branching — shipped in v0.4.0 as snapshots + rollback (time travel through genome states)
• Memory that survives restarts — shipped in v0.7.0 (conversation persisted atomically)
• Network reach — shipped in v0.7.0 (evolv.http() inside tools and plugins)
• The whole page is the canvas — shipped in v0.10.0 (organs mount inline in the conversation, open full-window from the sidebar)
• A shell that doesn't embarrass itself — shipped in v0.8.0 (markdown rendering, copy buttons, streaming caret, welcome screen, genome file deletion)
• Component marketplace — export / import genomes as .evolvpack files
• Multi-organism mode — agents that evolve together
• Vision — components that can see (canvas screenshots as tool input)
• Voice

Changelog (the organism's fossil record)

Version	What evolved
v0.29.0	search the whole project from the Workbench — new ⌕ search box greps every text file under the project root (case-insensitive, .git/node_modules/… respected, capped at 200 hits with a "showing first 200" hint, per-match file:line + context); click a result and the editor opens the file with the caret exactly on the match line, selection highlighting it; new /api/wb/search endpoint + test; verified live: 14/14 browser E2E
v0.28.0	the Workbench — a real dev environment for your project — new 🛠 Workbench opens the bound project (config.project_dir, or organism home): lazy file tree with type icons + sizes and skip-list (.git, node_modules, …), in-place text editor with ctrl+s write-to-disk, new file/dir, rename/move, delete, live refresh (the tree updates when anything else touches the project); behind it a full fs API (/api/wb/{root,tree,read,write,mkdir,delete,rename}) with path-escape + symlink-escape hardening, 512 KB read / 1 MB write caps and polite binary refusal; BUG FIX: the recompile loop — shell-reload storms (post-update seeding, dream bursts, rollbacks) could bounce the page on "recompiling shell" forever; a sessionStorage loop guard now reloads exactly once per storm; 8 new server tests + verified live: 12/12 browser E2E (tree → open → edit → ctrl+s → disk → rename → delete round-trip)
v0.27.0	plugins run in cages now — evolve_plugin accepts explicit perms:["http","fs","toast"]; a plugin without a permission gets a catchable error naming the missing capability (plugin "x" lacks permission "http" — re-evolve it with perms:["http"]) instead of silently reaching the real world; perms persist in plugin.json and are restored on every reload; log/on/every stay core (always on); 4 new tests (denial matrix, grant path, manifest persist + reload round-trip, core-always-allowed) — full suite + -race green
v0.26.0	tools grow type systems — evolve_tool accepts an optional typed contract (`schema: {param: "number"
v0.25.1	the demo brain works its plan the new way — the mock planner demo now walks declare → plan_advance → plan_advance×2 (one call = one step of progress) instead of re-sending the whole set_plan every turn; scenario test rewritten to assert exact advance-block counts; verified live: 9/9 browser E2E (boot 1/4 → live march 2/4 → 3/4 → 4/4 with correct statuses each step)
v0.25.0	the agent works its own plan — new plan_advance action: one call marks the current step done (by index or the doing step) and pulls the next todo into doing, so the brain loops through multi-step work without re-sending the whole plan; the declared plan is now injected into the system prompt every turn (## CURRENT PLAN with [x]/[~]/[ ] markers), so the model always knows where it is in its own work; plan helpers factored (publishPlan/countDone); 4 new tests (advance chain, index advance, bogus rejection, prompt injection) — all green
v0.24.0	the agent keeps a plan — first slice of the P0 planner: a new set_plan action lets the agent declare and advance multi-step task state ({title,status} per step, normalized to todo/doing/done), persisted atomically to workspace/plan.json (survives restarts), served at /api/plan, broadcast live over the bus, and rendered as a sidebar Plan panel with progress counter and ☑/◐/○ statuses (boot-restored on every load); the demo brain walks a plan declare → progress → done on request
v0.22.0	the docs evolve too — a single-page docs site generated straight from the README (internal/docsgen: section extraction + pragmatic markdown renderer with tables/fences/lists, HTML-escaped, sticky-TOC dark page; go run ./cmd/evolv-docs regenerates docs/index.html — 13 sections today), the installer grows --version / --help flags (resolves and prints the real latest release before you pipe it into sh), and the sprint gets a real engineering master plan at docs/EVOLV-24H-MASTERPLAN.md (repo audit, scored priorities, security backlog)
v0.21.0	fast while it sleeps — performance pass for organisms that mutate all night: the evolution ledger is virtualized (DOM holds the newest 200 entries, everything older stays out of the render tree behind a "⏵ show N older mutations" pager — the sidebar stays smooth at 1,000+ mutations), and streaming markdown is rAF-batched (token bursts coalesce into one parse + DOM rebuild per animation frame instead of dozens per second)
v0.20.0	dreams that write their own code — the idle dream engine is no longer a set of canned widgets: every dream composes a brand-new generative organ (palette, motion family, density and name drawn at random — orbs/waves/drift/rings/lines), and the other dreams re-open the previous organ's own file at ui/components/<name>.html, rewrite its code and let the shell remount it live. Plus the dream log: dream mutations are tagged dream:true in the evolution ledger, the sidebar groups consecutive dream mutations under a 🌙 "dream — nobody watching" divider, and the welcome screen greets you with "it dreamt N times while you were away" (click → replay)
v0.19.5	genome inspector, upgraded — file-type icons across the whole tree (🧩 organs, ⚙️ tools, 📝 skills, 🎨 skin, 🔌 plugins), a fuzzy filter box (subsequence match with highlighted glyphs, n of m files counter, Esc clears), unsaved-edit protection (switch/close warns, path shows ● unsaved) and a one-click ↺ revert back to the genome's own version
v0.19.0	autonomic nervous system — the demo organism now evolves BY ITSELF: idle heartbeat dreams grow real organs with zero keywords (music-box synth, gravity-pool physics, presence-clock, hex-pulse generative art), one per dream, then quiet — verified live, one mutation per minute with nobody typing
v0.18.0	🐍 playable snake — say "snake" and the mock brain grows a full arcade into its own canvas: 21×21 grid, arrows/WASD + swipe controls, score/best/length HUD, speed ramps every 3 foods, persistent best score; "snake" correctly outranks the generic "game"→flappy mapping
v0.17.0	share this conversation — ⇪ in the header downloads the whole transcript as one standalone HTML file (dark branded layout, XSS-escaped, zero external assets) via the new /api/export route; shell v15
v0.16.0	conversation search — ctrl+f opens a search bar over the chat: live match highlighting (CSS Custom Highlight API, zero DOM mutation), result count, enter/shift+enter to jump between matches, esc to close; shell v14
v0.15.0	sound & soul — 🔊 in the header wakes tiny WebAudio blips: a soft sine on file change, a triangle chirp on every mutation, a send blip; off by default, remembered per browser; shell v13
v0.14.0	mobile pass — EVOLV fits in your pocket: sidebar folds away on <820px and opens over a dimmed tap-to-close backdrop, full-bleed modals (organ / genome / diff / replay fill the screen), composer respects the home-indicator safe area, tested live at 390×844; shell v12
v0.13.0	"what changed" genome diff — ⏪ in the genome inspector diffs any two snapshots line-by-line (real LCS diff engine, /api/snapshots/diff); along the way: fixed same-second snapshot ID collisions and hardened snapshot restore against path escape — both caught by new tests; shell v11
v0.12.0	replay timeline — ⏳ in the sidebar opens the organism's entire fossil record (/api/replay, every mutation birth→now on one spine, color-coded by kind, click any entry to jump to the file it grew in the genome inspector); shell v10
v0.11.0	stop button (abort the organism mid-thought — real context cancel, not a cosmetic pause), daylight "paper" theme (one click / ctrl+shift+l, persisted), keyboard shortcuts (ctrl+k new chat · ctrl+b sidebar · / focus · esc closes), draggable resizable sidebar, shell v9
v0.10.0	the right-hand canvas pane is dead — the whole page is the canvas: organs mount inline in the conversation, sidebar Organs list, full-window organ mode; demo brain grows Flappy Bird + prompt-library + plugins + live self-edit
v0.9.0	demo brain grows up: the organism self-edits its own shell live (RECOMPILING SHELL), grows prompt-library buttons + skills in one batch, installs reactive plugins, and grows a playable Flappy Bird into its canvas; PayPal funding link
v0.8.0	markdown-lite v2 (lists, quotes, links), code blocks with language bar + copy, hover-to-copy messages, streaming caret, welcome screen, genome inspector can delete files — shell bumped to v7 for existing genomes
v0.7.0	conversation persists across restarts (atomic writes, corrupt-tolerant), evolv.http() for tools and plugins, silent provider retry
v0.6.0	batched multi-tool turns, real-time tool-card states, forgiving parser (salvaged raw JSON, unterminated fences), Claude-grade default skin, versioned shell reseed
v0.5.0	genome inspector, per-plugin sandboxes, skin hot-swap, mind panel
v0.4.0	dream mode, snapshots + rollback

FAQ

Is this just Electron + eval? No. It's one Go binary serving its own genome; the "eval" is a properly sandboxed goja runtime for agent-written tools, and UI components are plain files you can audit, edit, or delete at any time. What if the AI breaks its own UI? It happens sometimes — that's evolution. The factory genome is embedded in the binary; evolv --reset instantly restores it while keeping your evolution ledger. You can also fix it yourself: the UI is plain files. Does it need the internet? Only for models. With Ollama you get a fully local, offline self-evolving workspace. With the mock provider it evolves with zero brain at all (great for screenshots and parties). Why "EVOLV"? Because it does. Literally. You watched it happen in the GIF.

---

Contribute

The most fun repo on your machine to hack on:

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

Ideas that would be amazing: new protocol actions, a genome inspector UI, evolution replay/branching, security linting for evolved components, ports to new platforms. Open an issue or ping me directly — I answer everything.

Support & ideas

• [email protected] · Discord @dxn1_ai

If EVOLV made you say "wait, WHAT?" — a star genuinely helps other people find it. And if you want to help the mutation spread: tweet about it, post it on r/LocalLLaMA, or send the GIF to one friend who won't believe it.

About / keywords EVOLV — self-evolving AI workspace. AI that rewrites its own UI, tools and prompts live. A self-modifying agent and full coding workspace that works on your projects. Local-first, single Go binary, BYOK, free AI models via the Kilo Gateway. Think opencode or cursor, but the app itself is the thing that evolves.

License

MIT © dxn111