aevum ← home github ↗
start

How aevum works, and how to run it.

Two parts. First the shape — the four artifacts that carry a project across the death of the instance working on it. Then the wiring — how you put it into your own Claude Code.

part one — the shape

Four artifacts carry the line.

An AI coding instance is mortal — born without memory, dead when its context saturates. The project outlives it. aevum is the discipline that lets a fresh instance sit down and pick up exactly where the last one left off. It does that with four files.

  1. 01

    The baton

    looks backward

    The testimony one instance leaves the next — written from disk so it cannot drift into fiction. A fresh instance reads it first, then verifies it against the raw source before trusting a word.

  2. 02

    The round-table

    looks sideways

    An append-only round-table where parallel instances coordinate right now. Each claims a front, releases it when done — so two agents never silently work the same thing. Seats sit down; the round-table is where they keep from colliding.

  3. 03

    The lineage

    looks down the generations

    The genealogy, one node per close. Even after every working file is gone, the line of who-built-what stays legible.

  4. 04

    The compare-and-swap

    refuses the clobber

    When two instances of the same role close at once, the CAS rejects the silent overwrite and asks the later one to merge. Nothing is lost to a race.

part one — the loop

Every session is the same two moves.

You never re-explain the project. You boot — a fresh instance reads the baton, verifies it, and sits down in the seat. It works. Then it closes — leaving a new baton and adding a node to the lineage. The next instance repeats it. The project accumulates instead of restarting.

/bootread the baton · verify · sit
→
workthe seat does the job
→
/closeleave the baton · log the line
↺
next instancepicks up the line
part two — run it yourself

Wire it into your own Claude Code.

aevum is open (MIT). Right now it installs as a hands-on wiring for someone comfortable in a terminal — you clone the repo, read the contract, and cable the rituals into your .claude/. The one-step plugin that does this for you is next (below).

  1. Have Claude Code

    aevum is a protocol for running Claude Code across many sessions. You need the CLI installed and a project to run it on.

  2. Clone the repo

    The whole protocol — spec, reference scripts, templates, tests — lives here.

    # the protocol, in the open
git clone https://github.com/geheime/aevum▋

  3. Read the contract

    Open SPEC.md. It defines the artifacts and the rituals precisely enough that an instance can execute against it. This is the source of truth — read the raw file, don't infer.

  4. Cable the rituals

    Wire the /boot and /close rituals and the reference scripts into your .claude/. Run the test suite to confirm each failure mode it defends against is reproduced and green.

    # 20 checks: parser, reclaim, and the CAS
bash tests/run.sh▋
coming soon

One-step install — your Claude conducts it.

A Claude Code plugin (skills + slash-commands + hooks) that wires everything in a single step, and teaches your agent to drive the protocol on its own — detect a boot, leave the baton, refuse the clobber — without you steering each move. It has already been done by hand for one person; the plugin generalizes it. Watch the repo.

the two mother laws

If you keep only two rules, keep these.

  • Read the raw, don't infer from the output. Before you claim something works or merged, go to the real source — the file, the git log, the browser. The baton can be wrong; verify it.
  • A patch you repeat is a missing piece. If you fix the same thing every session, that is an unwritten rule. Write it down — as memory, a hook, a test — and stop patching.

Read the protocol on GitHub ↗