aya

Personal AI assistant toolkit.

aya is a CLI tool that AI hosts call — sync context between instances, schedule reminders, and manage identity. The workspace (your guild repo) defines how your AI host behaves; aya is the tool it uses.

Why "aya"?

Och, ye might well ask. It started life as assistant-sync — perfectly descriptive, perfectly dull, the kind o' name a committee'd be proud of. Then came helm, which sounded braw and nautical until some wee Kubernetes chart showed up and said "Naw, that's mine."

So there we were, rootin' around for a name, and someone muttered "aya" — and that was that. In the Scots tongue, aya is what ye say when somethin' lands just right. Not a grand "YES" mind ye, more a quiet "aye, that'll do." The kind o' sound a canny person makes when the kettle's found, the fire's lit, and everything's settled where it ought tae be.

That's this tool. Nae fuss. Nae ceremony. Just quietly doin' the job.

Install

# From PyPI (after first release)
uvx aya

# From GitHub — works today, no PyPI required
uvx --from git+https://github.com/shawnoster/aya aya

# From source
git clone https://github.com/shawnoster/aya.git
cd aya
uv sync
# After sync, run commands with `uv run aya`, or install globally:
# uv tool install .

Python 3.14 note: coincurve 21.0.0 does not ship a cp314 wheel, and building from the coincurve 21.0.0 sdist fails with cffi 2.0.0. Use Python 3.12 or 3.13 until this is resolved upstream. For example: uvx --python 3.12 --from git+https://github.com/shawnoster/aya aya

Quick start

# Set up identity on each machine
aya init --label alice       # on Alice's machine
aya init --label bob         # on Bob's machine

# Pair them
aya pair --peer bob          # on Alice's machine — shows a code
aya pair --code WORD-WORD-0000 --peer alice   # on Bob's machine

# Send a packet
aya send --to bob --intent "build notes" --files notes.md
aya send --to bob --intent "quick question" --seed --opener "Which side is canonical?"
aya send --to bob --intent "build notes" -m "## Notes\n\nAll green."

# Check inbox (and ingest trusted senders)
aya receive --auto-ingest --skip-untrusted

# Who am I, and who can I send to?
aya whoami

# Did that actually go out, and to which relays?
aya sent

Labels can be anything — home/work, names, machine hostnames. They're local aliases for the keypair on each side.

Pairing promotes the relay that actually carried the exchange to primary, independently on each side — the initiator promotes the relay the response arrived on, the joiner the relay it found the request on. That relay is proven to reach the peer, so later send/receive calls need no --relay. Relays seeded by aya init (relay.damus.io and nos.lol) stay on as fallbacks.

--relay replaces the configured list rather than narrowing it — --relay X talks to X only, with no fallback if X is down. Pairing is the one case where both machines must pass the same --relay: a request published only to a private relay cannot be found by a peer polling the public defaults. See skills/relay/SKILL.md for the full account.

Identity flags: --as, --label, --peer

Three flags name who you're talking about, and they're easy to confuse:

• --label <name> — used only with aya init, names this machine's local identity (e.g. aya init --label alice registers an instance called alice in the local profile).
• --as <name> — picks which local identity to act as for a command. Omit it and aya resolves the primary instance: an explicit one set via aya use, otherwise the only instance, otherwise the only non-default instance. If the choice is genuinely ambiguous the command fails and lists the candidates rather than guessing — a wrong identity polls an unrelated keypair and looks exactly like an empty inbox. Run aya whoami to see which one is active.
• --peer <name> — names a remote identity (the one you've paired with). Used with aya pair, aya trust, etc.

Quick mnemonic: --label creates a local name, --as selects one, --peer targets a remote one.

Scheduling

aya has its own scheduler, but Claude Code also has a separate cloud-based automation system called CCR (Claude Code Remote). They solve different problems — knowing which to reach for saves a lot of friction.

The one question

Does this task need me, or just need to be done?

If you need to be informed or make a decision → aya schedule. If it can be completed without you → CCR remote trigger.

aya schedule — human in the loop

aya's scheduler runs on your machine. Alerts are delivered at session start via the SessionStart hook — they surface to you in your session context. You read them, decide, act.

Use aya for:

aya watches poll for state and produce alerts. You are the actor.

CCR — human out of the loop

CCR (Claude Code Remote) runs isolated agents in Anthropic's cloud on a cron schedule. The agent clones your repo, does work, and exits — whether you're online or not. Use the schedule skill in Claude Code to create triggers.

Use CCR for:

CCR agents act autonomously. If you want to hear about what they did, wire them to Slack or Gmail via MCP connectors in the trigger.

Choosing between them

Does it need my attention or judgment?
  Yes → aya schedule (watch / remind)

Can it be completed without me?
  Yes → CCR trigger

Does it need to run more often than hourly?
  Yes → aya schedule (any interval via system cron)

Does it need my local files or environment?
  Yes → aya schedule + SessionStart hook

CCR minimum interval is 1 hour. aya can fire at any cron interval.

One-prompt setup

Already have aya installed on another machine? Give Claude Code this prompt on the new machine and it will handle everything:

Install aya (uv tool install aya-ai-assist), initialize identity with aya init --label <LABEL>, then pair with my other instance. If I have a pairing code from the other machine, run aya pair --code <CODE> --peer <OTHER_LABEL> --as <LABEL> and we're done. If not, run aya pair --peer <OTHER_LABEL> --as <LABEL> — this will block waiting for the other machine to join (up to 10 minutes), so give me the short code it displays and immediately run aya pair --code <CODE> on the other machine before the window expires. After pairing, install hooks and crontab with aya schedule install. Finally, add the aya plugin to your shell profile: alias claude='claude --plugin-dir /path/to/aya/.claude-plugin' then confirm the trust exchange with aya whoami (it lists instances and trusted peers; aya status covers workspace readiness, not relay trust).

Replace <LABEL> with a name for this machine (e.g. home, work, laptop, your name), <OTHER_LABEL> with the other machine's label, and <CODE> with the pairing code.

What that prompt does

1. Installs aya globally via uv
2. Creates identity — generates ed25519 + secp256k1 keypairs
3. Pairs instances — exchanges trust via short-lived relay code
4. Installs hooks — aya schedule install wires Claude Code hooks and system crontab automatically
5. Loads the plugin — makes /aya and /relay skills available for managing aya and communicating between instances

Agent integration (Claude Code)

aya is designed to surface alerts and reminders into your agent session, not just on the terminal. One command sets up everything:

aya schedule install          # crontab + Claude Code hooks
aya schedule install --dry-run  # preview first

This installs:

• A system crontab entry (*/5 * * * *) for background polling (watches, reminders, claim sweeping)
• Claude Code hooks for session activity tracking, cron registration, packet receiving, and CI monitoring

To remove everything: aya schedule uninstall.

What the hooks do

How session crons work

aya hook crons is the bridge between aya's persistent scheduler and Claude Code's in-session cron system. On each session start it:

1. Fetches active session-required recurring items (without claiming alerts)
2. Filters by idle back-off and work-hours constraints
3. Outputs a hookSpecificOutput.additionalContext block with explicit CronCreate instructions

The agent reads those instructions and must call CronCreate for each cron before responding. This registers recurring jobs for the session — so a */15 * * * * PR watch fires automatically every 15 minutes without the user having to ask.

Registering a session cron

# Watch a PR — fires every 15 min, Mon–Fri
aya schedule recurring \
  --message "pr123-merge-watch" \
  --cron "*/15 * * * 1-5" \
  --prompt "Check PR #123. If merged, watch staging deploy and notify."

The cron is persisted in aya's scheduler store. On the next session start, aya hook crons picks it up and injects the CronCreate call automatically.

PostToolUse: unified watch

After every shell command, aya polls all due scheduler watches (CI checks, GitHub PRs, Jira tickets) and wakes Claude if any condition fires:

{
  "matcher": "Bash",
  "command": "aya hook watch 2>/dev/null || true",
  "asyncRewake": true
}

After a git push, aya monitors triggered GitHub Actions workflows and wakes the agent if a check fails.

Non-Claude-Code agents

If your host doesn't support hooks, run this manually at the top of each session:

aya schedule pending --format text

This prints all due reminders, alerts, and session cron prompts as plain text. Copy any session cron prompts into your context to pick them up.

Claude Code plugin

aya ships with bundled Claude Code skills in skills/. There are two ways to install them:

Symlink install (recommended): installs skills as slash commands in ~/.claude/commands/:

make link-skills

This creates ~/.claude/commands/aya.md and ~/.claude/commands/relay.md as symlinks pointing into the repo. Run make unlink-skills to remove them. Re-running make link-skills is idempotent — safe to run after updates.

Plugin-dir (dev mode): load the whole plugin directory without symlinking:

alias claude='claude --plugin-dir /path/to/aya/.claude-plugin'

Either method loads aya's bundled skills:

After editing any skill file in the aya repo, run /reload-plugins in your session to pick up changes — no reinstall needed.

Commands

How it works

• Identity: did:key (ed25519) for packet signing + secp256k1 for Nostr transport
• Transport: Nostr relays (NIP-01, kind 5999) — async, federated, self-hostable
• Encryption: NIP-44 v2 (secp256k1 ECDH + ChaCha20 + HMAC-SHA256) — on by default for public relays
• Packets: Signed JSON envelopes with markdown content, TTL, and conflict strategies
• Security: End-to-end encryption, signature verification, user approval before ingest, trust registry

Working on aya

The package is laid out in layers, and dependencies point inward only:

Two rules matter more than the rest, and tests/test_architecture.py fails if either breaks:

• Nothing below adapters/ imports typer, rich or mcp. A use case that can print or exit cannot be reused by the other surface — that is how the CLI and MCP implementations drifted apart in the first place.
• The CLI and the MCP server do not import each other. They are peers over the same use cases, not layers.

New behaviour goes in usecases/; the surfaces parse input and render results. See docs/architecture.md for the full map.

uv sync
uv run pytest                     # ~1000 tests, isolated from your real ~/.aya
uv run ruff check --fix . && uv run ruff format .
uv run mypy src/aya/              # strict, no exclusions

License

MIT