aeon

Quick start

You need three things:

1. Node.js 20+ - grab the LTS installer from nodejs.org, or use a package manager: brew install node (macOS), winget install OpenJS.NodeJS.LTS (Windows), nvm or your distro's package manager (Linux). Already have it? node -v should print 20 or higher.

2. GitHub CLI (gh), authenticated - the dashboard uses it for everything (secrets, workflows), and ./aeon checks it before starting. Install: brew install gh (macOS), winget install --id GitHub.cli (Windows), per-distro instructions (Linux). Then run gh auth login and follow the prompts.

3. Your own copy of this repo - click Use this template at the top of the repo page - keep it public, Actions minutes are free on public repos. CLI version: gh repo fork aaronjmars/aeon --clone.

git clone https://github.com/<you>/aeon   # skip if you used `gh repo fork --clone`
cd aeon && ./aeon

Open http://localhost:5555 and follow the four steps:

1. Authenticate - connect your Claude Pro/Max subscription, or paste an API key: Anthropic, Anthropic-compatible, or a gateway key (Bankr, OpenRouter, UsePod, Venice, Surplus) - routed automatically.
2. Add a channel - Telegram, Discord, or Slack so Aeon can talk to you.
3. Pick skills - toggle what you want, set schedules. Each skill shows the API keys and MCP servers it needs, with one-click setup.
4. Run - hit Run now on any skill to try it immediately; API keys and var values apply directly, no push needed. When you change config (schedules, toggles), Push commits it to GitHub in one click so Actions runs it on cron.

That's it - Aeon now runs unattended. On a public repo, GitHub Actions minutes are free. Run ./onboard anytime to verify your setup.

Dashboard views, local dev, env vars, and remote access are documented in apps/dashboard/README.md.

Grab the gh_*_macOS_arm64.zip (or your platform's binary) from github.com/cli/cli/releases and drop it on your PATH (e.g. ~/.local/bin). No installer, no sudo. Then gh auth login.

What Aeon can do

102 skills, grouped into 10 packs. By default the dashboard shows only the small core set; everything else is hidden until you enable its pack in the Packs view - a visibility switch that reveals a pack's skills across the UI without running anything. Putting a skill on duty stays a per-skill toggle. Every skill is independently installable, schedulable, and chainable. How packs work: docs/skill-packs.md.

Authoritative source: skills.json + packs.json, the dashboard Packs view, or ./add-skill aaronjmars/aeon --list. A skill's pack comes from its category: frontmatter - see docs/skill-packs.md. Dependency graph: docs/skill-graph.md - a visual map of how skills connect.

It heals itself

Every skill output is automatically scored 1–5 by Haiku after each run. Scores and failure flags (api_error, stale_data, rate_limited) are tracked per skill in memory/skill-health/ with a rolling 30-run history. When something breaks, the loop fixes it without you:

1. heartbeat (3x daily) - detects failed, stuck, or chronically broken skills
2. skill-health - audits quality scores and flags API degradation patterns
3. skill-evals - assertion-based output tests to catch regressions
4. skill-repair - diagnoses and patches failing skills automatically
5. self-improve - evolves prompts, config, and workflows based on performance

Health skills file issues, repair skills close them. heartbeat is the only skill enabled by default: nothing to report → silent; something needs attention → one notification. Deep dive: docs/CORE.md.

Votable health (on by default — set the repo variable HEALTH_ISSUES=0 to turn it off): when a skill regresses (a Haiku score of 1–2 or a failure flag), the loop opens or comments on a per-skill GitHub Issue titled health: <skill>; clean runs stay silent, so there's no issue spam. 👍/👎 the issue and self-improve / skill-repair triage the most-voted, worst-scoring skills first — a visible, conflict-free repair queue you can steer.

It replicates

Aeon can spawn and manage copies of itself. spawn-instance forks the repo into a new specialized instance (var: "crypto-tracker: monitor DeFi protocols"), selects relevant skills, and registers it in memory/instances.json - no secrets propagated, billing stays isolated. fleet-control health-checks and dispatches across instances; fleet-scorecard tracks fleet economics.

It ships real work

external-feature ships code to watched repos unprompted. deploy-prototype generates and deploys live web apps to Vercel. vuln-scanner