HOW AEON
IS BUILT.How aeon is built - the operator config, identity and memory, and channels that feed a runtime spine on GitHub Actions, the seven-way LLM gateway cascade, the self-healing loop, and fleet replication.

One map, three bands

Three input layers sit across the top - the operator config you set, the identity and memory the agent reads, and the channels and MCP servers it talks through. They feed a single left-to-right runtime spine. The spine drops into the model gateway, a fleet it can spawn, and a loop that heals it. Configure once; it runs the rest unattended.

For devs · The scheduler (messages.yml, */5) picks the first matching skill in aeon.yml and dispatches the aeon.yml runner. CLAUDE.md, STRATEGY.md, soul/ and memory/ load into context; any .mcp.json servers register as tools. Output commits back to the repo and fans out via ./notify; scored runs feed the self-healing loop, and spawn-instance/fleet-control extend the fleet.

The same map, as a circuit

The same system again, drawn as a live circuit - the coral pulses trace how a run actually moves through it: in from the inputs, along the spine, out to the loops.

What one run does

A single run reads left to right. The scheduler picks a skill, an optional authorization gate clears it, Claude Code executes the skill, the tools do the work, and the output ships. Every model call along the way routes through the gateway hung below.

For devs · The optional Fleet Watcher preflight can ALLOW/BLOCK a run before Claude starts (no-ops if its secrets are unset). Claude Code executes SKILL.md with memory/ in context; tools are bash, gh, WebSearch / WebFetch and any MCP servers. Output is a PR, a Pages / RSS update, a ./notify fan-out, or a dashboard feed card.

Every call fails over

aeon can power Claude Code seven ways. Whichever provider you have a key for and rank highest serves the run; if it dies - no credits, rate limit, outage, a dud response - the run falls through to the next, all the way down to the direct Anthropic API. A dead provider degrades gracefully instead of failing the run.

For devs · aeon.yml ships gateway: { provider: auto }; each run resolves the live provider from whichever secrets are set, in priority order. Override the order with GATEWAY_ORDER, or pin one (which disables failover) via gateway.provider. Native gateways export ANTHROPIC_BASE_URL; OpenAI-compatible ones (Venice, Surplus) bridge through a per-run claude-code-router sidecar.

What happens every five minutes

Nothing runs on a server. A clock ticks; the schedule picks exactly one skill; a throwaway machine boots; Claude reads that skill's instructions, does the work, grades its own output, and commits the result back to the repo. Then it sleeps until the next tick.

For devs · messages.yml fires */5; the first cron match in aeon.yml wins; a GitHub Actions runner dispatches aeon.yml; Claude Code executes SKILL.md with memory/ in context; Haiku scores the output 1–5 into memory/skill-health/; git commit persists output + state. A non-matching tick exits in ~10s.

The fleet repairs itself

aeon watches its own work. Every run gets a grade, and the grades pile up in one file. A sentinel reads them - and when a skill keeps failing, aeon files an issue, writes a fix, opens a pull request, and merges itself back to health, usually before you notice anything broke.

For devs · Scores and flags land in cron-state.json. heartbeat (3×/day, listed last) reads it; skill-health files a structured issue; skill-repair patches the SKILL.md and opens a PR; the merge closes the loop. The dashed path is the reactive trigger - consecutive_failures >= 3 auto-fires skill-repair without waiting for cron.

Skills snap together

Skills compose like building blocks. Run two at once, drop what they produce into a shared folder, and hand both results to a third skill that writes your morning brief - then pings you. No orchestrator, no glue code, just a few lines of YAML.

For devs · A chains: block in aeon.yml runs steps via chain-runner.yml. parallel: [token-movers, hn-digest] fans out; each writes .outputs/{skill}.md; priority-brief consume:s both (injected as context) and calls ./notify. Set on_error: fail-fast or continue.

One aeon becomes many

aeon doesn't just run itself - on a schedule it can fork itself into a brand-new repo, copy the API keys across, and stand up a whole fleet of specialised instances, each running on its own. No heartbeat, no operator: just the cron clock and a few core skills.

For devs · spawn-instance (manual) clones the agent into a new GitHub repo, configures a skill subset, validates, and registers it in memory/instances.json; fleet-control (2×/day) checks health and dispatches across instances; fork-fleet tracks forks in the wild. Secrets don't auto-propagate for safety - the spawn step provisions the new repo's Actions secrets so the fork can run. It's all cron-driven from aeon.yml - no sentinel required.

The original shape, retargeted: context feeds the schedule, which fans out to spawn-instance, migrate-keys, and self-improve - then it runs a fleet.

It grows toward your number

Point it at a metric it cannot measure yet and aeon doesn't stall - it writes the skill it is missing, asks you once for the API keys, and wires it in. Now the fleet is bigger. Run after run it reprioritises and tunes its own skills, compounding toward your number with no new instruction from you.

For devs · Every run reads STRATEGY.md. When a priority needs data no skill collects, aeon drafts a new SKILL.md, requests the credentials, and registers it in aeon.yml - the fleet grows by one. Paired with the self-healing loop (06), the system both repairs and extends itself: the same loop that runs forever also gets better forever.