# aeon - agent guide

aeon is an open-source, MIT-licensed autonomous agent framework. You give it a
direction and it leverages 86 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

- The operator **owns everything**: their repo, keys, GitHub Actions and
  memory. Aeon Connect (https://www.aeon.fun/connect) hosts the dashboard and a remote
  MCP server (https://www.aeon.fun/connect/mcp) that drives the operator's own agent;
  there is no hosted runtime and no public REST endpoint to call. Runs happen
  on the operator's own GitHub Actions.
- 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

Send a human to Aeon Connect: https://www.aeon.fun/connect. In the browser they sign in
with GitHub, create their aeon (a public fork or a private copy), install the
Aeon Connect GitHub App on that one repo, connect a model, and pick skills. No
clone or terminal needed.

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. Browser: open https://www.aeon.fun/connect and sign in with GitHub.
2. Create your aeon repo (Public = a fork of https://github.com/aeonfun/aeon with free Actions
   minutes; Private = a copy). Aeon Connect turns GitHub Actions on.
3. Connect a model: a Claude subscription token (`claude setup-token`), an
   API key, or another login. It is stored as an encrypted secret in the repo.
4. Pick skills and run one - GitHub Actions handles scheduling, execution, and
   notifications via Telegram, Discord, Slack, Email, or Buzz.

Terminal instead: `git clone https://github.com/aeonfun/aeon && cd aeon && ./aeon init` (needs
Node.js 20+ and the GitHub CLI); `./aeon` opens the same dashboard locally.

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
- Aeon Connect MCP (drive your own agent, OAuth with GitHub sign-in): https://www.aeon.fun/connect/mcp - list and run skills, follow runs, read output, memory, strategy and soul, toggle skills, install packs. Works in ChatGPT, Claude, Claude Code and Cursor. Claude Code: `claude mcp add --transport http aeon https://www.aeon.fun/connect/mcp`. Local alternative: `bin/add-mcp` in the repo registers the stdio `aeon-mcp` server (apps/mcp-server) with Claude Code or Desktop
- aeon docs MCP (public, read-only, Streamable HTTP): https://www.aeon.fun/mcp (server card: https://www.aeon.fun/.well-known/mcp.json) - searches aeon's docs and skill catalog, cannot touch any instance
- Versioning: v1, URL-path (https://www.aeon.fun/v1/ask); `Deprecation`+`Sunset` headers 90+ days ahead of any change

## Skills (86)

### 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 — runs keyless out of the box; YDC_API_KEY unlocks higher limits and 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

- `anatomy` - Build crafted, highly detailed, interactive isometric SVG figures that explain a technical idea as a real physical object (a test rig, a dial gauge, a cabinet of drawers, a plotter, a lock), with many small precise solid parts, four-tone shading, correct painter's order, a framed card with title, hint and live readout, and calm eased motion. Use this whenever someone wants an isometric illustration, an explanatory diagram or figure for docs, a blog post, a landing page or an article, a "Linear-style" or "premium" technical drawing, an interactive explainer, or an SVG that shows how a system, algorithm or component works, even if they never say "isometric". Works framework-free (TypeScript/JS that writes SVG and HTML) and in React/Next.js, and can add realistic WebGL shaders (fire, exhaust, water, caustics, lamp light) that live inside the drawing in the same isometric perspective.
- `arc-studio` - Drive Circle Arc Studio from a headless runner. Start one Arc testnet turn, poll it on a later run, and notify when it finishes or needs an answer.
- `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.
- `create-prove` - Run a changed Aeon skill for real and attach SHA-bound behavioral evidence to its PR
- `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).
- `feedback-builder` - Point Aeon at a service's /feedback endpoint - pull what agents reported (bugs, missing features), triage and cluster it, then build the best accepted request as a PR for a human to approve.
- `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.
- `sc-audit` - Deep security audit of a smart-contract repo OR a live on-chain contract by address - detect Solidity, model the protocol invariants and trust boundaries first, run Slither (best-effort) plus a bounded agentic pass that hunts for a path breaking each invariant, triage, adversarially verify, prove with a fuzzer, and drive each finding through the shared responsible-disclosure routing. The dedicated contract arm split out of vuln-scanner.
- `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

## Other projects from Aeon Inc

- OpenDia: https://github.com/aeonfun/opendia - connect your browser to AI models
- soul.md: https://github.com/aeonfun/soul.md - the best way to build a personality for your agent
- Minitor: https://github.com/aeonfun/minitor - monitor the current thing. Your dashboard for the internet
- univ4-hooks: https://github.com/aeonfun/univ4-hooks - Uniswap v4 hook registry (https://www.aeon.fun/hooks)

## More

- Docs & full catalog: https://www.aeon.fun/docs
- Architecture: https://www.aeon.fun/architecture
- Machine-readable summary: https://www.aeon.fun/llms.txt
- Source: https://github.com/aeonfun/aeon
- Contact: aaron@aeon.fun