Elixir Bot

Retired 2026-09-26. Elixir Bot no longer runs. It was POAP KINGS' clan agent from February to September 2026, and the projects that replaced it grew out of it: Elixir MCP records the game for many clans, elixir-mcp-collector fetches from the API, elixir-mcp-discord is the Discord agent, Elixir Clan handles clan management and awards, and Elixir Drop is the game. The code and history are kept here as they were on the last day. Nothing in this repository is operated or maintained any more; do not restart it.

Elixir is the clan agent for the POAP KINGS Clash Royale clan (#J2RGCRVG). It combines a deterministic data engine, an LLM awareness loop, scoped memory, Discord conversation, and leadership workflows.

AGENTS.md is the source of truth for architecture and repository conventions. SETUP.md is the production operations guide.

System at a glance

Elixir has one external data ingress and one proactive voice:

flowchart LR
    API["Clash Royale API"] --> INGRESS["cr_api.py"]
    INGRESS --> RECEIPTS["append-only API receipts"]
    RECEIPTS --> RAW["deduplicated payload content<br/>14-day analysis buffer"]
    INGRESS --> TICK["atomic materialization generation<br/>apply → derive → manage"]
    TICK --> STREAMS["battle, player, clan,<br/>and war event streams"]
    TICK --> READS["current projections, rollups,<br/>management state + generation id"]
    STREAMS --> AWARE["hourly awareness loop"]
    READS --> AWARE
    AWARE --> PLAN["validated post plan<br/>with hard coverage floors"]
    PLAN --> OUTBOX["durable per-post outbox"]
    OUTBOX --> DISCORD["member-facing Discord lanes"]
    TICK --> ACTIONS["leader action cards"]

• cr_api.py is the only Clash Royale API ingress. Every successful response appends an api_observation_receipts row; identical bodies share one raw_api_payloads content row.
• engine.tick.run_tick records the admitted inputs and commits streams, projections, rollups, readiness, management, and generation status together. Interactive profile/battle-log refreshes use the same generation contract.
• Event streams are durable history. Projections are disposable read models. Current state is never reconstructed from prompts.
• The awareness loop reads one SQLite snapshot identified by data_generation, decides what is worth saying, and is the sole proactive poster. Its whole plan is validated and persisted before send; partial retries skip fulfilled posts.
• Clan management is deterministic. It writes state and leader actions; it does not delegate promotion, demotion, or kick policy to the model.

The detailed v5.1 design is in docs/reference/v5.1/.

Product surfaces

Elixir speaks as one identity across destination-specific Discord lanes:

• #elixir — the awareness brain's curated public commentary and updates.
• #announcements — weekly recaps and major system updates.
• #actions — crisp leadership handoff cards and action outcomes.
• #ask-elixir — open member conversation and screenshot help.
• #clan-chat — mention-driven clan help.
• #leaders — private, evidence-grounded clan operations.
• #welcome — onboarding and identity verification.
• #recruiting — reusable recruiting copy.

The exact channel IDs, reply policies, memory scopes, and workflows live in prompts/DISCORD.md.

Recurring activities

runtime/activities.py is the canonical registry for activity keys, ownership, schedules, executors, delivery targets, and enabled state. The important groups are:

• Core: engine-tick and awareness-loop.
• Clan management: weekly-leadership-review, action-outcome-refresh, and war-attendance-snapshot.
• Member communications: daily-clan-insight, weekly-recap, weekly-member-report, weekly-elder-standing, promotion-content, and weekly-discord-invite-relay.
• Data and operations: card-catalog-sync, api-sentinel, db-maintenance, db-backup, and memory-synthesis.
• Optional/manual: clan-wars-intel; tournament watching is dynamically started and resumed outside the recurring registry.

Do not duplicate schedule values in prose; inspect the registry or use the /clanops activity ... commands.

Quick start

Python 3.14 is the supported runtime.

uv sync --locked
# Create .env with the required secrets below.
uv run --locked python elixir.py

Required secrets:

DISCORD_TOKEN=...
CLAUDE_API_KEY=...
CR_API_KEY=...

Non-secret clan and Discord configuration lives in prompts/CLAN.md and prompts/DISCORD.md. See SETUP.md before running production.

pyproject.toml contains direct runtime and development constraints. uv.lock is the exact environment used by CI and deployment.

Repository map

• elixir.py — process entrypoint.
• elixir_agent.py — stable public LLM facade.
• cr_api.py — sole Clash Royale API ingress.
• engine/ — five-step data engine, emitters, projections, management, polling, and offline rehearsal.
• db/ — canonical schema builder and migrations, connection discipline, schema checks, and storage facade.
• storage/ — domain persistence and read helpers.
• agent/ — workflow prompts, model loop, tool contracts, and tools.
• runtime/ — Discord routing, activities, jobs, awareness, and logging.
• prompts/ — identity, purpose, clan, channel, lane, and workflow instructions.
• tests/ — unit, integration, fixture, invariant, and entrypoint tests.

Database model

The operational database defaults to elixir-v51.db. Clash Royale player tags are natural keys everywhere. The pre-cut database is the immutable cold archive elixir-v5-archive-2026H2.db and must never be written.

The runtime data layers are:

1. Raw API responses — bounded analysis buffer, not system of record.
2. Baselines — current comparison substrate for state-diff emitters.
3. Event streams — durable battle/player/clan/war facts.
4. Rollups — durable player and clan daily metrics.
5. Identity and tenure — players, Discord links, aliases, and memberships.
6. Projections — rebuildable current state and management views.
7. Awareness, management, operations, and scoped memory records.

See docs/data-model-erd.md and docs/reference/v5.1/schema.md.

Tests and confidence gates

Use the locked uv environment:

uv lock --check
uv run --locked python scripts/check_docs.py
uv run --locked python scripts/check_exception_hygiene.py
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked mypy capabilities/contracts.py
uv run --locked pytest tests/ -q --cov=capabilities --cov-report=term-missing --cov-fail-under=80

Before deploying engine changes, also run:

uv run --locked python scripts/replay_gate.py
uv run --locked python scripts/simulate.py

For one consolidated health answer:

uv run --locked python scripts/confidence_report.py --json

The suite uses isolated SQLite databases and mocked external services. Real CR payload shapes live in tests/fixtures/cr/; refresh them from retained raw payloads rather than hand-editing them.

Operations

Production is managed by launchd through scripts/admin.sh:

bash scripts/admin.sh status
bash scripts/admin.sh restart
bash scripts/admin.sh activity run api-sentinel

Elixir does not monitor itself: logs/elixir-error.log (ERROR+ with tracebacks) is the operator interface, and triaging it is the Operations Manager's job — see AGENT-TEAM/error-watch.md.

Member self-service commands live under /elixir. Leadership operations live under /clanops. System telemetry is read from the databases directly — via the .claude/skills/ lenses, scripts/admin.sh, or SQL. The Observatory web app was deleted 2026-08-04: it went unused for weeks while still taking a share of every schema change.

Review model/channel failures with:

uv run --locked python scripts/review_agent_feedback.py --limit 20
uv run --locked python scripts/review_agent_feedback.py --workflow clanops --json

Cleanup and portability

uv run --locked python scripts/clean.py
uv run --locked python scripts/clean.py --db

The database cleanup option removes only legacy local runtime files; it never touches elixir-v51.db or the archives.

A new clan primarily rewrites prompts/CLAN.md, prompts/DISCORD.md, and any culture-specific lane prompts. Elixir no longer publishes poapkings.com; the site has its own standalone update process.

Fan Content and Attribution

Elixir is an unofficial, non-commercial fan project. It is not affiliated with, authorized, or endorsed by Supercell. Clash Royale and the Clash Royale API are trademarks of Supercell, and the card names, card/badge artwork, and game data Elixir reads and displays are Supercell's intellectual property, used under Supercell's Fan Content Policy. Card and badge imagery posted to Discord is served live from Supercell's own CDN (api-assets.clashroyale.com); this project does not redistribute or bundle it. See LICENSE for the third-party carve-out.

This material is unofficial and is not endorsed by Supercell. For more information see Supercell's Fan Content Policy: www.supercell.com/fan-content-policy.