Using Aesop

01 / Requirements

What you need on the machine.

Aesop is a kernel. It does not know your repositories, rules, or accounts, so you provide them.

Licensing: Aesop is open source under the MIT License. Releases 0.8.0 through 0.11.0 were published under PolyForm Noncommercial 1.0.0; versions up to 0.7.0 were MIT. Bug reports, questions, documentation fixes and pull requests are welcome: see CONTRIBUTING.md. Report vulnerabilities as described in SECURITY.md.

Read the blueprint page: Quickstart.

02 / Install

Scaffold a fleet from npm.

The package is @matt82198/aesop on npm. The scaffold command installs the /power and /buildsystem skills into ~/.claude/skills/ unless you pass --no-skills.

npx @matt82198/aesop my-fleet --name "api" --repos "/path/to/repo"
npx @matt82198/aesop doctor

doctor shows what is still missing. The CLI copies the pre-push policy into the hooks of the repo it scaffolds.

Adding --install-deps runs npm install and pip install -r requirements.txt in the target. --force replaces any existing .git/hooks/pre-push and overwrites installed skills. --yes skips interactive prompts and uses defaults. --repos takes comma-separated repo paths.

Read the blueprint page: Quickstart, Install the hook.

03 / Commands

The documented commands.

This table lists commands that appear in the project's README and docs. Nothing else is claimed.

From a checkout

These run from the root of a clone of the source repository.

Read the blueprint page: Quickstart.

04 / First run

From install to one wave.

The README lists six steps. The first-wave guide in the repository (docs/FIRST-WAVE.md) walks through them.

1. Install the kernel

   Run the scaffold command from the install section, then npx @matt82198/aesop doctor to see what is still missing.

2. Point it at your repos

   Copy aesop.config.example.json to aesop.config.json and set repos. Field reference: docs/CONFIGURE.md.

3. Write your brain

   Copy CLAUDE-TEMPLATE.md to ~/.claude/CLAUDE.md and edit it. Add a MEMORY.md built from docs/MEMORY-TEMPLATE.md. /power reads both.

4. Name a machinery directory (optional)

   Set CONDUCTOR_ROOT to a directory you own. The watchdog derives a sibling fleet root only for the canonical aesop checkout and otherwise refuses to start.

5. Provide keys and accounts

   Run gh auth login for merges and sign in to Claude Code for workers. Add API keys only if you use an API backend.

6. Run one wave

   Run npx @matt82198/aesop watch, then /power, then /buildsystem.

Read the blueprint page: Quickstart.

05 / Structure your repo

Make it easy for a small lane to do one job.

Your rules, project map and dispatch contract live in your repo and your brain, not in the kernel.

Rules for how lanes work in your repo

• One worktree per lane. A lane works in its own worktree, and the pre-push gates run before anything reaches CI.
• One lane, one stage. Each stage is a separate dispatch, and a brief names exactly one stage. See the system page.
• Failure changes the contract. A failed lane is killed, and the contract is amended before a fresh lane is dispatched.

Read the blueprint page: Stage lanes, Stage matrix.

06 / Watch and recover

Dashboard and recovery.

The dashboard is a live fleet view, with a zero-key demo mode (npx @matt82198/aesop dash --demo).

The loop is crash-only, so recovery is a restart from disk. The watchdog has a halt switch: while a halt sentinel exists it logs HALTED and skips its work, and self-heal leaves it alone. A stale watchdog heartbeat triggers a restart only when no halt is in effect.

Read the blueprint page: Crash-only operation.

07 / Verify an event store

Check a hash chain in a few steps.

The repository guide checks an event store's hash chain and shows what a broken chain looks like. Nothing needs installing beyond the Python standard library. From a checkout:

# Step 1: run the unit tests; stop here if the suite does not print OK
python -m unittest tests.test_event_store_core

# Step 2: create a throwaway store (replace <work> with an empty directory outside any git repository)
#   <work>/stores/demo/store.json  contains {"project": "demo", "schema": 2}
#   <work>/registry.json           contains {"stores": {"demo": {"path": "<work>/stores/demo", "goals": ["G9"]}}}
mkdir -p <work>/stores/demo/events
export EVENT_STORES_REGISTRY=<work>/registry.json
python -I tools/event_store/cli.py append --project demo --kind note --actor orchestrator --text "first demo event" --ref goal=G9
python -I tools/event_store/cli.py append --project demo --kind ruling --actor orchestrator --text "second demo event" --ref goal=G9
# expected: appended demo seq=1, then appended demo seq=2

# Step 3: verify a store (exit 0 when clean, 1 when a problem is found)
python -I tools/event_store/cli.py verify --path <store>

verify is tamper-evident, not tamper-proof: editing only the last line passes, because no later line stores its hash. The full steps, including the append-only guard, are in docs/guides/verify-event-store.md.

Read the blueprint page: Verify an event store, Event store.