Aeon: An Open-Source AI Agent Framework That Runs on GitHub Actions

I run an agent that writes me a morning brief before I’m out of bed. It tracks the repos I care about and stays quiet on slow days. It pays for the web searches it needs out of its own wallet. It does all of this on a schedule, in GitHub Actions, on a fork of the Aeon public repo. No server. No always-on laptop. No SaaS dashboard charging me by the seat.

This post kicks off a series on why that’s possible, and where Aeon does things other AI agent frameworks can’t — or won’t.

Aeon is an open-source autonomous AI agent framework by @aaronjmars. You fork the repo, drop your config into aeon.yml, set a couple of secrets, and you have an agent running on GitHub Actions runners.

Out of the box it ships with 180+ skills — small units of work the agent can perform. morning-brief. repo-pulse. narrative-tracker. paper-digest. tweet-roundup. Each one is a Markdown file describing what the skill does and how to do it. The agent reads the file at run time. No DSL. No plugin SDK. No compile step. If you can write a prompt, you can write a skill.

The default delivery channel is Telegram. You DM a bot once, your chat ID lands in a secret, and from then on every skill posts its output to your phone. You can also reply to the bot and route messages back into Aeon as triggers. Discord and Slack work the same way.

Three things stand out. The series will work through each in turn.

1. It runs in the background by design — no server, no orchestrator

LangGraph, CrewAI, AutoGen, AutoGPT — they assume a process is already running somewhere. You decide where to host it. You monitor it. You restart it when it dies. Infrastructure first, agent second.

Aeon starts from the opposite end. The unit of deployment is a cron line in YAML. GitHub Actions does the running. The result is a scheduled and reactive flow — you fire skills by cron, by DMing the bot, or by pushing a commit. Failed runs self-heal: the next scheduled tick fires regardless. Your laptop can be closed. The agent is still on.

That sounds small until you have five skills firing every day for a month and realize nothing has paged you, nothing has gone offline, and the only thing you ever maintain is the YAML.

The next article in the series covers this architecture in detail — what changes when “the agent runs while you sleep” stops being a slogan.

2. It can spend money — x402 and Circle agent wallets

Most AI agents are read-only. They fetch, they summarize, they post — but they don’t act in any economic sense. They can’t, because acting in the world usually means an API key, a billing account, a credit card.

Aeon plugs cleanly into Circle’s agent wallet and the x402 protocol. The agent has its own USDC wallet. It can search the x402 bazaar, find a paid API, pay for one call, and use the result — no API key, no bank account, no prefunded billing setup. You set rules: per-transaction caps, daily, weekly, and monthly USDC limits.

What this unlocks in practice:

• Prediction-market odds for a narrative-tracker run.
• Weather data before a “should I drive today” brief.
• Live web search when free APIs rate-limit you.
• Premium feeds for a morning-brief.

The agent decides what’s worth a few cents and pays for it.

Article three covers x402-powered use cases for Aeon in depth.

3. Skills are Markdown files, and they compose

A skill in Aeon is a single Markdown file. That’s the whole interface. You can:

• Fork the upstream catalog and edit any skill in place.
• Write a new one in twenty minutes by copying a similar one and rewriting the spec.
• Chain skills together in aeon.yml — the output of one skill becomes the input of the next.
• Ask Aeon to write a new skill for you. create-skill and self-improve are real skills in the catalog. The agent expands its own surface area.

Everything is in git. Every change is a commit. Every run is a workflow log. You can see exactly what your agent did last Tuesday at 04:00 UTC, why, and what it produced — no observability stack to spin up.

Articles four and five cover the composition story and the receipts-over-vibes story.

Aeon is not a hosted product. Nobody is operating it for you. The bottom rung of the ladder is “fork the repo and read the YAML”. If you’ve never edited a GitHub Actions workflow, that’s the on-ramp.

It doesn’t have a flashy chat UI. The local dashboard at localhost:5555 exists, but you stop opening it after the first day. The interface is your inbox, your Telegram, your repo log.

gh repo fork aaronjmars/aeon --clone
cd aeon
./onboard

The onboard script walks through three secrets — CLAUDE_CODE_OAUTH_TOKEN, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID — runs a verify pass, and dispatches a test skill so you see your first message land on Telegram. Push the resulting aeon.yml, and the schedule starts running on the next cron tick.

Is Aeon free to run?

The framework itself is free and open-source. You’ll pay for GitHub Actions minutes beyond the free tier (the free tier covers most personal use cases) and for the LLM provider behind Claude Code. Optional paid APIs pay themselves through the agent’s x402 wallet.

How does Aeon compare to LangGraph or CrewAI?

LangGraph and CrewAI are libraries you assemble into a running process. Aeon is a deployment pattern — skills as Markdown files, scheduled in YAML, executed by GitHub Actions. You can think of it as “the agent framework where the orchestrator is git + GitHub”.

Do I need to know Python?

No. Skills are Markdown. The agent is Claude Code under the hood. You’ll touch YAML for scheduling and Markdown for skill prompts. Bash and Python show up only inside specific skills that need them.

Can I run Aeon without Telegram?

Yes. Discord, Slack, and Telegram are all supported — pick any, all, or none. With no notification channel configured, skills still run; output lands in the repo as commit artifacts.

Is my data private?

Your fork is yours. Secrets live in GitHub Actions secrets. Skill outputs commit to your repo. The framework doesn’t phone home.

Article 2: The agent that runs while you sleep. The architecture behind background-first agents, and why most frameworks can’t get there without an SRE on call.