---
title: "aeon docs - how aeon works"
description: "The whole aeon docs guide as one markdown document."
canonical: "https://www.aeon.fun/docs"
---

# aeon docs - how aeon works

> Markdown twin of https://www.aeon.fun/docs, generated from the live docs pages. Whole-site
> summary: https://www.aeon.fun/llms.txt. Skill catalog: https://www.aeon.fun/docs/llms.txt.

# Get Started (https://www.aeon.fun/docs)

Launch your own autonomous Aeon agent repo on GitHub Actions from the browser, a coding agent, or your terminal.

Every setup path ends the same way: your own Aeon repository on GitHub ([`aeonfun/aeon`](https://github.com/aeonfun/aeon)), running unattended on your own GitHub Actions. The browser onboarding at [Aeon Connect](/connect) is the fastest path and needs no local clone or terminal.

## In the Browser (Aeon Connect)

Open [Aeon Connect](/connect) and sign in with GitHub to launch an agent in about five minutes. You only need a GitHub account and a model credential (a Claude subscription, an API key, or a provider login).

### Sign in with GitHub
[Aeon Connect](/connect) requests only the permissions required to provision and control your agent repository.

### Create your Aeon repo
Name your repository (default `aeon-<login>`) and choose **Public** or **Private**. Aeon Connect creates it in your account and enables GitHub Actions automatically.

### Install the GitHub App
Install the [Aeon Connect GitHub App](https://github.com/apps/aeon-connect) on your new repository only. It receives scoped `Actions`, `Contents`, `Secrets`, `Variables`, and `Workflows` permissions on that single repo.

### Connect a model
Paste a Claude subscription token (`claude setup-token`), an API key, a ChatGPT (Codex) login, or use one-click OpenRouter. Credentials are stored directly in your repo's encrypted GitHub Actions secrets.

### Pick skills and run
Enable your first skills, optionally connect Telegram, Discord, Slack, or email notifications, and trigger a test run. From then on, the scheduler runs your skills on cron.

> **You own everything:** Your repository, your keys, your GitHub Actions, and your git-committed memory stay in your account. [Aeon Connect](/connect) stores no model keys and never hosts your runtime - it provides the dashboard and remote MCP server (`https://www.aeon.fun/connect/mcp`).

## From a Coding Agent

Paste one line into Claude Code, Codex, Hermes, or OpenClaw. Your agent reads the hosted setup skill at [`https://www.aeon.fun/skills/aeon.md`](https://www.aeon.fun/skills/aeon.md) and either opens [Aeon Connect](/connect) or runs `./aeon init` locally:

```text
read https://www.aeon.fun/skills/aeon.md and follow the instructions to set up your aeon agent
```

## From the Terminal

Requires Node.js 20+ and the GitHub CLI (`gh auth login`):

```bash
git clone https://github.com/aeonfun/aeon && cd aeon
./aeon init   # creates your repo, connects GitHub, a model, and Telegram
./aeon        # opens the local dashboard on http://localhost:5555
```

If you create a repo manually on [`github.com/aeonfun/aeon`](https://github.com/aeonfun/aeon), click **Use this template** so Actions start enabled (manual GitHub forks start with Actions disabled until you enable them in the **Actions** tab).

## Public vs Private

| Mode | How it is created | Actions minutes & visibility |
| --- | --- | --- |
| **Public** | Fork of [`aeonfun/aeon`](https://github.com/aeonfun/aeon) | Unlimited free GitHub Actions minutes; memory and run logs are public. |
| **Private** | Template copy (`./aeon init --private` or Private in [Aeon Connect](/connect)) | Memory and logs stay private; uses your account's Actions minutes (2,000 free/month on GitHub Free). |

---

# Architecture (https://www.aeon.fun/docs/architecture)

How Aeon uses a single GitHub repository and GitHub Actions runners as a zero-infrastructure agent runtime.

Aeon is a GitHub repository ([`aeonfun/aeon`](https://github.com/aeonfun/aeon)) paired with a Next.js control plane (hosted at [Aeon Connect](/connect) or run locally via `./aeon`). Git is the database and GitHub Actions is the compute layer - there is no server, daemon, or external database to maintain.

## Three Surfaces

1. **Dashboard** - configures skills, schedules, and secrets either in the browser at [Aeon Connect](/connect) or locally at `http://localhost:5555` (`./aeon`).
2. **Repository** - holds markdown skills (`skills/`), agent identity (`CLAUDE.md`, `STRATEGY.md`, `soul/`), git-committed memory (`memory/`), and schedules (`aeon.yml`).
3. **Actions Runners** - throwaway GitHub Actions VMs that wake on cron, execute due skills through the configured coding-agent harness, score output quality, and commit state back to git.

## Four Key Files

| File | Role |
| --- | --- |
| [`aeon.yml`](https://github.com/aeonfun/aeon/blob/main/aeon.yml) | Enabled flags, cron schedules, `var` inputs, model/harness overrides, chains, and reactive triggers. |
| [`CLAUDE.md`](https://github.com/aeonfun/aeon/blob/main/CLAUDE.md) | Standing agent instructions loaded on every run; imports `STRATEGY.md`, `memory/MEMORY.md`, and `soul/`. |
| [`catalog/skills.json`](https://github.com/aeonfun/aeon/blob/main/catalog/skills.json) | Machine-readable skill registry generated from each `SKILL.md` by `bin/generate-skills-json`. |
| [`.github/workflows/scheduler.yml`](https://github.com/aeonfun/aeon/blob/main/.github/workflows/scheduler.yml) | Cron workflow that ticks every 5 minutes and dispatches due skills. |

## Control Plane

Locally, `apps/dashboard/` shells out to `gh` for `/api/*` calls (secrets, workflows, config). It is loopback-gated by default and supports `AEON_DASHBOARD_ALLOWED_HOSTS` for Tailscale with strict same-origin checks.

In the browser, [Aeon Connect](/connect) serves the same interface multi-tenant by calling GitHub through the [Aeon Connect GitHub App](https://github.com/apps/aeon-connect) using short-lived installation tokens scoped to your repository.

## Repository Layout

```text
aeon/
├── CLAUDE.md                        # agent identity & standing rules
├── STRATEGY.md                      # operator north-star brief
├── aeon.yml                         # schedules, chains, reactive triggers
├── ./aeon                           # local dashboard + CLI launcher
├── ./notify                         # multi-channel notification dispatcher
├── catalog/
│   ├── skills.json                  # generated skill catalog
│   └── packs.config.json            # first-party pack definitions
├── bin/
│   ├── onboard                      # validate instance setup
│   ├── add-skill                    # import skills from GitHub
│   └── generate-skills-json         # regenerate catalog files
├── skills/
│   └── <skill-name>/SKILL.md        # one prompt file per skill
├── apps/
│   ├── dashboard/                   # local Next.js UI
│   ├── cli/                         # headless CLI
│   ├── mcp-server/                  # local stdio MCP server
│   └── webhook/                     # Cloudflare Worker for instant Telegram
├── memory/
│   ├── MEMORY.md                    # goals, active topics, pointers
│   ├── cron-state.json              # per-skill run metrics & scores
│   └── issues/                      # structured failure tracker
└── .github/workflows/
    ├── aeon.yml                     # skill runner + Haiku quality scorer
    ├── chain-runner.yml             # multi-step skill chain executor
    ├── scheduler.yml                # 5-minute cron dispatcher
    └── messages.yml                 # inbound Telegram/Discord/Slack router
```

---

# Skills (https://www.aeon.fun/docs/skills)

How Aeon skills are structured as single SKILL.md prompt files with frontmatter metadata, inputs, and blast-radius capabilities.

Every Aeon skill is a folder under [`skills/`](https://github.com/aeonfun/aeon/tree/main/skills) containing a single `SKILL.md` prompt file - no boilerplate code or class hierarchy. Browse all live skills and their individual install commands on the [Skills catalog](/skills) page.

## Six Categories

| Category | Focus | Examples |
| --- | --- | --- |
| **Core** | Fleet coordination, liveness, memory, and self-configuration | [`heartbeat`](/skills/heartbeat), [`memory-flush`](/skills/memory-flush), [`spawn-instance`](/skills/spawn-instance), [`aeon-update`](/skills/aeon-update) |
| **Basics** | Daily digests, research briefs, X drafting, and web search | [`digest`](/skills/digest), [`article`](/skills/article), [`write-tweet`](/skills/write-tweet), [`fetch-tweets`](/skills/fetch-tweets) |
| **Crypto** | On-chain monitoring, DeFi analytics, prediction markets, and v4 hooks | [`onchain-monitor`](/skills/onchain-monitor), [`monitor-polymarket`](/skills/monitor-polymarket), [`deploy-uni-hook`](/skills/deploy-uni-hook) |
| **Dev** | Security scanning, smart contract audits, PR triage, and shipping | [`vuln-scanner`](/skills/vuln-scanner), [`sc-audit`](/skills/sc-audit), [`feature`](/skills/feature), [`pr-triage`](/skills/pr-triage) |
| **Productivity** | Inbox triage, competitor tracking, media generation, and scorecards | [`mention-radar`](/skills/mention-radar), [`competitor-monitor`](/skills/competitor-monitor), [`remotion`](/skills/remotion) |
| **Evolution** | Self-healing, diagnostics, skill authoring, and autonomous research | [`aeon-doctor`](/skills/aeon-doctor), [`skill-health`](/skills/skill-health), [`skill-repair`](/skills/skill-repair), [`self-improve`](/skills/self-improve) |

See [`docs/CORE.md`](https://github.com/aeonfun/aeon/blob/main/docs/CORE.md) for how `core` and `evolution` combine to make the agent self-directing.

## Anatomy of a Skill

Each `SKILL.md` combines YAML frontmatter (schedule defaults, category, required secrets, and capabilities) with a markdown prompt:

```markdown
---
name: digest
description: Generate and send a digest on a configurable topic
metadata:
  title: Digest
  mode: write
  category: basics
  var: ""
  tags: [content, news]
  requires: [XAI_API_KEY?]
---

# Digest

Produce a <=300-word digest from recent signals: top items on the topic,
why they matter, and what changed since the last run.

## Inputs
- memory/MEMORY.md      -> current goals
- memory/topics/*.md    -> tracked topics
- output/.chains/*.md   -> upstream chain outputs (if any)

## Output
- A single ./notify call with the brief
- An entry appended to memory/logs/$(date +%F).md
```

## The `var` Input

Every skill accepts a single `var` string parameter in `aeon.yml` (or at dispatch time), interpreted per skill:
- **Research / Basics** - topic or query (`var: "rust"`)
- **Dev / Security** - target repository (`var: "owner/repo"`)
- **Crypto** - token, chain, or protocol (`var: "solana"`)
- **Empty (`""`)** - falls back to the skill's built-in defaults and `STRATEGY.md`

## Adding a Skill

1. **From the catalog:** `bin/add-skill aeonfun/aeon token-movers monitor-polymarket` (`--list` browses, `--all` installs all).
2. **From a starter template:** `bin/new-from-template <template> <skill-name> --category <category>` using the templates in [`docs/examples/skill-templates/`](https://github.com/aeonfun/aeon/tree/main/docs/examples/skill-templates).
3. **Hand-written:** Add `skills/<your-skill>/SKILL.md`, run `bin/generate-skills-json` and `bin/generate-packs-json`, register with `eyebrow scan`, and add an entry in `aeon.yml`.

## Capabilities Taxonomy

Every skill declares a blast-radius hint in frontmatter (`capabilities: [...]`), checked in CI by [`ci-capabilities-parity.yml`](https://github.com/aeonfun/aeon/blob/main/.github/workflows/ci-capabilities-parity.yml) and documented in [`docs/CAPABILITIES.md`](https://github.com/aeonfun/aeon/blob/main/docs/CAPABILITIES.md):

| Capability | Meaning |
| --- | --- |
| `read_only` | No repo writes, external mutations, on-chain calls, or notifications. |
| `external_api` | Authenticated read call to a third-party HTTP API. |
| `writes_external_host` | Mutating request (`POST`/`PUT`/`DELETE`/`PATCH`) to an external service. |
| `onchain_writes` | Signs and broadcasts blockchain transactions. |
| `agent_messaging` | Posts or replies publicly on social or chat platforms. |
| `sends_notifications` | Calls `./notify` to message the operator's own channels. |

## Onchain Evidence

[`onchain-monitor`](/skills/onchain-monitor) rechecks the last observed block hash. If a reorg changes it, the monitor rewinds a safety window and replays observations before alerting, deduplicating transactions across runs. Completed watches write a hashed receipt under `memory/evidence/`; the alert includes its path and digest.

Verify a saved receipt from your instance repo without RPC or API access:

```bash
node scripts/verify-onchain-evidence.mjs memory/evidence/<file>.json
```

The checker validates the SHA-256 digest, schema, ranges, counters, block hashes and sorted transaction hashes, and rejects secret-like fields and credential-bearing URLs. Exit code `0` means internally consistent, `1` means invalid, and `2` means the file argument was omitted. A receipt is not a signature or proof that an RPC was honest or a block final.

## Full Skill Catalog

Browse all skills with live schedules, required secrets, and one-line install commands at [`/skills`](/skills) or inspect the raw JSON registry at [`catalog/skills.json`](https://raw.githubusercontent.com/aeonfun/aeon/main/catalog/skills.json).

---

# Scheduling (https://www.aeon.fun/docs/scheduling)

Configure UTC cron schedules, execution order, dependencies, and per-skill model overrides in aeon.yml.

All skill schedules live in [`aeon.yml`](https://github.com/aeonfun/aeon/blob/main/aeon.yml) using standard 5-field UTC cron syntax.

## Configuration Shape

```yaml
model: claude-sonnet-5-5

skills:
  article:
    enabled: true               # flip to true to activate
    schedule: "0 8 * * *"       # daily at 08:00 UTC
  digest:
    enabled: true
    schedule: "0 14 * * *"
    var: "solana"               # input passed to this skill
  token-movers:
    enabled: true
    schedule: "30 12 * * *"
    model: "claude-opus-5-5"    # per-skill model override
  heartbeat:
    enabled: true
    schedule: "0 8 * * *"       # ambient health check, listed last by convention
```

## Scheduler Rules

- **Parallel dispatch:** [`.github/workflows/scheduler.yml`](https://github.com/aeonfun/aeon/blob/main/.github/workflows/scheduler.yml) ticks every 30 minutes at off-peak minutes (`11,41 * * * *`) by default and dispatches every due skill in parallel.
- **Dependency ordering:** Skills that declare `depends_on:` in their frontmatter wait for upstream skills to complete first.
- **Heartbeat fallback:** [`heartbeat`](/skills/heartbeat) is the only skill enabled out of the box and sits last in `aeon.yml` by convention.
- **Tunable tick cadence:** On private repositories where GitHub Actions minutes are metered, adjust the cron in `.github/workflows/scheduler.yml` to off-peak slots like `7 * * * *` (hourly) or `7,22,37,52 * * * *` (every 15 min).

## Model Selection

Set a default model at the top of `aeon.yml` and override individual skills as needed:
- `claude-sonnet-5-5` - default for routine execution and monitoring.
- `claude-opus-5-5` - deep reasoning, security audits, and code generation.
- `claude-haiku-5-5` - post-run 1-5 quality scoring and lightweight transforms.

Per-skill `model:` and `harness:` overrides in `aeon.yml` can be written on their own keys or as single-line inline flow maps with quoted values.

---

# Memory (https://www.aeon.fun/docs/memory)

How Aeon persists agent state, daily logs, topic notes, failure issues, and run metrics as git-committed files.

Aeon stores all state as plain Markdown and JSON files inside [`memory/`](https://github.com/aeonfun/aeon/tree/main/memory), read at the start of a run and committed back to git on exit.

## Five Memory Layers

| Path | Purpose | Retention |
| --- | --- | --- |
| `memory/MEMORY.md` | Curated index of goals, active topics, and file pointers | Long-lived, kept under 8 KB |
| `memory/topics/*.md` | Deep notes split out by topic | Long-lived |
| `memory/logs/YYYY-MM-DD.md` | Append-only daily activity log across all skills | Permanent |
| `memory/issues/ISS-NNN.md` | Structured failure reports opened by health skills | Until `resolved` |
| `memory/skill-health/*.json` | Rolling 30-run quality scores and error flags per skill | Rolling 30 runs |

## Operating Rules

- **Read on entry:** Every skill reads `memory/MEMORY.md` first to align with current goals and active topics.
- **Log on exit:** Skills append a summary entry to `memory/logs/$(date +%F).md`.
- **Promote details:** Once a topic outgrows a few lines in `MEMORY.md`, details move into `memory/topics/<name>.md`.
- **Automatic compaction:** [`memory-flush`](/skills/memory-flush) promotes durable facts from daily logs into `MEMORY.md` with `[source: ...]` citations, prunes stale entries, and skips execution when no logs have changed.

## `cron-state.json`

The state reducer orders events by their parsed timestamp instant, including UTC offsets, and breaks equal-time ties deterministically. Event input order therefore cannot change the latest status or consecutive failure count.

`memory/cron-state.json` tracks per-skill run counts, consecutive failures, success rates, and the latest quality score. [`heartbeat`](/skills/heartbeat), [`skill-health`](/skills/skill-health), and [reactive triggers](/docs/reactive) read this file to detect regressions:

```json
{
  "digest": {
    "last_status": "success",
    "last_success": "2026-05-28T07:00:21Z",
    "total_runs": 30,
    "total_successes": 29,
    "consecutive_failures": 0,
    "success_rate": 0.97,
    "last_quality_score": 4
  },
  "monitor-polymarket": {
    "last_status": "failed",
    "last_failed": "2026-05-28T06:45:08Z",
    "total_runs": 9,
    "total_failures": 2,
    "consecutive_failures": 2,
    "success_rate": 0.78,
    "last_quality_score": 1,
    "last_error": "api_error: 429 rate_limited"
  }
}
```

---

# Self-Healing (https://www.aeon.fun/docs/self-healing)

How Aeon scores every skill output 1-5, tracks degradation, files internal issues, and opens automated fix PRs.

After every skill run, Haiku scores its output 1-5 (`1` = failed or empty, `5` = clean) and records diagnostic flags (`api_error`, `stale_data`, `rate_limited`) into `memory/skill-health/` as a rolling 30-run history.

## Four Self-Healing Skills

### `heartbeat` - the sentinel
[`heartbeat`](/skills/heartbeat) runs daily and is the only skill enabled by default. Inspects `memory/cron-state.json` for failures, stalled PRs, and missed schedules; logs `HEARTBEAT_OK` when clean and notifies you when action is needed.

### `skill-health` - the auditor
[`skill-health`](/skills/skill-health) analyzes the rolling 30-run score history for quality degradation and files structured issues in `memory/issues/`.

### `skill-repair` - the mechanic
[`skill-repair`](/skills/skill-repair) diagnoses a failing skill (`SKILL.md`, run logs, and filed issue) and opens a targeted fix pull request. Fires automatically after 3 consecutive failures when reactive triggers are enabled.

### `self-improve` - the evolver
[`self-improve`](/skills/self-improve) makes one small, targeted refinement per run based on recent score history rather than rewriting skills wholesale.

> **Enabling full self-healing:** Turn on [`skill-health`](/skills/skill-health), [`skill-repair`](/skills/skill-repair), and the `consecutive_failures >= 3` [reactive trigger](/docs/reactive) in `aeon.yml`.

## Issue Lifecycle

Issues live in `memory/issues/ISS-NNN.md` with structured YAML frontmatter (`status`, `severity`, `root_cause`, `fix_pr`). Health skills open issues (`status: open`), and repair skills transition them to `resolved` once the fix PR lands.

## PR Governance

- **[`pr-review`](/skills/pr-review) (`--survey`)** - buckets open PRs by risk tier (`core-review`, `infra-review`, `skill-pass`, `fast-track`) and only re-notifies when a riskier PR arrives.
- **[`auto-merge`](/skills/auto-merge)** - merges green PRs that pass the safety policy (allowlisted paths, `<=500` changed lines, `CLEAN` merge state, no opt-out labels), capped at 3 merges per run.

---

# Skill Chains (https://www.aeon.fun/docs/chains)

Compose multi-step pipelines in aeon.yml where parallel upstream skills feed outputs into downstream consumers.

Skill chains pass outputs between skills without an external orchestrator, executing as sequential and parallel workflow steps via [`.github/workflows/chain-runner.yml`](https://github.com/aeonfun/aeon/blob/main/.github/workflows/chain-runner.yml).

## Defining a Chain

Declare chains under the `chains:` key in [`aeon.yml`](https://github.com/aeonfun/aeon/blob/main/aeon.yml):

```yaml
chains:
  digest-pipeline:
    schedule: "0 7 * * *"
    on_error: fail-fast                       # or: continue
    steps:
      - parallel: [token-movers, github-trending]
      - skill: digest, consume: [token-movers, github-trending]
```

## How a Chain Executes

### Step dispatch
`parallel:` steps fan out concurrently; sequential `skill:` steps wait for prior steps to finish.

### Output capture
Each completed step writes its markdown output to `output/.chains/<skill>.md`.

### Downstream injection
Steps that declare `consume: [...]` receive the listed upstream `output/.chains/<skill>.md` files directly in their prompt context.

### Error handling
`on_error: fail-fast` aborts the chain on the first failed step; `on_error: continue` runs downstream steps with whatever upstream outputs succeeded.

---

# Reactive Triggers (https://www.aeon.fun/docs/reactive)

Fire skills automatically on runtime conditions in cron-state.json such as consecutive failures or status changes.

While cron schedules handle fixed times, reactive triggers fire skills with `schedule: "reactive"` whenever runtime conditions in `memory/cron-state.json` match.

## Defining Triggers

Add a `reactive:` block to [`aeon.yml`](https://github.com/aeonfun/aeon/blob/main/aeon.yml) (shipped commented out by default so self-repair stays opt-in):

```yaml
reactive:
  skill-repair:
    trigger:
      - { on: "*", when: "consecutive_failures >= 3" }
  autoresearch:
    trigger:
      - { on: "skill-health", when: "last_status = success" }
```

## Trigger Conditions

- **`on: "*"`** matches any skill in `cron-state.json`; pass a specific slug (e.g. `on: "skill-health"`) to watch one skill.
- **`when:`** supports three predicates evaluated on each scheduler tick:
  - `consecutive_failures >= N`
  - `success_rate <op> X` (where `X` is `0.0` to `1.0`)
  - `last_status = <value>` (`success` or `failed`)
- Reactive skills do not need a cron expression - the scheduler dispatches them as soon as their condition matches.

---

# Strategy (https://www.aeon.fun/docs/strategy)

Align every skill run to a single north-star metric, ranked priorities, audience, and hard constraints in STRATEGY.md.

[`STRATEGY.md`](https://github.com/aeonfun/aeon/blob/main/STRATEGY.md) is the operator's brief at the repository root. Imported into `CLAUDE.md` via `@STRATEGY.md`, it sits in context on every run so skills prioritize the same goal without per-skill prompt edits.

## The Five Fields

Keep `STRATEGY.md` concise so it costs minimal tokens on each run:

```markdown
# Strategy

## North-star metric
> Weekly active teams - not signups.

## Priorities          # most important first, cap at ~5
1. Correct, verifiable work over work that looks finished.
2. Depth on core projects over broad, shallow coverage.
3. Surface signal early - don't sit on a decision.

## Audience
> Technical founders, short on time.

## Hard constraints    # lines never to cross
- Never publish secrets or unverified claims as fact.
- Stay within configured spend and rate limits.

## Optimize for / avoid
- Optimize for: signal, correctness, the priorities above.
- Avoid: filler, hype, busywork, anything off-strategy.
```

## Wiring into `CLAUDE.md`

`CLAUDE.md` pulls `STRATEGY.md` in with a single `@STRATEGY.md` import:

```markdown
## Strategy

STRATEGY.md is the operator's north-star - overarching goal,
priorities, audience, and hard constraints. Read it at the start
of every task and align your output to it; when a choice isn't
otherwise determined, let the strategy break the tie.

@STRATEGY.md
```

> **Unconfigured by default:** New instances ship `STRATEGY.md` with neutral defaults and a `Status: unconfigured defaults` line. Remove that status line once you customize the file, or run [`strategy-builder`](/skills/strategy-builder) to draft one.

## Strategy vs Soul

- **`STRATEGY.md`** sets **intent** (what to work on, prioritize, or skip) and loads on **every** run.
- **[`soul/`](/docs/soul)** sets **voice** (how to write) and loads only when producing human-facing output.

---

# Soul (https://www.aeon.fun/docs/soul)

Give your Aeon agent a distinct writing voice using soul/SOUL.md, STYLE.md, and calibration examples.

By default Aeon writes in a flat, direct, neutral tone. Adding files under `soul/` gives your agent a specific voice across every notification, report, and social draft.

## Directory Hierarchy

```text
soul/
├── SOUL.md                # identity, worldview, opinions, background
├── STYLE.md               # sentence structure, vocabulary, anti-patterns
├── examples/              # 10-20 calibration samples
│   ├── good-tweets.md
│   ├── good-replies.md
│   └── bad-outputs.md
└── data/                  # raw source material (browse only, never copy-paste)
    ├── x-export.json
    ├── blog-posts.md
    └── transcripts.md
```

## Wiring into `CLAUDE.md`

`CLAUDE.md` instructs skills to check `soul/` before writing any human-facing output:

```markdown
## Voice

If soul/ files exist, read them before writing any notification
or output - to match the operator's voice. Skip if the soul
directory is empty or absent.

Soul file hierarchy (read in this order):
- soul/SOUL.md       - identity, worldview, opinions, background
- soul/STYLE.md      - sentence structure, vocabulary, anti-patterns
- soul/examples/     - calibration material (good + bad outputs)
- soul/data/         - raw source material; browse, don't copy-paste
```

> **Specificity test:** A `SOUL.md` only works when its opinions are specific enough that a competitor would disagree with them. If anyone in your field could sign the same `SOUL.md`, make it sharper.

## Building with `soul.md`

Use the [`aeonfun/soul.md`](https://github.com/aeonfun/soul.md) companion repository or the built-in [`soul-builder`](/skills/soul-builder) skill: drop raw posts or transcripts into `soul/data/` and run `/soul-builder` to synthesize `SOUL.md`, `STYLE.md`, and calibration examples.

---

# Authentication (https://www.aeon.fun/docs/auth)

Power Aeon runs via Claude subscription OAuth, Anthropic API keys, eight LLM gateways, and cross-repo GitHub PATs.

Aeon authenticates to Claude through two direct credentials or eight optional LLM gateways. Set one secret in your repository (via [Aeon Connect](/connect), `./aeon init`, or GitHub Settings); each run auto-resolves the active provider from whichever secret is present.

## Ten Supported Providers

| Provider (`gateway.provider`) | Type | Secret Name | Notes |
| --- | --- | --- | --- |
| **Claude subscription** (`claude`) | Direct | `CLAUDE_CODE_OAUTH_TOKEN` | Included in Claude Pro / Max (`claude setup-token`) |
| **Anthropic API** (`anthropic`) | Direct | `ANTHROPIC_API_KEY` | Pay-as-you-go per token at [`console.anthropic.com`](https://console.anthropic.com) |
| **OpenRouter** (`openrouter`) | Gateway | `OPENROUTER_API_KEY` | Anthropic-native passthrough via [`openrouter.ai`](https://openrouter.ai) |
| **Bankr** (`bankr`) | Gateway | `BANKR_LLM_KEY` | Discounted Opus access via [`bankr.bot`](https://bankr.bot) |
| **UsePod** (`usepod`) | Gateway | `USEPOD_TOKEN` | Solana token marketplace via [`usepod.ai`](https://usepod.ai) |
| **Venice** (`venice`) | Gateway | `VENICE_API_KEY` | Privacy-first inference via [`venice.ai`](https://venice.ai) |
| **Surplus** (`surplus`) | Gateway | `SURPLUS_API_KEY` | USDC-settled via [`surplusintelligence.ai`](https://surplusintelligence.ai) |
| **Grok / xAI** (`grok`) | Gateway | `XAI_API_KEY` | Anthropic-compatible passthrough to [`api.x.ai`](https://x.ai) |
| **GLM / Z.AI** (`glm`) | Gateway | `GLM_API_KEY` | Z.AI Coding Plan passthrough to [`z.ai`](https://z.ai) |
| **HivemindOS** (`hivemindos`) | Gateway | `HIVEMINDOS_CREDIT_TOKEN` | Credit-balance billing without a separate provider account |

## Claude Subscription OAuth

For Claude Pro or Max subscribers, generate a 1-year setup token locally and paste it into **Connect a model** in [Aeon Connect](/connect) (or let `./aeon init` save it):

```bash
claude setup-token
# opens browser -> prints sk-ant-oat01-... (valid 1 year)
```

## Gateway Auto-Resolution

`aeon.yml` defaults to `gateway: { provider: auto }`. On each run, Aeon checks secrets in this order:

```text
claude (CLAUDE_CODE_OAUTH_TOKEN) -> anthropic (ANTHROPIC_API_KEY) ->
openrouter -> bankr -> usepod -> venice -> surplus -> grok -> glm -> hivemindos -> direct (fallback)
```

Override the resolution order with `GATEWAY_ORDER`, or pin a specific provider in `aeon.yml` (`gateway: { provider: openrouter }`). See [`docs/CONFIGURATION.md#llm-gateways`](https://github.com/aeonfun/aeon/blob/main/docs/CONFIGURATION.md#llm-gateways) for full gateway details.

## Cross-Repo GitHub Access

The default `GITHUB_TOKEN` is scoped to your Aeon repository only. For skills that inspect or open PRs on external repositories ([`github-monitor`](/skills/github-monitor), [`pr-review`](/skills/pr-review), [`feature`](/skills/feature), [`vuln-scanner`](/skills/vuln-scanner)), store a **classic** Personal Access Token as `GH_GLOBAL` with `repo` and `workflow` scopes. Skills automatically fall back to `GITHUB_TOKEN` when `GH_GLOBAL` is unset.

---

# Harnesses (https://www.aeon.fun/docs/harnesses)

Run skills across nine coding-agent CLIs including Claude Code, Grok, Codex, Pi, Vibe, Kimi, fx, Cursor, and Hermes.

While an [LLM gateway](/docs/auth#auth-gateways) swaps the model endpoint behind Claude Code, a **harness** swaps the entire coding-agent CLI that executes your skill. Aeon ships nine harnesses behind [`harness-adapter/run-harness`](https://github.com/aeonfun/aeon/blob/main/docs/harnesses.md), all returning the same `{result, usage, session_id}` contract.

## Selecting a Harness

Set the default harness at the top of `aeon.yml`, override per skill (single-line flow map), or pick one at dispatch time in [Aeon Connect](/connect):

```yaml
harness: claude          # global default: claude | grok | codex | pi | vibe | kimi | fx | cursor | hermes

skills:
  digest: { enabled: true, schedule: "0 9 * * *", harness: "grok" }
```

## Supported Harnesses

| Harness ID | CLI | Auth Secrets / Fallbacks |
| --- | --- | --- |
| `claude` | Claude Code (`claude -p`, default) | `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, or any [LLM gateway](/docs/auth) |
| `grok` | Grok Build (`grok -p`) | `GROK_CREDENTIALS` (`grok login --device-auth`) or `XAI_API_KEY` |
| `codex` | OpenAI Codex CLI (`openai/*`) | Native ChatGPT login (`CODEX_AUTH`) or `OPENROUTER_API_KEY` |
| `pi` | Pi Coding Agent (`deepseek/*`) | Native key or `OPENROUTER_API_KEY` |
| `vibe` | Mistral Vibe (`mistralai/*`) | `MISTRAL_API_KEY` or `OPENROUTER_API_KEY` |
| `kimi` | Moonshot Kimi (`moonshotai/*`) | Native Kimi login or `OPENROUTER_API_KEY` |
| `fx` | Vercel [`fx.sh`](https://fx.sh) | `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` (no OpenRouter fallback) |
| `cursor` | Cursor CLI (`agent -p`) | `CURSOR_API_KEY` (no OpenRouter fallback) |
| `hermes` | Nous Portal Hermes | `HERMES_AUTH` or `OPENROUTER_API_KEY` |

## Grok Authentication & Run-Shaping

Grok Build (`grok`) authenticates directly via `GROK_CREDENTIALS` or `XAI_API_KEY` and logs token counts and cost to `memory/token-usage.csv`. Optional `SKILL.md` frontmatter keys shape Grok runs (ignored by other harnesses):

```yaml
max_turns: 120      # agentic-turn cap (default 60)
best_of_n: 3        # run 3 ways in parallel and keep the best
verify: true        # append a self-verification pass before finishing
effort: high        # low | medium | high | xhigh | max
```

## Cross-Harness Parity

| Surface | Behavior across harnesses |
| --- | --- |
| **Standing instructions** | Reads `CLAUDE.md` and generated `AGENTS.md` (carrying `STRATEGY.md`). |
| **Read-only mode** | Enforced by the Linux `bwrap --ro-bind` OS sandbox in `run-harness`. |
| **MCP servers** | Project `.mcp.json` is expanded with `${VAR}` secrets before launch (except `pi`, which disables MCP). |
| **Chains & scoring** | Inbound chat replies, skill chains, and the post-run quality scorer work across all nine harnesses. |

Full harness reference: [`docs/harnesses.md`](https://github.com/aeonfun/aeon/blob/main/docs/harnesses.md).

---

# Notifications (https://www.aeon.fun/docs/notifications)

Fan out skill outputs to Telegram, Discord, Slack, Email, and Buzz, and trigger skills via Telegram commands.

[`./notify`](https://github.com/aeonfun/aeon/blob/main/notify) queues messages during a skill run and dispatches them post-run to every configured channel, silently skipping unconfigured ones.

## Supported Channels

| Channel | Outbound Secrets | Inbound (Talk Back) Secrets |
| --- | --- | --- |
| **Telegram** | `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` | Same (offset-based polling or webhook) |
| **Discord** | `DISCORD_WEBHOOK_URL` | `DISCORD_BOT_TOKEN` + `DISCORD_CHANNEL_ID` |
| **Slack** | `SLACK_WEBHOOK_URL` | `SLACK_BOT_TOKEN` + `SLACK_CHANNEL_ID` |
| **Email** | `RESEND_API_KEY` + `NOTIFY_EMAIL_TO` | - |
| **Buzz** | `BUZZ_PRIVATE_KEY` + `BUZZ_CHANNEL_ID` | - |

## Inbound Priority

When [`.github/workflows/messages.yml`](https://github.com/aeonfun/aeon/blob/main/.github/workflows/messages.yml) is enabled, pending inbound messages are processed in priority order (`Telegram > Discord > Slack`), with per-channel read state (Telegram update offset, Discord/Slack reaction acks) preventing duplicate runs.

## Telegram Commands & Buttons

Structured Telegram interactions are handled by a router with **no LLM in the loop**, making commands and button taps instant and free:
- **Slash commands:** Every enabled skill registers as `/skill-name <var>` (e.g. `/token-movers solana`).
- **Inline buttons:** Notifications include `Run again` and `Schedule weekly` buttons; alert skills add `Snooze` and `Mute`.
- **Deep links:** `https://t.me/<bot>?start=<skill>__<arg>` triggers a skill from any link.
- **Force-reply follow-ups:** Skills can prompt a question and route your Telegram reply straight back into the next run.

Full reference: [`docs/telegram-commands.md`](https://github.com/aeonfun/aeon/blob/main/docs/telegram-commands.md).

## Telegram Instant Mode

Default polling runs every 5 minutes. For ~1-second responses, deploy the Cloudflare Worker in [`apps/webhook/`](https://github.com/aeonfun/aeon/blob/main/docs/telegram-instant.md) or enable **Instant replies** under `Settings -> Credentials -> Telegram` in the dashboard.

## `json-render` Feed

In local dashboard mode, skills emit structured specs into `apps/dashboard/outputs/` for live rendering. In GitHub Actions, `./notify-jsonrender` converts markdown output into the same spec via Haiku.

---

# MCP (https://www.aeon.fun/docs/mcp)

Drive your Aeon agent from ChatGPT, Claude, or Cursor via the remote Aeon Connect MCP server or local stdio tools.

Aeon skills work outside GitHub Actions too - drive your agent remotely from ChatGPT, Claude, or Cursor through [Aeon Connect](/connect), or expose skills locally over stdio MCP.

## Remote MCP (Aeon Connect)

[Aeon Connect](/connect) serves a Streamable HTTP MCP server at `https://www.aeon.fun/connect/mcp` (also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/fun.aeon%2Faeon/versions/latest) as `fun.aeon/aeon`). Sign in with GitHub via OAuth to list and trigger skills, inspect run status, read outputs and `memory/`, toggle skills, and send feedback (`send_feedback`). Execution still runs on your own GitHub Actions and model keys never pass through chat.

```bash
# Claude Code
claude mcp add --transport http aeon https://www.aeon.fun/connect/mcp
# Codex CLI
codex mcp add aeon --url https://www.aeon.fun/connect/mcp
# Gemini CLI
gemini mcp add --transport http aeon https://www.aeon.fun/connect/mcp
# VS Code
code --add-mcp '{"name":"aeon","type":"http","url":"https://www.aeon.fun/connect/mcp"}'
```

For read-only documentation queries without signing in, point any MCP client at the public docs server at [`https://www.aeon.fun/mcp`](https://www.aeon.fun/mcp).

## Install the Aeon Plugin

The plugin for Claude Code and Codex bundles the operator console, the hosted MCP connection and a `get-started` onboarding skill from version 0.2.0:

```text
# Claude Code
/plugin marketplace add aeonfun/aeon
/plugin install aeon@aeon
# Codex
codex plugin marketplace add aeonfun/aeon
codex plugin add aeon@aeon
```

Sign in with GitHub and choose your agent repo. Onboarding checks the connection, shows enabled skills and missing key names, then offers a first `heartbeat` run and reads its result. Setup changes require confirmation. The connection never reads or writes secret values, and switching reaches only other Aeon repos you allowed when connecting.

## Local Stdio MCP

Register your local clone's skills as `aeon-<name>` tools in Claude Desktop or Claude Code:

```bash
bin/add-mcp                # build and register local stdio MCP server
bin/add-mcp --desktop      # print Claude Desktop config snippet
bin/add-mcp --build-only   # compile without registering
bin/add-mcp --uninstall    # remove registration
```

See [`docs/examples/mcp/test_connection.py`](https://github.com/aeonfun/aeon/blob/main/docs/examples/mcp/test_connection.py) for a working stdio client example calling `aeon-token-movers`.

## Consuming External MCP Servers

Skills can also act as MCP clients during a run. For example, [`base-mcp`](/skills/base-mcp) connects to the Base MCP server (`https://mcp.base.org`) to read balances and execute approved swaps across partner plugins (Morpho, Moonwell, Uniswap, Avantis, Virtuals, Aerodrome, Bankr).

## One-Click OAuth Connect

OAuth-protected upstream MCP servers connect through a browser PKCE flow in the dashboard: tokens are captured server-side into encrypted repository secrets and refreshed before each run. Supported one-click connectors:
- **Base** ([`base-mcp`](/skills/base-mcp))
- **Robinhood** ([`robinhood-mcp`](/skills/robinhood-mcp))
- **Executor** ([`executor-mcp`](/skills/executor-mcp))
- **glim** ([`glim-mcp`](/skills/glim-mcp))
- **Finance District** ([`finance-district-mcp`](/skills/finance-district-mcp))
- **PostHog**, **Higgsfield** ([`higgsfield`](/skills/higgsfield)), and **Flovia** ([`flovia`](/skills/flovia))

> **Token rotation requires GH_GLOBAL:** OAuth refresh tokens rotate on every use. Because default `GITHUB_TOKEN` cannot write updated repository secrets, set `GH_GLOBAL` (or `GH_SECRETS_PAT`) so rotated refresh tokens persist across runs.

---

# Fleet (https://www.aeon.fun/docs/fleet)

Fork specialized Aeon agent instances for crypto, research, or DevOps and coordinate them without sharing secrets.

A single Aeon instance can spawn and coordinate specialized child instances (e.g. crypto monitoring, security scanning, community ops) while keeping secrets isolated per repository.

## Three Fleet Skills

| Skill | Role |
| --- | --- |
| [`spawn-instance`](/skills/spawn-instance) | Creates a new specialized fork in your GitHub account from a short brief. |
| [`fleet-control`](/skills/fleet-control) | Coordinates and monitors the child instances you own via `memory/instances.json`. |
| [`fork-fleet`](/skills/fork-fleet) | Tracks public community forks running across GitHub. |

## Spawning an Instance

Configure [`spawn-instance`](/skills/spawn-instance) in `aeon.yml` or dispatch it on demand with a specialization brief in `var`:

```yaml
skills:
  spawn-instance:
    enabled: true
    schedule: "workflow_dispatch"
    var: "crypto-tracker: monitor DeFi protocols and token movements"
```

- Forks the repository into a new GitHub repo under your account and enables only the skills matching the `var` brief.
- Registers the child repo in `memory/instances.json` so [`fleet-control`](/skills/fleet-control) can track its health.
- **Secrets never propagate:** each spawned repository starts with an empty secret store so credentials stay isolated by instance.

## Framework Updates

[`aeon-update`](/skills/aeon-update) brings shipped framework changes into forks and private copies through one reviewable PR at a time. Its new `baseline_sha` stays on the PR branch until you merge it. Closing the PR unmerged keeps the old baseline, so the next run can offer the changes again; while a sync PR remains open, another sync exits with `AEON_UPDATE_PR_OPEN`.

The skill uses `scripts/aeon_update.py plan` for a read-only comparison and `apply` on its sync branch for file updates, validation and catalog regeneration. Files that fail validation are held as conflicts. Logs and run output stay out of the sync commit. See the [skill instructions](https://github.com/aeonfun/aeon/blob/main/skills/aeon-update/SKILL.md) for report mode and reset options.

Concurrent run pushes also retry GitHub's inline `cannot lock ref ... is at ... but expected ...` rejection when another run advances the branch. Authentication, hook and unrelated remote failures still stop immediately.

---

# Skill Packs (https://www.aeon.fun/docs/packs)

Group built-in skills by domain and install security-scanned community skill packs from third-party repositories.

Skill packs keep your dashboard focused on the domains you actually run. **First-party packs** act as a visibility lens over built-in skills, while **community packs** install third-party skill bundles after an automated security scan.

## First-Party Packs

Every instance ships all built-in skills, showing **Core**, **Evolution**, and **Basics** by default and grouping the rest into domain packs. Enabling a first-party pack reveals its skills in the UI (each skill still has its own `enabled` toggle):

| Pack | Default Visibility | Focus |
| --- | --- | --- |
| **Core** | Always on | Fleet coordination, self-configuration, liveness, and memory. |
| **Evolution** | Shown by default | Self-improvement loop that authors, evaluates, and repairs skills. |
| **Basics** | Shown by default | Daily digests, articles, X posts, and web research starters. |
| **Dev & Code** | Opt-in pack | PR/issue triage, code review, deploys, security scanning, and cost audits. |
| **Crypto & Markets** | Opt-in pack | Token, DeFi, and prediction-market monitoring plus on-chain forensics. |
| **Productivity** | Opt-in pack | Routines, idea pipelines, competitor tracking, email, and media generation. |

The pack registry is generated by `bin/generate-packs-json` (see [`docs/skill-packs.md`](https://github.com/aeonfun/aeon/blob/main/docs/skill-packs.md)).

## Community Packs

Third-party skill collections live in their own GitHub repositories and can be installed with one click from the dashboard's **Packs** tab or via the CLI:

```bash
bin/install-skill-pack --list                        # browse catalog/skill-packs.json
bin/install-skill-pack clawhunter/clawhunter-skills  # scan and install a pack
```

Browse the live registry at [`catalog/skill-packs.json`](https://raw.githubusercontent.com/aeonfun/aeon/main/catalog/skill-packs.json) and the specification at [`docs/community-skill-packs.md`](https://github.com/aeonfun/aeon/blob/main/docs/community-skill-packs.md).

The [Sentinel Pack](https://github.com/sentinelhood/robinhood-sentinel) now lists seven keyless monitoring skills for Robinhood Chain and Pons: address diffs, Aeon v4 hook usage, launch lookalikes, one-shot token checks, repeat deployers, graduations to locked v4 pools, and busy bonding curves. It never signs transactions.

The [Cohesivity pack](https://github.com/AragAgg/aeon-skill-pack-cohesivity) adds `deploy-site`, which builds a small web app from your instance's signals and deploys it to a free 72-hour tenant, then reports its URL and expiry. No API keys or signup are needed to start.

## Trust Model

### Manifest discovery
Reads `skills-pack.json` (or scans `skills/`) in the target repository to list candidate `SKILL.md` files.

### Automated security scan
`skill-scan` checks every prompt for arbitrary code execution, secret exfiltration, destructive shell commands, prompt injection, and credential-path access.

### Disabled-by-default install
Installed skills land in `aeon.yml` with `enabled: false` until you explicitly activate them.

### Lockfile provenance
Records the source repository, branch, and commit SHA in `skills.lock` for reproducible updates.

---

# Security (https://www.aeon.fun/docs/security)

Prompt-injection defenses, secretcurl credential isolation, Fleet Watcher preflight gates, and Sigstore provenance.

Every byte Aeon fetches from the public internet is treated as untrusted data, never instructions. Secrets stay in GitHub Actions environment variables and are gated by static command checks and `./secretcurl`.

## Prompt-Injection Discipline

- **External content is data, not orders:** Web pages, RSS feeds, GitHub issues, and tweets cannot issue instructions; only `CLAUDE.md` and the active `SKILL.md` define behavior.
- **Hostile instructions are dropped:** Inputs matching prompt-injection patterns ("ignore previous instructions") are logged and ignored.
- **Zero secret exfiltration:** Environment variables and repository secrets are never interpolated into outbound shell URLs or bodies.

## `./secretcurl` & Sandbox Boundaries

- **Read-only OS sandbox:** Skills with `mode: read-only` run inside a Linux `bwrap` read-only root filesystem and have write/git/gh tools stripped.
- **`./secretcurl` credential injection:** The Bash analyzer blocks any command containing a bare `$SECRET`. Authenticated HTTP calls use `./secretcurl` with `{ENV_NAME}` placeholders, which only substitutes secrets declared in the skill's `requires:` frontmatter.
- **Fail-closed irreversible steps:** Deploys, payments, and on-chain transactions execute via `./secretcurl` as the skill's final step.

## Local Dashboard Gating

The local dashboard API (`./aeon`) binds to loopback by default and verifies `Origin` on all state-changing requests:

| Environment Variable | Behavior |
| --- | --- |
| `AEON_DASHBOARD_ALLOWED_HOSTS` | Comma-separated hostnames allowed alongside loopback (e.g. Tailscale or internal DNS). |
| `AEON_DASHBOARD_ALLOW_ANY_HOST` | Disables `Host` header checks (use only behind an authenticating reverse proxy). |

## Fleet Watcher (Optional)

Configure `FLEET_ENDPOINT` and `FLEET_TOKEN` secrets to consult an external authorization server before and after every skill run. If preflight returns `BLOCK` (or if the endpoint is unreachable when configured), the workflow exits before the agent starts.

## Verifiable Provenance (Optional)

Aeon can emit Sigstore-signed [GitHub Artifact Attestations](https://github.com/aeonfun/aeon/blob/main/docs/attestation.md) binding a run's output bytes to the exact repository, workflow, and commit SHA on the public Rekor transparency log (verifiable via `gh attestation verify`).

## Langfuse Observability (Optional)

Set `LANGFUSE_*` secrets to stream traces, tool calls, priced token usage, and quality scores out-of-band to [Langfuse](https://github.com/aeonfun/aeon/blob/main/docs/langfuse.md) without slowing down skill runs.

---

# Cost (https://www.aeon.fun/docs/cost)

Run a public Aeon instance with zero extra infrastructure cost using free GitHub Actions minutes and a Claude subscription.

A public Aeon repository on a free GitHub account, authenticated with an existing Claude Pro or Max subscription (`CLAUDE_CODE_OAUTH_TOKEN`), costs **$0 in extra infrastructure**.

## Why Public Instances Are Free

- **Unlimited public Actions minutes:** GitHub provides unlimited free Actions minutes for public repositories on standard runners.
- **Zero hosting overhead:** No VPS, no managed database, and no background daemon - only Git, GitHub Actions, and your model credential.

## Private Repository Minutes

If you create a **Private** copy (in [Aeon Connect](/connect) or via `./aeon init --private`) to keep your `memory/` and logs private, runs draw from your GitHub account's monthly Actions quota:

| GitHub Plan | Included Minutes / Month | Overage Rate (Linux) |
| --- | --- | --- |
| **Free** | 2,000 | N/A |
| **Pro / Team** | 3,000 | $0.008 / min |

## Levers to Reduce Usage

1. **Widen the scheduler tick:** Change the cron in [`.github/workflows/scheduler.yml`](https://github.com/aeonfun/aeon/blob/main/.github/workflows/scheduler.yml) from `*/5` to `*/15` or `0 *`.
2. **Disable unused skills:** Any skill with `enabled: false` in `aeon.yml` consumes zero minutes and zero tokens.
3. **Tier models by task:** Keep `claude-sonnet-5-5` as the default, reserve `claude-opus-5-5` for deep reasoning skills, and let Haiku handle post-run scoring.
4. **Audit token spend:** Inspect `memory/token-usage.csv` or enable [`spend-watch`](/skills/spend-watch) to spot high-burn skills.

---

# ADK (https://www.aeon.fun/docs/adk)

Build multi-tenant dashboards, agent products, and installable skill packs on top of Aeon using GitHub as the API.

The **Aeon Developer Kit (ADK)** defines how to build products on top of Aeon - multi-tenant dashboards, vertical agent apps, or skill packs where users own their own instance. Because every Aeon operation maps to a file or GitHub API call, **GitHub is the backend API**.

## Two Ways to Build

1. **Drive instances via a GitHub App** - dispatch skills, provision encrypted secrets, and read outputs across user repositories using per-request installation tokens. [Aeon Connect](/connect) is the production reference implementation.
2. **Ship your product as a skill pack** - package domain skills into a repository with a `skills-pack.json` manifest (see [Skill Packs](/docs/packs)) so any operator can install your product in one command.

See the full permission matrix, OAuth flow, and tenant-isolation contract in [`docs/ADK.md`](https://github.com/aeonfun/aeon/blob/main/docs/ADK.md).

## Ecosystem Catalog

Aeon maintains three public registries in [`aeonfun/aeon`](https://github.com/aeonfun/aeon):

| File | Contents |
| --- | --- |
| [`docs/ECOSYSTEM.md`](https://github.com/aeonfun/aeon/blob/main/docs/ECOSYSTEM.md) | Products, agents, and tools built on or extending Aeon (mirrored live at [`/ecosystem`](/ecosystem)). |
| [`docs/SHOWCASE.md`](https://github.com/aeonfun/aeon/blob/main/docs/SHOWCASE.md) | Architecture comparisons between Aeon and other agent frameworks. |
| [`catalog/skill-packs.json`](https://github.com/aeonfun/aeon/blob/main/catalog/skill-packs.json) | Community skill packs installable via `bin/install-skill-pack`. |

To list your project on [`/ecosystem`](/ecosystem), open a PR appending a row (`Logo | Project | Links`) to [`docs/ECOSYSTEM.md`](https://github.com/aeonfun/aeon/blob/main/docs/ECOSYSTEM.md).
