Most AI agents have an infra problem. You need a server. You need a daemon. You need to babysit a process that crashes at 3am. Aeon sidesteps all of that — it runs on GitHub Actions, costs nothing for public repos, and if it fails, the next cron tick just retries it.
This post breaks down how it works, how it compares to OpenClaw (the other major Claude Code agent), and how you can use it to build things.
What Aeon Actually Is
Aeon is an autonomous agent built on Claude Code. You fork the repo, configure a YAML file, add some secrets, and GitHub Actions handles the rest. Every few minutes, a cron job wakes up, checks if any scheduled skill matches the current time, and runs it — then commits any output back to the repo.
The core loop is dead simple:
cron tick → check aeon.yml → match a skill → Claude Code runs it → commit output → notify you
No server. No Docker. No daemon. If GitHub Actions is up, Aeon is up.
The Skill System
Everything in Aeon is a skill — a markdown file that tells Claude Code what to do. There are 32 built-in skills across four categories:
Research & Content: digest, article, paper-digest, hacker-news-digest, tweet-digest, reddit-digest, research-brief
Dev & Code: pr-review, github-monitor, issue-triage, changelog, code-health, feature (builds from GitHub issues labeled ai-build)
Crypto / On-chain: token-alert, wallet-digest, on-chain-monitor, defi-monitor
Productivity: morning-brief, weekly-review, goal-tracker, memory-flush, reflect
Each skill is just a SKILL.md file. Enabling one looks like this in aeon.yml:
skills:
digest:
enabled: true
schedule: "0 8 * * *" # daily at 8am UTC
var: "solana" # narrows the topic
The var field is the key abstraction. Every skill interprets it differently — for digest it's a topic, for pr-review it's owner/repo, for token-alert it's a ticker. Leave it empty and each skill falls back to its own defaults.
Aeon vs. OpenClaw
The README is honest about this:
| OpenClaw | Aeon | |
|---|---|---|
| Response time | Real-time (sub-second) | Cron-based (minutes) |
| Infrastructure | Needs a server/daemon | GitHub Actions |
| Cost | Depends on hosting | Free for public repos, ~$2/mo otherwise |
| Failure recovery | Process needs restarting | Next cron tick retries automatically |
| Best for | Interactive agents, chat bots | Background tasks, monitoring, digests |
If you're building something where a user types a message and expects an immediate response, use OpenClaw. If you're building something that runs in the background and surfaces information proactively — digests, PR reviews, on-chain monitoring, changelogs — Aeon is the better fit.
The tradeoff is latency for simplicity. Aeon will never be faster than your cron interval, but it also never needs babysitting.
How It Actually Runs
There are two GitHub Actions workflows:
messages.yml — polls for inbound messages every 5 minutes (Telegram, Discord, Slack) and handles scheduling. You can tune this:
schedule:
- cron: '*/5 * * * *' # default, every 5 min
- cron: '*/15 * * * *' # saves Actions minutes
- cron: '0 * * * *' # hourly, most conservative
aeon.yml — the skill runner. Fires on workflow_dispatch and issues events (for the feature skill's ai-build label integration).
The heartbeat skill runs every 3 hours as a catch-all. It reads recent memory and logs, checks for stalled PRs, flagged items, and skills that haven't run on schedule. If there's nothing to report, it logs HEARTBEAT_OK and exits without committing. If something needs attention, it sends a notification.
The Memory System
Aeon persists state across runs using three files:
-
memory/MEMORY.md— goals, active topics, high-level context -
memory/topics/— detailed notes by topic -
memory/logs/YYYY-MM-DD.md— daily activity logs
Skills like memory-flush promote important log entries into MEMORY.md. reflect consolidates and prunes stale entries. goal-tracker compares recent output against goals defined in MEMORY.md. This gives the agent a kind of long-term context that persists across hundreds of cron ticks.
Authentication
Two options:
Secret What it is Billing
CLAUDE_CODE_OAUTH_TOKEN OAuth token from Pro/Max Included in plan
ANTHROPIC_API_KEY API key Pay per token
For the OAuth token:
claude setup-token # opens browser, prints sk-ant-oat01-... (valid 1 year)
Five-Minute Setup
git clone https://github.com/aaronjmars/aeon
cd aeon && ./aeon
This opens a local dashboard at http://localhost:5555 where you:
- Add your Claude API key or OAuth token
- Set up a Telegram/Discord/Slack channel
- Toggle skills on, set schedules, optionally set a
var - Hit Push — one click commits and pushes config to GitHub
After that, Actions handles it.
What You Can Build With It
Automated research digest
Turn on digest with var: "your topic". Every morning, Aeon searches the web, synthesizes recent developments, and sends you a structured briefing via Telegram.
Self-reviewing PRs
Enable pr-review. Set var: "your-org/your-repo" (or add a GH_GLOBAL personal access token for cross-repo access). Aeon reviews open PRs and posts summary comments automatically.
On-chain monitoring
Enable token-alert or wallet-digest. Set var to a ticker or wallet address. Aeon monitors for price/volume anomalies or notable transactions and notifies you.
AI-driven issue-to-PR pipeline
Label any GitHub issue ai-build. The feature skill fires, Claude reads the issue and the codebase, implements it, and opens a PR. This is the most ambitious use case — basically a junior dev that picks up labeled tickets autonomously.
Custom skills
Skills are just markdown. To add your own:
./add-skill BankrBot/skills --list # browse external skills
./add-skill BankrBot/skills bankr # install specific ones
npx skills find "crypto trading" # search the ecosystem
Or write your own SKILL.md in the skills/ directory. The format is just instructions to Claude Code — describe what the skill should do, what inputs it reads, what it outputs, and what it commits.
Giving Aeon a Voice
By default Aeon has no personality. If you want it to write in your style, there's a soul/ system:
-
soul/SOUL.md— identity, worldview, opinions -
soul/STYLE.md— voice, sentence patterns, tone -
soul/examples/good-outputs.md— 10–20 calibration samples
Add a reference to these at the top of CLAUDE.md and every skill will read and internalize them before running. The README makes a useful point here: soul files work when they're specific enough to be wrong. Vague instructions like "I have a nuanced writing style" don't transfer. Specific ones do.
Cost Reality Check
For most use cases, this is close to free:
| Scenario | Cost |
|---|---|
| No skill matched | ~10s of Actions time |
| Skill runs | 2–10 min depending on complexity |
| Heartbeat (nothing found) | ~2 min |
| Public repo | Unlimited free minutes |
GitHub Pro/Team gives 3,000 free minutes/month. A daily digest + heartbeat running in a private repo will stay well under that. The expensive scenario is running many skills frequently — tune your cron intervals accordingly.
The Two-Repo Strategy
The repo is a public template. The recommended pattern is to run your actual instance as a private fork:
git remote add upstream https://github.com/aaronjmars/aeon.git
git fetch upstream
git merge upstream/main --no-edit
Your memory/, articles/, and personal config don't exist in the template, so merges are clean. You get template updates without conflicts.
One Gotcha to Know
GitHub has two requirements for scheduled workflows to fire:
- The workflow file must be on the default branch — crons on feature branches don't run
- The repo must have recent activity — GitHub disables crons on repos with no commits in 60 days
If you fork and nothing happens: go to Actions → Messages → Run workflow (manual trigger). After one manual trigger, the cron activates automatically.
Bottom Line
Aeon is the right tool if your use case is "run something in the background, tell me when there's something worth knowing." The GitHub Actions infrastructure means zero ops overhead — no server to provision, no process to keep alive, no pager alert when a daemon crashes.
The skill system is genuinely extensible. If you can describe a task in markdown well enough for a senior engineer to execute it, you can turn it into a skill. And the community is already building and sharing skills via the add-skill ecosystem.
Top comments (0)