Home
GenOS brings a Git-like execution model to AI agents. It can freeze an agent and its world, fork several isolated futures, run competing strategies, compare their evidence, replay the winner from the original state, and promote only what passes verification.
It is less an “agent framework” than an experimental state and execution substrate for agents that need reversibility, lineage, controlled experimentation, and honest evidence.
Status:
v0.0.1-alpha.1, active pre-alpha research software. The core local primitives are executable today; distributed execution, hardened sandboxing, and production guarantees remain roadmap work.
Most agent workflows mutate one live timeline. GenOS turns that timeline into a graph of inspectable alternatives:
┌─ branch A: minimal patch ─ tests fail ─ reject
agent + world ─ snapshot S0 ──┼─ branch B: refactor ─ tests pass ─ replay ─ promote
└─ branch C: workaround ─ tests pass ─ compare
│
└─ events + diffs + lineage + receipts
The important unit is not a prompt. It is an Agent–World Capsule:
Capsule = genome + state + world + event history + execution budget
That boundary lets GenOS reason about more than generated text. It can track which agent acted, what it knew, which files it touched, which events produced the result, what budget it consumed, and how the result relates to its ancestors.
| Capability | What it changes |
|---|---|
| Snapshot and restore | Failures become recoverable checkpoints instead of lost context |
| Counterfactual forks | Several hypotheses can start from the same baseline |
| Isolated worlds | Sibling branches can mutate independent directory or worktree state |
| Structural diff | Decisions can compare state, beliefs, goals, files, and outcomes |
| Deterministic state replay | Supported state transitions can be reconstructed without another model call |
| Evidence-gated promotion | A branch wins because it passes declared checks, not because it sounds persuasive |
| Lineage and provenance | Every promoted result can retain where it came from and what changed |
| Genome and phenotype experiments | Agent traits, experience, heredity, and branch fitness become explicit research objects |
Read What is GenOS?, then How GenOS works. Together they explain why the project exists, how the capsule model works, and how a branch moves from hypothesis to verified promotion.
Start with the Quickstart. The smallest demo needs no model key. The safe parallel debugging walkthrough is the best product story in the repository.
Continue with Architecture, Isolation, replay & provenance, and Studio & interfaces.
For concrete interfaces, use the CLI guide, connect an assistant through MCP, or configure local AI and multi-model routing.
Read Evaluation, evolution & memory and Examples & evidence. GenOS includes executable experiments around Pareto selection, branch evolution, genome/phenotype separation, belief provenance, causal replay, resilience, and swarm coordination.
Then explore the orchestrator and its 77-strategy registry, Agent Trinity, A-Team, organizations & swarms, the layered approach to hallucination reduction, and the reproducible benchmarks & results.
The repository contains implemented local primitives for typed genomes and state, snapshots and capsules, append-only event histories, local content-addressable storage, directory and Git-worktree worlds, fork/diff/merge/replay workflows, evaluation experiments, a CLI, an MCP adapter, and GenOS Studio.
The project does not currently claim deterministic LLM inference, complete network replay, OS-enforced isolation for arbitrary untrusted code, distributed transactions, or production readiness. GenOS makes these boundaries visible rather than hiding them.
git clone https://github.com/PISSARAW/GenOS.git
cd GenOS
./run-demo.shThen run the richer debugging proof:
./examples/safe-debugging-demo/run-demo.shBoth run without provider credentials. See Examples & evidence for exactly what each command proves.