aeonfun/aeon: an unattended agent framework that runs on GitHub Actions

The problem Aeon targets: work that should happen without you

Most agent tooling assumes a person is present. You type a prompt, you approve a tool call, you review a diff. Aeon inverts that assumption. The README states the project is built for "the work you want done while you're away" and claims to be the only framework that does four things unattended at once: run on a schedule, remember across runs, react to conditions, and repair its own broken skills. The slogan is blunt about the trade-off: "No approval loops. No babysitting. Configure once, forget forever."

The intended user is someone who already treats GitHub Actions as a place to run automation. The README's quick start assumes three things you must supply yourself: Node.js 20 or newer, an authenticated GitHub CLI, and your own copy of the repository. That last requirement is structural rather than cosmetic. Aeon is designed to be forked or templated, not consumed as a dependency, because the agent commits work back into the repository it runs from.

The skill catalog is the second half of the pitch. The README describes six packs with 60 or more skills, and links to a catalog page that lists 80. The packs are named Core (fleet coordination, self-config, liveness), Evolution (skills that author and heal other skills), Basics, Dev and Code, Crypto and Markets, and Productivity. That breadth is also the first thing to be skeptical about: a catalog of 80 prompts is not the same as 80 capabilities you have validated.

A skill is a Markdown file, and the prompt is the program

The unit of work in Aeon is a SKILL.md file. The README gives a trimmed real example from skills/digest/SKILL.md, and the structure is worth reading closely because it explains most of the framework's behaviour. There is a YAML frontmatter block with name, category, description, requires, var, and mode. Below it, the prompt itself is the skill.

# skills/digest/SKILL.md
---
name: digest
category: basics                 # which pack it belongs to
description: Generate and send a digest on a configurable topic
requires: [XAI_API_KEY?]         # ? = optional key, bare = required
var: ""                          # per-run input - "solana", "rust", "AI agents"…
mode: write
---

Three keys carry real weight. requires declares API keys, and the README notes that a question mark marks a key as optional while a bare name is required, so the frontmatter is also the dependency manifest. var is the per-run input, which is how one digest skill covers many topics without forking the file. mode: write signals that the skill can change things rather than only read, which is the field to look at before enabling anything you did not write.

Scheduling happens outside the file. The dashboard configures skills and puts them on a cron, and the README says Haiku rates every run. That rating is a quality signal produced by a model, not a test suite, so treat it as a hint rather than a gate. Skills can also be chained into one another, which is how a digest skill could feed a delivery step.

Nine harnesses behind one run-harness contract

Aeon does not ship its own model client. It drives external agent CLIs, and the README names nine: Claude, Grok, Codex, Pi, Vibe, Kimi, fx, Cursor, and Hermes. The mechanism is a single adapter contract called run-harness, and the README states that every harness honors the same shape for result, usage, and session. Swap the harness and nothing else in the skill changes.

That is a genuinely useful abstraction, and it is also where the abstraction leaks. The harnesses are separate CLIs with separate authentication, separate rate limits, and separate pricing. Aeon normalizes the return shape, not the cost or the failure modes. The README also draws a boundary worth noting: GLM Coding Plan is described as a Claude AI Gateway hop via GLM_API_KEY, not a harness. If you assumed any OpenAI-compatible endpoint could be dropped in as a tenth harness, the project's own wording says otherwise.

The repository layout reflects the same adapter idea at the top level, with harness-adapter/ sitting beside skills/, catalog/, memory/, and soul/. The memory/ directory is what backs the claim about remembering across runs, and soul/ appears to hold the persistent configuration the dashboard writes. The README does not document the internal format of either directory, so anyone planning to hand-edit state should read the source first.

Installing Aeon and running the digest skill for the first time

The README's quick start is four steps: fork the template, connect a channel, pick skills, let it run. The prerequisites are explicit. You need Node.js 20 or newer, the GitHub CLI authenticated with gh auth login, and your own copy of the repository. The README asks you to keep that copy public because Actions minutes are free on public repositories, and offers two ways to get it.

gh repo fork aeonfun/aeon --clone
cd aeon && ./aeon

If you cloned manually instead, the README gives the equivalent as git clone https://github.com/<you>/aeon followed by the same cd aeon && ./aeon. The ./aeon entrypoint starts the local dashboard, and the README says to open localhost:5555 and follow the on-screen flow: authenticate against one of the nine harnesses, add a channel, pick skills, then Run.

The dashboard is not the only interface. The README states that everything is also an ./aeon command through the CLI, and a /aeon chat command through the setup skill, which can be installed as a Claude Code or Codex plugin. For the digest skill shown earlier, the practical first run is to enable it in the dashboard, set its var to a topic such as "rust", and confirm that the XAI_API_KEY requirement is satisfied. Because that key is marked optional with a question mark, the run may still start without it, which is exactly the kind of thing to watch on a first execution rather than assume.

One more installation note from the README: if you lack admin rights and cannot install gh, it points to the gh_*_macOS_arm64.zip or your platform's binary from the cli/cli releases page, dropped on your PATH, for example in ~/.local/bin, followed by gh auth login. There is no documented rollback procedure for a skill that has already run, which is a gap given that skills can run in write mode.

The autonomy claim has a real failure mode

The design decision that defines Aeon is the absence of approval loops, and it is the same decision that limits where the tool belongs. A skill with mode: write can change a repository, and the README's own examples include shipping features, disclosing vulnerabilities, and deploying live apps. There is no described confirmation step between a scheduled trigger and those outcomes.

The self-healing claim deserves the same scrutiny. The Evolution pack is described as authoring and healing skills, which means an agent can modify the prompts that govern its own future runs. That is a closed loop: a bad edit to a skill becomes the input to the next scheduled execution. The README does not document a review gate, a diff approval, or an automatic revert for skill changes. Whether that is acceptable depends entirely on what the skill is allowed to touch.

A concrete case where Aeon is the wrong tool: any workflow with a regulatory or contractual requirement that a human authorizes an action before it takes effect. Vulnerability disclosure is the sharpest example from Aeon's own catalog. The README lists privately disclosing real vulnerabilities as a capability, but coordinated disclosure usually involves a maintainer, a timeline, and a judgement call about severity. An unattended agent can draft that report; it should not be the thing that decides when to send it. The same reasoning applies to anything that spends money, deletes data, or speaks to a third party under your name.

How Aeon differs from Claude Code and Hermes

The README's own comparison is against Claude Code, Hermes, and others, and the framing is that most agent tools keep you in the loop while Aeon does not. That is a fair description of the difference in posture, but it is not the whole difference in approach.

Claude Code is an interactive coding agent. You run it in a terminal, it works on your codebase, and you steer it. Aeon is a scheduler and a skill registry that happens to call agent CLIs, Claude Code among them. The distinction matters because it changes what you are responsible for. With an interactive agent, the session is the unit of control: you can stop it. With Aeon, the cron entry is the unit of control, and the interesting question becomes what a skill is permitted to do when nobody is watching.

Hermes appears in the README both as a harness Aeon drives and as a comparison point, which is a slightly unusual position. The practical reading is that Aeon treats these tools as interchangeable execution backends rather than as competitors. If you already pay for one of the nine harnesses, Aeon is a way to schedule it. If you want a single vendor's opinionated workflow end to end, Aeon adds a layer you may not want.

Licence, packaging, and the upgrade cost

Aeon is MIT licensed, and the root package.json carries "license": "MIT" alongside a description that is unusually candid about the build. The root is not an npm workspace. There is no workspaces key, so nothing hoists or dedupes, and each package under apps/ keeps its own lockfile and its own toolchain pins. The description states that the dashboard is on typescript@6, the mcp-server is on typescript@7, and the CLI borrows the dashboard's node_modules on purpose.

That choice has a direct cost at upgrade time. Because install order matters, the root provides a bootstrap script that must be run once, and it installs the apps in the order the CLI's borrow requires: dashboard and cli with npm ci, then mcp-server and webhook with npm install --no-audit --no-fund. Running the apps out of order is the kind of mistake that produces confusing module resolution errors rather than a clear message. The root scripts for lint, typecheck, build, and test fan out across the apps, and note that lint and test cover apps/webhook while typecheck and build do not, which is worth knowing before you trust a green root run as full coverage.

On licence implications, MIT is permissive and places few conditions on reuse, but it says nothing about the terms of the nine harnesses you connect. Those are separate services with their own pricing and acceptable-use terms, and Aeon's licence does not extend to them. That is a factual boundary, not legal advice; if the combination matters to your organisation, the harness terms are the ones to read.

Editorial conclusion

Adopt Aeon if you already live in GitHub Actions, want scheduled work to run without you, and are comfortable giving an agent write access to a repository you own. Do not adopt it if every agent action needs human review before it lands, or if you cannot keep a public fork alive, since the README asks for a public copy so Actions minutes stay free. Before switching anything on, verify which API keys a skill declares in its requires frontmatter, check whether that skill runs in write mode, and confirm the harness you authenticated supports the model you intend to pay for.

Frequently asked questions

Official sources

1. aeonfun/aeon on GitHub
2. License: MIT
3. Project website
4. README
5. Releases