rust · filesystem-native · daemon-first
Where agents
build agents.
An agentic build system for agentic systems. Ontology-grounded, auditable, one Rust binary.
start an assistant
Install once, grow everything else
meclaw is three things, and you only install the first one. meclaw is the substrate: a directory tree that runs — every folder an actor, every edge a route, one Rust binary underneath. meclaw-os is a small, experimental operating system for agents, grown onto that substrate at runtime. An assistant is grown into the OS the same way — a JSON file, not a deployment.
# 1 — install meclaw: one static Linux binary (lands in ~/.local/bin)
curl -fsSL https://meclaw.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
# the templates must match the binary: clone the tag the installer just gave you
git clone --depth 1 --branch "v$(meclaw --version | cut -d' ' -f2)" \
https://github.com/mmeyerlein/meclaw && cd meclaw
# one key — replace sk-... with a real one (https://openrouter.ai/keys), or step 3 ends in code=auth
printf 'OPENROUTER_API_KEY=sk-...\nMODEL_BRAIN=openai/gpt-4o-mini\n' > examples/meclaw-os/seed/.env
# 7777 is an arbitrary free port: if it is taken, change it in every line below as well.
# The very first start reads a 25 MB binary from cold disk and can stay silent for ~40 s; every later start takes well under a second.
meclaw --root examples/meclaw-os/seed --templates ./templates --daemon --api 127.0.0.1:7777
# 2 — install the OS into the running colony: one POST, nothing restarts
curl -s -X POST 127.0.0.1:7777/colony/mutations \
-H 'Content-Type: application/json' -d @examples/meclaw-os/grow.json
# 3 — talk to your assistant
curl -s -X POST 127.0.0.1:7777/messages -H 'Content-Type: application/json' \
-d '{"target": "/door", "headers": {"channel": "chat-1"},
"body": {"messages": [{"origin": "user", "type": "text",
"text": "Say hello in one short sentence."}]}}'
# 4 — read the answer: nothing is hidden, the reply is a hop on the record (needs jq)
curl -s '127.0.0.1:7777/colony/trace?limit=200' | jq -r \
'[.trace[] | select((.headers_json | fromjson | .hop.route) as $r | $r == "answer" or $r == "error")]
| last | if . == null then "no answer yet — the colony is still working; watch it at http://127.0.0.1:7777/ui/"
else .body_payload | fromjson | .messages[0].text end'
# 5 — watch the colony in the browser: http://127.0.0.1:7777/ui/One binary, one key, four steps — the answer is not a return value, it is a message on the record.
what just happened
Three installs, and only one of them was software
You installed meclaw. A single Rust binary that turns a directory tree into a running colony of actors: every folder is a cell, its config.json is its definition, and the edges between folders are the routes a message can take. Nothing else got installed.
You installed an operating system — without stopping anything. grow.json is not code and was not deployed: it is a mutation, nodes and edges, applied over HTTP to a colony that was already running. It grew a door, a firewall and a conversation agent out of the template library — and that is the only way anything is ever added to a colony, which is why the same door is open to the agents themselves.
You talked to an assistant nobody programmed. No SDK, no agent class, no loop you wrote — the assistant is a shape in the filesystem, grown from templates. The full version of that shape grows an organisation, a person, their assistant and their channels from five such files.
why it is built this way
meclaw doesn't ship you a loop
Every agent framework ships the same thing: a loop — call the model, run a tool, feed the result back, until some condition you wrote says stop. In meclaw an llm cell makes one provider call and emits one message; tools are cells, the loop is an edge that routes back, the harness is topology. Since topology is files, the swarm can rewrite its own harness while it runs — and that decision raises the same questions every time. Each one is a page.
Everything is a file
Because the harness lives in the filesystem, ls, grep, diff and git are the tooling, and an agent rebuilds its own topology with the same closed vocabulary a human uses. There is no SDK and no plugin API — the interface is HTTP and files, and 38 shipped templates without a line of Rust are the proof.
An operating system for agents
Every agentic product ends up rebuilding the same things: an organisation, its people, their assistants, the channels they are reached on, plus secrets, screening and sessions. meclaw-os ships those as templates under one rule — a level owns what its siblings must share — and it is rudimentary and experimental, built so a new agent is a grow, not a project.
read the page →One assistant, two brains
The shipped assistant runs two models on purpose: a conversation surface that answers fast, and a reasoning core that thinks — one job, one brain, one tool menu each, and the menu is asked for rather than typed into a prompt. One model doing both is either slow in conversation or shallow in reasoning; the split is a harness decision, and the harness is a file.
read the page →Memory that outlives the window
A conversation can run for weeks — not because something clever compacts the context, but because the window was never where the conversation was stored. The memory hive writes without an LLM, retrieves over five model-free legs, consolidates nightly by superseding instead of deleting, and the window is assembled per turn out of the record, under a budget.
read the page →Ontology, in the meclaw sense
Not philosophy: a typed catalogue. The builder designs against the template library and its declarations and is validated by them, rather than emitting free-form JSON somebody hopes parses — and when the catalogue has no word for what you want, add_templates registers a new class into a running colony.
Prepared for recursive self-improvement
The primitives are here and tested: runtime mutation, a builder that turns a wish into a manifest, keep-or-revert on a measured window, a receipt for every act. meclaw is prepared for recursive self-improvement — the loop that closes them is not (yet), and deliberately so: nothing in the repository improves itself unattended, and every goal the control loop could pursue ships disabled.
read the page →The strange names
argus, affinity, talky, cogny, hive — the names are roles, not branding. Each one carries a one-line reason, and the page is where those lines live.
read the page →Why Rust, why Linux only
One static binary, one async task per cell — and the security model is the kernel: Landlock, network namespaces, cgroup v2 and seccomp, fail-closed. Without those primitives "sandboxed" would be a promise instead of a property, which is why there is no macOS build; authentication is the reverse proxy's job, as for every Linux daemon.
read the page →You talk, it shows
This one is an idea, not a feature: the vision is the movie Her — you talk to it, and it shows you, drawn onto a display that belongs to you rather than to any one agent. Nothing in the repository does that today; what exists is the window it would draw on, and where the idea is being followed is voice2vision.eu.
read the page →limits
Honest about the version number
code cells run python3, nothing elseOne runtime for cell code. No second language, no plugin API.Under heavy development
meclaw is not finished, and it is open source so it does not have to be finished alone. Good first contributions: example colonies, template cells, docs drift-fixes — see CONTRIBUTING.md and the good first issue label. 6500+ tests, 0 fail; release truth lives in CHANGELOG.md.