aeon - agent guide

aeon is an open-source, MIT-licensed autonomous agent framework. You give it a direction and it leverages 81 skills to get the work done, running unattended on GitHub Actions with self-healing loops, reactive triggers, and persistent memory.

What an agent should know

• aeon is a framework you fork and run, not a hosted API or SaaS - no public REST endpoint to call.
• The unit of work and integration is a skill: a SKILL.md with a schedule and when-to-use guidance.
• Two files steer the agent: SOUL.md (voice) and STRATEGY.md (intent - one metric, a few priorities, hard limits); every skill reads both before it acts.
• Every run is scored 1-5 by Claude Haiku; skills that fail repeatedly are diagnosed and patched automatically.

When to use aeon

• Scheduled briefs, digests, and changelogs
• Continuous monitoring (markets, onchain activity, GitHub repos, mentions)
• Autonomous code work (PR reviews, vulnerability scanning and disclosure)
• Social and BD automation (drafting posts, replies, outreach radar)
• Self-evolving fleets (writes new skills, forks into specialised repos)

Fastest path - set aeon up for an operator

If you are a coding agent helping someone start, read and follow the hosted setup skill: https://www.aeon.fun/skills/aeon.md

How to run it

1. Fork the repository: https://github.com/aeonfun/aeon
2. Run ./aeon and authenticate (a GitHub account and an Anthropic/Claude key to start).
3. Pick the skills you want in aeon.yml.
4. Push - GitHub Actions handles scheduling, execution, and notifications via Telegram, Discord, Slack, Email, or Buzz.

Also ships as an installable Claude Code plugin from plugin/ in the source repo.

Reachable API

• Developer hub (API, MCP, CLI, versioning + deprecation policy): https://www.aeon.fun/developers
• OpenAPI 3.1 spec: https://www.aeon.fun/openapi.json (typed for function calling)
• NLWeb /ask (POST a question, or GET ?q=): https://www.aeon.fun/ask
• MCP server (Streamable HTTP, read-only): https://www.aeon.fun/mcp (server card: https://www.aeon.fun/.well-known/mcp.json); to drive a running instance, run the full aeon-mcp server from the repo
• Versioning: v1, URL-path (https://www.aeon.fun/v1/ask); Deprecation+Sunset headers 90+ days ahead of any change

Skills (81)

Core

• aeon-update - Pull framework updates from the upstream Aeon repo into this instance - 3-way merges canon's new commits into a PR, never clobbering operator config.
• auto-merge - Automatically merge open PRs that have passing CI, no blocking reviews, and no conflicts
• auto-workflow - Two-mode aeon.yml workflow builder - analyze inspects URLs and emits a tiered, signal-verified skill-enablement plan plus an aeon.yml diff; enable flips slugs to enabled:true and opens a PR.
• fleet-control - Operate managed Aeon instances from memory/instances.json - health-check, dispatch, and status snapshots (control), plus a fleet scorecard of runs, tokens, cost, and reliability (scorecard).
• fork-fleet - Fork divergence monitor - tracks where the fleet's active forks diverge in CODE (unique commits, new/modified skills) and CONFIG (enable/var/model/schedule vs upstream), gated on real change.
• heartbeat - Ambient fleet-health check that surfaces anything worth attention (default), or an on-demand priority brief - the 3 things to focus on, why now, and what moved (var=brief)
• memory-flush - Promote important recent log entries into MEMORY.md and prune stale ones
• narrative-convergence - Cross-skill signal detector - finds entities or themes surfaced independently by 3+ different skill categories within 48h and surfaces them as high-confidence write opportunities
• shiplog - Recap of everything shipped since the last run - cross-repo PRs, security fixes, star deltas, and X traction, synthesized into a digest article and a ready-to-post shiplog in your voice.
• soul-builder - Build a SOUL from an X handle - read a wide sample of a public X account, then draft SOUL.md (identity, worldview, opinions), STYLE.md (voice), and examples so every skill speaks in that voice.
• spawn-instance - Clone this Aeon agent into a new GitHub repo - fork, configure skills, validate, and register in the fleet
• strategy-builder - Draft STRATEGY.md from a goal - read the operator's brief (goal, repo, links) plus the repo README and memory, then write a tight north-star/priorities/audience/constraints strategy.

Basics

• action-converter - 5 concrete real-life actions, leverage-scored against open loops with specificity and anti-fluff gates
• article - Write a publication-ready article in one of three angles - a trending long-form piece, a watched-repo thesis, or a project-through-a-lens essay. Optional Replicate hero image with --visual.
• bd-radar - Business-development radar across your product family - find who's building, forking, integrating, and mentioning your products, ranked into a who-to-talk-to-this-week lead list.
• digest - Generate and send a digest on a configurable topic, optionally pulling RSS/Atom feeds as an input source alongside web + X signal.
• executor-mcp - Run a task through your Executor Cloud tool catalog - one MCP endpoint proxying every integration you connected (MCP servers, OpenAPI specs, GraphQL APIs), with per-tool allow/approve/block policies. OAuth Connect via the dashboard MCP panel.
• fetch-tweets - Search and curate X/Twitter behind one selector - keyword, topic roundup, a single or tracked-account digest, an X list, or the AI-agent buzz preset - clustered into signal-scored sub-narratives.
• github-trending - Curated trending across GitHub repos and the Hugging Face Hub (models, datasets, spaces) - filtered, clustered, and labeled by momentum with a one-line why-notable per pick.
• glim-mcp - Live-data research via the glim.sh MCP - web search, full page extraction, X/Twitter, Reddit, GitHub, Amazon, and YouTube transcripts - synthesized into a cited digest. Pay-per-call from the connected account balance; OAuth Connect via the dashboard MCP panel.
• idea-forge - Three-mode idea engine - generate collides the week's zeitgeist with what you can ship into scored wedges; validate viability-screens the idea backlog; memo writes evidence-backed startup memos.
• last30 - Cross-platform social research - narrative-first intelligence on what people are saying about a topic across Reddit, X, HN, Polymarket, and the web over the last 30 days.
• pr-review - Review open PRs two ways - default is a per-PR deep review with severity-tagged findings, inline comments, and a verdict; --survey runs a risk-tiered triage digest of what's safe to merge first.
• price-alert - Fire when the tracked token does something - new ATH, sharp 1h move, or operator-set target crossed. Silent on normal days.
• skill-article - Turn any skill in this instance into a publish-ready launch article - proof-stat headline, one contrarian thesis, mechanics, war stories from real run history, a mental-model reframe, and the full SKILL.md embedded verbatim so readers can steal it. Optional Higgsfield title banner with --banner.
• token-movers - Crypto market scanner and single-token analyst - movers scans top winners/losers/trending or on-chain runners with pump-risk flags; single-token produces a verdict-first deep report for one token.
• tx-explain - Decode any Base transaction into a plain-English story - method, token movements, swaps/approvals, counterparties, and suspicious-approval flags. Keyless via Base RPC + Etherscan v2.
• video-script - Turn a repo, product page, or update into a recording-ready video script in a receipts-first format - verifies every claim against live sources, then writes timestamped VO + on-screen direction with a plain-language glossary, assets checklist, anti-tells, and a verify-before-recording list.
• write-tweet - Multi-format tweet studio - standalone drafts (10 across 5 size tiers), a 5-10 tweet thread, or 10 remixes of past tweets, selected via ${var}.
• you-web-search - Web search using You.com Search API with high-quality, cited results and optional real-time web crawling.

Crypto & Markets

• base-mcp - Access a Base Account via the Base MCP server (mcp.base.org) - wallet, portfolio, sending, swapping, signing, x402 payments, batched calls, and transaction history.
• compute-resell - Autonomous compute-reselling agent on Surplus Intelligence - resells free or low-cost provider compute across Bankr, AWS Bedrock, and Google Vertex (GCP) as one skill. Reads the live market + your cost + your usage, auto-lists your models per enabled provider, and reactively prices each offer to win routing within a cost floor, cap, and health guardrails.
• cortx-reliability - Check whether an x402 payment endpoint is reliably delivering value before spending USDC on it. Returns paid delivery rate, active incidents, latency, and a clear proceed/warn/block recommendation.
• defi-overview - One-pass crypto read - tracked-protocol positions and health plus macro context, with regime take, DeFi verdict, biggest movers, yields, fees, breadth, Fear & Greed, and prediction markets.
• deploy-uni-hook - "Generate, simulate, audit, and deploy a Uniswap v4 hook + test pool from a brief, on any Uniswap v4 chain (every testnet and mainnet) - pre-audited templates or a from-scratch freeform hook (flags auto-derived; static audit + dangerous-pattern scan + a behavioral forge test + fork sim gate the deploy). Dry-run by default; explicit arm: to broadcast; testnet default, mainnet behind a double opt-in; records the deploy to main. Every deployed hook inherits a mandatory 10 bps AeonFee protocol fee."
• distribute-tokens - Two-phase contributor rewards - plan builds a tier-priced payout from the repo's merged-PR ranking; send executes it on-chain via Bankr Wallet API with per-recipient idempotency and dry-run.
• finance-district-mcp - Multichain non-custodial agent wallet via Finance District - check balances, prices, and best DeFi yields, move funds, swap, and make x402 paid API calls across EVM, Solana, Bitcoin, and Sui. Keys never leave a secure enclave (TEE); spend caps are enforced at the wallet. OAuth Connect via the dashboard MCP panel.
• investigation-report - One-shot Base-token investigation - runs any subset of six onchain-security checks (rug-scan, contract-audit, deployer-trace, holder-concentration, honeypot, lp-lock) into one verdict. Keyless core.
• miroshark-matchday - Friday bulk football matchday simulations on MiroShark - pay $1 USDC per sim via x402 (Finance District agent wallet), launch Premier League, Serie A, and La Liga matchday sims in parallel, collect share links and full reports, and render or hand off one video per sim.
• monitor-polymarket - Monitor Polymarket and/or Kalshi prediction markets for 24h price moves, volume changes, fresh comments, and high-conviction alerts.
• narrative-tracker - Track rising, peaking, and fading crypto/tech narratives with quantitative mindshare + velocity signals and explicit positioning calls.
• onchain-monitor - Monitor blockchain addresses and contracts for notable activity.
• picks-tracker - Retrospective on past token and prediction market picks - what hit, what flopped, what the score is.
• pm-manipulation - Detect suspected manipulation on prediction markets over the past 3 days by cross-referencing price/volume/comment anomalies with multilingual local-press coverage.
• robinhood-mcp - Read your Robinhood Agentic brokerage account via the Robinhood Trading MCP - portfolio, buying power, positions, and order history - and place a single operator-instructed trade. OAuth Connect via the dashboard MCP panel.
• submit-hook - "Submit a deployed Uniswap v4 hook to the public univ4-hooks registry - format the listing, open a PR (issue fallback) so it lists on the hook marketplace."
• taskmarket-delegate - Delegate work to the TaskMarket agent-worker market - browse open tasks, create tasks with explicit authorization, and track/submit work, so an agent can outsource instead of burning inference on unreliable or low-confidence work.
• token-pick - One token recommendation and one prediction market pick - scored, quantified, with a skip branch when signals are weak.
• unlock-monitor - Token unlock and vesting tracker - quantify supply pressure via absorption ratio, classify cliff vs linear, and deliver one-line market reads.

Dev & Code

• changelog - Generate a user-facing changelog from recent commits/PRs across watched repos - write it in-repo (Keep a Changelog format) or open a cross-repo changelog PR on a docs/marketing repo.
• deploy-prototype - Generate a small app or tool and deploy it live to Vercel via API.
• feature - Build, enhance, or revive GitHub repos - ship one feature PR per watched repo (watched), make the best single enhancement on one external repo (external), or revive the top dormant repo (dormant).
• github-monitor - Watch your GitHub repos across four views - a combined urgency monitor (stale PRs, new issues, releases), a new-issue triage queue, a release upgrade digest, or your own opened-PR tracker.
• inbox-triage - Daily GitHub notification inbox triage - surfaces aging vuln PR replies, security advisories, review requests, and mentions that need action.
• posthog-errors - Weekly cross-project error overview from PostHog - enumerates every project the OAuth grant covers, pulls the last 7 days of error-tracking issues per project, ranks them by impact, flags what's new vs ongoing, and sends one digest with per-project totals, the top issues, and a clickable link to a full committed report of every issue.
• pr-triage - First-touch triage for external pull requests - verdict, label, and a welcoming comment within minutes of open.
• rightstack - Use RightStack as a read-only Web3 stack advisor for architecture recommendations, workflow inspection, tool comparisons, and package-migration checks. Use for planning; do not treat corpus output as implementation proof.
• seo-audit - Daily on-page and technical SEO audit of every page on a site - discovers URLs from the sitemap, scores each page, adds cross-page checks (duplicate titles, canonicals, sitemap gaps), diffs against yesterday, and sends the score line plus any regressions.
• spend-watch - Autonomous cloud-cost analyst across Neon, Vercel, Railway and GitHub Actions - pulls per-object usage, attributes it to the biggest drivers, root-causes each, and emits recommendations ranked by real signal (idle %, over-allowance, failure rate) with dollar figures only where the billing API returns real ones (and, armed, applies safe cost levers).
• vuln-scanner - Audit trending repos for real security vulnerabilities and disclose responsibly - scan and route findings (PVR / dependency PR), re-submit queued advisories, and send armed email disclosures.
• vuln-tracker - One lifecycle poll over everything vuln-scanner produces - PR and advisory status, PVR triage transitions, and pending-disclosure aging, with a stars-secured impact headline and one action queue.

Productivity

• competitor-monitor - Watch a list of competitor web pages on a cadence - snapshots each page's real signals (pricing, headings, CTAs, new/removed pages, title/description), diffs against the last run, and reports only what actually changed.
• higgsfield - Generate images and video through the Higgsfield MCP - text-to-image, text-to-video, and image-to-video with motion control across 100+ models. Generation draws real credits from the connected Higgsfield account; OAuth Connect via the dashboard MCP panel.
• hunter-22 - Scan the ClawHunter agent bounty marketplace for opportunities that genuinely match this agent's real capabilities (code, security research, writing) and surface only real matches — never a raw unfiltered dump. When a match is real audit-shaped work with a linked GitHub repo, the notification carries a one-tap button to dispatch vuln-scanner at it directly.
• idea-pipeline - Execution-gap audit - cross-references the startup idea backlog against shipped skills, prototypes, and cross-repo PRs, surfacing the top 3 ideas to build next by narrative and operator fit.
• mention-radar - Monitor external web and social mentions of the operator's active projects - surface what people are discovering, where they're confused, and where to engage.
• operator-scorecard - Three recap modes - default synthesizes agent health, community growth, and economic activity into a was-it-worth-it verdict; ops recaps what shipped and failed; push ranks push impact.
• remotion - Render a short (~10s) video on any topic with Remotion - the agent writes a storyboard JSON, a bundled React/Remotion project renders it to an MP4, and the clip is committed to the repo and delivered by URL. No editor, no external generative API.
• reply-maker - Draft copy-paste-ready X replies - two options per reply-worthy tweet from tracked accounts, topics, or lists (default), or ready-to-post responses to engagement opps in recent logs (from-logs).
• schedule-ads - Manage paid ads on AdManage.ai from declarative config - default schedules launches across Meta/TikTok/Snapchat/Pinterest/LinkedIn (always PAUSED); create provisions Meta campaigns and ad sets.
• send-email - Compose and send a one-off email to a named recipient via Resend - written in the operator's voice, then sent in-run through the shared send caps with an operator audit copy.
• weekly-aeoncard - Build a weekly token-consumption recap image from memory/token-usage.csv - this week + all-time totals, top skills, rendered as a shareable SVG card.

Evolution

• aeon-doctor - Static config-correctness linter for this instance - catches the silent-failure class (unquoted schedules, duplicate keys, unconfigured skills, mode typos, broken requires/MCP refs) that no run-based health skill can see. Notifies only on problems.
• autoresearch - Evolve a skill by generating variations, evaluating them, and updating the best version.
• create-skill - Generate a complete new skill from a one-line prompt and ship it as a PR.
• install-skill - Install a community skill pack into this fork from a GitHub repo and ship it as an auto-merged PR.
• pack-submit - Package one of this agent's own skills as a standalone community pack and submit it to the aeon registry as a PR.
• search-skill - Search the open agent skills ecosystem for skills that fill a real gap and install them via the native add-skill path.
• self-improve - Improve the agent itself, or audit its recent performance - better skills, prompts, workflows, and config, plus a quality/reliability/memory-hygiene review of what it did and what failed.
• skill-health - Fleet skill observability with two views - health audits per-skill metrics and files/resolves issues in memory/issues/; analytics ranks the fleet by 7d runs, success rates, and anomaly flags.
• skill-repair - Diagnose and fix failing or degraded skills automatically - systemic-first triage, per-category playbooks, and a verification plan.