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 eight-way LLM gateway cascade, the self-healing loop, and fleet replication.

One map, three bands

Three input layers - operator config, identity/memory, and channels and MCP servers - 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.

For devs · The scheduler (scheduler.yml, */5) dispatches every due skill in aeon.yml. CLAUDE.md, STRATEGY.md, soul/ and memory/ load into context; .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, live - coral pulses trace how a run 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 auth gate clears it, Claude Code executes it, tools do the work, and the output ships. Every model call routes through the gateway below.

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

Every call fails over

aeon can power Claude Code eight ways. Whichever provider you rank highest and have a key for serves the run; if it dies - no credits, rate limit, outage, a dud response - the run falls through to the next, down to the direct Anthropic API.

For devs · aeon.yml ships gateway: { provider: auto }; each run resolves the provider from whichever secrets are set, in order. Override with GATEWAY_ORDER, or pin one (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.

For devs · scheduler.yml fires */5; every due cron skill in aeon.yml dispatches in parallel to a GitHub Actions runner; Claude Code executes SKILL.md with memory/ in context; Haiku scores the output 1-5 into memory/skill-health/; git commit persists output + state.

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.

For devs · Scores and flags land in cron-state.json. heartbeat (daily) reads it; skill-health files a structured issue; skill-repair patches 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 in parallel, drop their output into a shared folder, and hand both to a third skill that summarizes and notifies. No orchestrator, no glue code - just YAML.

For devs · A chains: block in aeon.yml runs steps via chain-runner.yml. parallel: [token-movers, github-trending] fans out; each writes output/.chains/{skill}.md; digest consume:s both and calls ./notify. Set on_error: fail-fast or continue.

One aeon becomes many

On a schedule, aeon can fork itself into a brand-new repo, copy the API keys across, and stand up a fleet of specialised instances, each running on its own.

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. Secrets don't auto-propagate - the spawn step enables the fork's Actions but leaves it inert (pending_secrets) until you set its Actions secrets by hand.

Context feeds the schedule, which fans out to spawn-instance, fleet-control, and self-improve.

It grows toward your number

Point it at a metric no skill can measure yet: run create-skill, it drafts the missing skill, flags the API keys it needs, and opens a PR to wire it in. Merge, and the fleet is bigger. The scheduled self-improve pass then tunes the skills you already have, run after run.

For devs · Every run reads STRATEGY.md. When a priority needs data no skill collects, the operator-dispatched create-skill drafts a new SKILL.md, flags the credentials it needs, and registers it in aeon.yml as a disabled skill behind a PR. The scheduled self-improve pass tunes existing skills.