agentvcs

The goal: make an agent's run-time evolution first-class and trustworthy — capture every iteration (code + goal + models + trace + swarm) as one commit, prove & freeze what works into a deterministic recipe, reconcile it back into your git releases, and measure whether the self-modification is actually improving.

Two timelines, one file

An agent in production rewrites its own skill and spawns a sub-agent to help. Meanwhile your team edits that same skill in git. Both changes are correct. Neither knows about the other. Today one of them is thrown away, usually the agent's, because there is nowhere to put it.

agentvcs gives it somewhere. A commit is not a tree of files — it is an atomic snapshot of four dimensions at once, plus the sub-agent swarm:

• code — the files as usual: tools, scripts, markdown skills.
• goal — the intent or directive the agent was pursuing.
• models — which LLM ran, with which params (temperature, …).
• trace — the chain of thought, tool calls and real results that caused the change.

Which means the runtime line and the design-time line are both branches, and the question becomes a merge. Every commit also carries a state: fluid while the agent is still searching probabilistically (high temperature, code and goals mutating between iterations), crystallized once it has been proven and frozen — models pinned to temperature 0, the iteration compiled into a replayable recipe that is cheap, stable and deterministic. And diff tells you which dimension moved: a goal redirect and a code change are distinguishable events, not one opaque text diff.

The reconcile contract

Merging two prose goals or two session traces is not a job for a line-differ. So agentvcs does not try. It writes a bundle to a subprocess's stdin — {base, ours, theirs} goals, traces, code diffs, eval and cost metrics, plus any unresolved conflict text — and reads back {goal, trace, notes, resolved_files}.

agentvcs merge runtime/main --reconcile "nanoloop reconcile"

That is the whole interface. The core has no LLM dependency and no opinion about what is on the other end. Conflicting hunks are pre-resolved toward whichever side has the higher verified eval score before the reconciler is consulted at all.

Crystallizing

freeze turns a proven run into a deterministic recipe you can replay. It refuses unless the declared eval passes on every run, and --force past a failure stamps verified: false rather than quietly lying. "Crystallized" means "proven", enforced in code rather than in the README. A rollback restores the full prior state — code, goal, models and trace together — and records why in a durable ledger.

Does the evolution actually work?

Because agentvcs keeps the whole lineage — every variant as a commit with an eval score — it can measure something a code VCS can't: whether a self-modification loop is genuinely improving, or merely changing. Each of these is an exact, standard-library computation over the commit graph, not a heuristic:

• price — the Price equation splits a quality change into selection (choosing between branches) and transmission (editing within a lineage), and flags the Eigen error catastrophe when editing degrades faster than selection recovers.
• health — critical slowing down (a collapse warning before the mean score even moves) plus Muller's ratchet load on a branch left unmerged too long.
• infobits — how many bits your context actually buys (Kelly / channel capacity): the compression headroom.
• contain — a branching-process test R₀ = n·p for whether a poisoned shared memory will spread across a fleet or die out on its own.

Two runnable walkthroughs make the point without any math on screen: five plain-English business cases (a support bot that quietly gets worse every week, a fork nobody merged, wasted context, a poisoned memory), and the technical companion where every claim is asserted against --json. Both run on real evaluations — see the demos.

Nothing to install around it

The whole thing is pure Python standard library, zero runtime dependencies — deliberate, for auditability and drop-in integration. It doesn't ask you to instrument your code either: traces are captured passively from what the runtime already writes (local session files, events) through built-in providers for claude-code, qwen-code, anthropic-managed, vercel-eve and odyssey. Secrets are [REDACTED] by default.

Every command accepts --json and emits one parseable object with stable error codes, so an agent recovers programmatically instead of parsing English — and an MCP server ships with it (claude mcp add agentvcs -- agentvcs-mcp), so Claude or Cursor can version the agent autonomously. Two layers are opt-in and off by default: an Ed25519 Soul (init --with-soul) that signs every commit and mints a Soulbound Token on each verified freeze — a CV of what the agent has actually proven, reputation that can't be cloned — and a corporate layer (init --corporate) with a signed audit log and human approvals.

What's proven

212 tests pass across Python 3.10–3.13. CI runs the full version matrix plus an end-to-end smoke test that executes the agent-loop demo and asserts a scorecard ≥5/6. Pure standard library, zero runtime dependencies; install from source (not on PyPI yet).

git clone https://github.com/EvolvingAgentsLabs/agentvcs
cd agentvcs && pip install -e .
bash examples/business-cases/run.sh      # plain-English demos, offline, seconds
bash examples/eve-evolve-merge/demo.sh   # the reconcile, offline, no API key

That demo forks a RefundBot into a runtime line and a design-time line and merges them, producing a marker-free skill containing both rule sets and a swarm containing both sub-agents.

What to know before you trust it. The demo's reconciler is a deterministic bullet-union stub, honest in its docstring but not intelligent — the LLM reconciler is a separate piece. And test coverage is lopsided: the optional cryptographic layer has 20 tests while the core object store has 5.