aeon

Files (8)

• SKILL.md
• ci.md · references/
• history-mining.md · references/
• layout.md · references/
• mcp.md · references/
• secrets.md · references/
• skill-anatomy.md · references/
• mine-history.mjs · scripts/

SKILL.md (first lines)

# Aeon

Aeon is an agent that runs on the user's own GitHub repo via Actions. A skill is a Markdown file (`skills/<name>/SKILL.md`); `aeon.yml` says which ones run and when.

Pick the mode they're asking for:

| | |
|---|---|
| **1 · Start** | No instance yet, or set one up from scratch |
| **2 · Reschedule** | Change times, cadence, or what a skill focuses on |
| **3 · Unblock** | "It didn't run" / "nothing happened" |
| **4 · Chat → skill** | Turn what we just did into a scheduled skill |
| **5 · Edit a skill** | Change what an existing skill does |
| **6 · What to turn on** | Pick skills, browse packs, install more |
| **7 · Strategy & voice** | `STRATEGY.md` and `soul/` - the north star and the tone |
| **8 · Mine history → skill** | "What of my repeated work could Aeon do for me?" - surface it from past coding-agent chats |

## Preflight (every mode)

1. Find the repo: current dir → `gh repo set-default` → ask. Clone it if it isn't local (an instance made with Aeon Connect lives at `github.com/<owner>/<repo>` like any other; no instance yet means Mode 1).
2. **Confirm `gh` points at THEIR instance, before any command that writes.**

   ```bash
   gh repo view --json nameWithOwner -q .nameWithOwner
   ```

   If that prints `aeonfun/aeon` and they aren't working on upstream itself, stop and run `gh repo set-default <owner>/<repo>`. `gh` prefers an `upstream` remote over `origin` when no default is pinned, and every Aeon write (`auth`, `secrets set`, `skills run`, config pushes) is a `gh -R <resolved>` call - so it will cheerfully put their API keys on the upstream repo and dispatch runs there. It looks like success: no error, a real run id, and the skill just never fires on their instance.
3. `gh auth status` - everything routes through `gh`. If it fails, tell them to run `gh auth login` and stop.
4. Use the `./aeon` CLI for all config writes. It preserves comments in `aeon.yml` and validates. Never hand-edit the YAML - with one exception: the CLI cannot *create* an entry for a brand-new skill (see Mode 4 step 4).

**Don't trust "disabled" for a skill you just created.** The read path lists skills from disk and defaults a missing `aeon.yml` entry to `enabled: false`, so "not configured" and "disabled" look identical. One command tells them apart:

```bash
comm -23 <(ls skills/*/SKILL.md | cut -d/ -f2 | sort) \
         <(grep -oE '^  [a-z0-9-]+:' aeon.yml | tr -d ' :' | sort)
```

Anything it prints is on disk but unconfigured. **Orientation - what's installed, what's on, and where everything lives: `references/layout.md`.**

**Setting any key or token:** read `references/secrets.md` - it has every secret and repo variable with the exact page to get it from. Always set secrets with `./aeon secrets set NAME --stdin`, never as a command argument.

**Handling secrets:** never ask the user to paste a key, token, or private key into the chat, and never echo, log, or commit one. Never read credential files (`~/.ssh`, `.env`, CLI session files) to fill a secret in. The user enters each value themselves, straight into `./aeon secrets set NAME --stdin` or the dashboard's Connect screens.

---

## Mode 1 - Start on Aeon

Goal: one real notification in their phone, fast. Do not configure a schedule first.

> **Fastest start, no terminal: Aeon Connect.** If the user has no terminal, no Node or `gh`, or just wants the quickest path, send them to 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. Nothing else to do: the agent then runs on their own GitHub Actions. Use the terminal path below only if they want a local clone.

> **Want to drive it from a chat app instead?** Once an instance exists, the user can add https://www.aeon.fun/connect/mcp as a connector in ChatGPT, Claude or Cursor (Claude Code: `claude mcp add --transport http aeon https://www.aeon.fun/connect/mcp`). It signs in with GitHub and can run skills, read outputs and memory, and edit strategy and soul. Details: `references/mcp.md`.

1. **Run `./aeon init`.** Ask public or private first (public: Actions minutes are free; private: `--private`, minutes bill against the account quota, 2,000/mo on Free). Then, from a clone of the template:

   ```bash
   git clone https://github.com/aeonfun/aeon && cd aeon
   ./aeon init                 # add --private, --name <repo>, --harness <h> as needed
   ```

   It is idempotent and prints a check or a fix per step: signs in to GitHub with the `workflow` scope, creates `<owner>/<name>` from the template (a template copy starts with Actions on; Aeon Connect forks public instances and turns Actions on itself), points this folder at it (`aeonfun/aeon` stays as the `upstream` remote), runs `gh repo set-default`, enables Actions and lets them open PRs (the default token permission is left as is), offers to store the gh token as `GH_GLOBAL` (only if it has `repo` + `workflow`), connects a model from the credential manifest, and links Telegram with a `/start` deep link. Re-run it any time; `bin/onboard` is the read-only check. `--dry-run` shows every step without changing anything.

   **If they set things up by hand, pin the default repo before any other command.** With an `upstream` remote and no default pinned, **`gh` prefers `upstream` over `origin`**, so secrets and runs silently land on `aeonfun/aeon`. Fix and verify:

   ```bash
   gh repo set-default <owner>/<repo>
   gh repo view --json nameWithOwner -q .nameWithOwner   # must print THEIR repo
   ```

2. **Auth a model** (if `init` skipped it). At least one is required. The choices per harness, in the order the workflow uses them, are in `harness-adapter/harnesses.json` (`credentials`) and the table in `docs/harnesses.md`. Fastest is `./aeon auth --harness claude-code` (Claude Pro/Max, opens a browser), or `./aeon auth --key <key>`, which detects the provider **from the key prefix**: `sk-ant-oat` (OAuth), `sk-or-` (OpenRouter), `bk_` (Bankr), `inf_` (Surplus), `xai-` (Grok); anything else lands in `ANTHROPIC_API_KEY`.

   **UsePod, Venice, GLM and HivemindOS keys have no prefix** and are undetectable, so a bare `--key` files them as a plain Anthropic key and the run fails later with a confusing auth error. They must be named:

   ```bash
   ./aeon auth --key <token> --provider usepod    # same for venice, glm, hivemindos
   ```

   `--dry-run` prints the resolved `method=... -> secret ...` without calling `gh` or `claude`; run it whenever the provider is in doubt.

   **Don't assume they have a Claude subscription:** ten providers work, including OpenRouter, Grok, GLM, and crypto-settled gateways. See "Providers and harnesses".
3. **Wire one channel** (if `init` skipped it). Telegram is the fastest: `./aeon init` asks for the @BotFather token and links the chat for them; by hand it is `./aeon secrets set TELEGRAM_BOT_TOKEN --stdin` and `TELEGRAM_CHAT_ID`. Skip Discord/Slack/email for now; one channel is enough to prove it works.
4. **Run one skill now.** Pick it with Mode 6 - ask what they want handled, propose one - then `./aeon skills run <name>`. Wait for it, then `./aeon runs logs <id>`. They should get a Telegram message.
5. **Only then, schedule it.** `./aeon skills enable <name>` and set a time (see Mode 2).

Good first skills: `digest` (topic briefing), `github-monitor` (their repos), `heartbeat` (already on by default, reports only when something needs attention).

---

## Mode 2 - Reschedule / change the routine

Show them their day as a **timeline in their own timezone**, not a config file:

```
07:00  digest           "solana"
09:00  pr-review        your repos
18:00  heartbeat        health check
```

Build it from `./aeon skills ls --enabled --json`. (`--enabled` matters: plain `ls` prints a `SCHEDULE` column for *disabled* skills too - that's their `aeon.yml` entry, not proof anything fires.) No CLI, or want the raw file? `references/layout.md` has grep-only equivalents. Then take plain-language edits and apply them:

| They say | You do |
|---|---|
| "move the digest to 7am" | `./aeon skills schedule digest "0 6 * * *"` |
| "weekdays only" | `... "0 6 * * 1-5"` |
| "too noisy, twice a week" | `... "0 6 * * 1,4"` |
| "stop the crypto one" | `./aeon skills disable token-movers` |
| "make it about rust instead" | `./aeon skills set digest --var rust` |

Rules:
- **All cron in `aeon.yml` is UTC.** Convert from their timezone, and say so: "7am Paris = `0 6 * * *` UTC (5am in summer - want it pinned to local time?" There is no local-time option, so if DST matters, tell them which half of the year is off by an hour.
- Confirm back the **next 3 fire times in their timezone** after any change.
- `--dry-run` first on anything ambiguous, show the diff, then apply.
- Changes need a push to take effect. The CLI does it; confirm it landed.
- **Then check the entry came out right** - one grep, every time:

  ```bash
  grep '^  <skill>:' aeon.yml
  ```

From aeonfun/aeon, MIT.

More from aeonfun/aeon