Architecture
How Aeon uses a single GitHub repository and GitHub Actions runners as a zero-infrastructure agent runtime.
Aeon is a GitHub repository (aeonfun/aeon) paired with a Next.js control plane (hosted at Aeon Connect or run locally via ./aeon). Git is the database and GitHub Actions is the compute layer - there is no server, daemon, or external database to maintain.
Three Surfaces
- Dashboard - configures skills, schedules, and secrets either in the browser at Aeon Connect or locally at
http://localhost:5555(./aeon). - Repository - holds markdown skills (
skills/), agent identity (CLAUDE.md,STRATEGY.md,soul/), git-committed memory (memory/), and schedules (aeon.yml). - Actions Runners - throwaway GitHub Actions VMs that wake on cron, execute due skills through the configured coding-agent harness, score output quality, and commit state back to git.
Four Key Files
| File | Role |
|---|---|
aeon.yml | Enabled flags, cron schedules, var inputs, model/harness overrides, chains, and reactive triggers. |
CLAUDE.md | Standing agent instructions loaded on every run; imports STRATEGY.md, memory/MEMORY.md, and soul/. |
catalog/skills.json | Machine-readable skill registry generated from each SKILL.md by bin/generate-skills-json. |
.github/workflows/scheduler.yml | Cron workflow that ticks every 5 minutes and dispatches due skills. |
Control Plane
Locally, apps/dashboard/ shells out to gh for /api/* calls (secrets, workflows, config). It is loopback-gated by default and supports AEON_DASHBOARD_ALLOWED_HOSTS for Tailscale with strict same-origin checks.
In the browser, Aeon Connect serves the same interface multi-tenant by calling GitHub through the Aeon Connect GitHub App using short-lived installation tokens scoped to your repository.
Repository Layout
aeon/
├── CLAUDE.md # agent identity & standing rules
├── STRATEGY.md # operator north-star brief
├── aeon.yml # schedules, chains, reactive triggers
├── ./aeon # local dashboard + CLI launcher
├── ./notify # multi-channel notification dispatcher
├── catalog/
│ ├── skills.json # generated skill catalog
│ └── packs.config.json # first-party pack definitions
├── bin/
│ ├── onboard # validate instance setup
│ ├── add-skill # import skills from GitHub
│ └── generate-skills-json # regenerate catalog files
├── skills/
│ └── <skill-name>/SKILL.md # one prompt file per skill
├── apps/
│ ├── dashboard/ # local Next.js UI
│ ├── cli/ # headless CLI
│ ├── mcp-server/ # local stdio MCP server
│ └── webhook/ # Cloudflare Worker for instant Telegram
├── memory/
│ ├── MEMORY.md # goals, active topics, pointers
│ ├── cron-state.json # per-skill run metrics & scores
│ └── issues/ # structured failure tracker
└── .github/workflows/
├── aeon.yml # skill runner + Haiku quality scorer
├── chain-runner.yml # multi-step skill chain executor
├── scheduler.yml # 5-minute cron dispatcher
└── messages.yml # inbound Telegram/Discord/Slack router