{"id":47281247,"url":"https://github.com/jthingelstad/elixir-bot","last_synced_at":"2026-07-05T16:00:28.136Z","repository":{"id":341083257,"uuid":"1168831440","full_name":"jthingelstad/elixir-bot","owner":"jthingelstad","description":"LLM-powered, channel-native Discord agent for the POAP KINGS Clash Royale clan — event-sourced reactive engine, scoped public/leadership memory, and GitHub-backed poapkings.com publishing.","archived":false,"fork":false,"pushed_at":"2026-07-04T18:29:57.000Z","size":5425,"stargazers_count":3,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-04T19:15:25.732Z","etag":null,"topics":["ai-agent","anthropic","clash-royale","claude","discord-bot","discord-py","event-sourcing","llm","python","sqlite"],"latest_commit_sha":null,"homepage":"https://poapkings.com/elixir/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jthingelstad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-27T21:09:06.000Z","updated_at":"2026-07-04T18:30:00.000Z","dependencies_parsed_at":"2026-06-19T15:01:46.031Z","dependency_job_id":null,"html_url":"https://github.com/jthingelstad/elixir-bot","commit_stats":null,"previous_names":["jthingelstad/elixir-bot"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jthingelstad/elixir-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jthingelstad%2Felixir-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jthingelstad%2Felixir-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jthingelstad%2Felixir-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jthingelstad%2Felixir-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jthingelstad","download_url":"https://codeload.github.com/jthingelstad/elixir-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jthingelstad%2Felixir-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35160046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","clash-royale","claude","discord-bot","discord-py","event-sourcing","llm","python","sqlite"],"created_at":"2026-03-16T00:46:33.870Z","updated_at":"2026-07-05T16:00:28.087Z","avatar_url":"https://github.com/jthingelstad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Elixir Bot\n\nElixir is an LLM-powered Discord bot for the POAP KINGS Clash Royale clan (`#J2RGCRVG`).\n\nIt is not a generic chat bot and not a single-feed narrator. Elixir is a channel-native clan agent with:\n- Discord channel lanes like `river-race`, `clan-events`, `leader-lounge`, and `ask-elixir`\n- executable agents/workflows for awareness, conversation, clanops, memory synthesis, content, and specialist tasks\n- a central recurring activity registry for scheduled work\n- scoped memory for public vs leadership context\n- GitHub-backed publishing for poapkings.com\n\n[AGENTS.md](AGENTS.md) is the repository source of truth for architecture and operating notes. This README is the best high-level introduction to the project.\n\nUseful companion docs:\n- [AGENTS.md](AGENTS.md)\n- [SETUP.md](SETUP.md)\n- [VERSIONS.md](VERSIONS.md)\n\n## What Elixir Does\n\nElixir currently handles four main kinds of work:\n\n1. Discord conversation\n   Elixir answers questions in the right channel with the right lane behavior. `#ask-elixir` is open conversation and screenshot help, `#clan-chat` is mention-driven, and `#leaders` is private clan operations.\n\n2. Signal-driven clan updates\n   Elixir detects roster, war, and progression signals, then fans one source event into one or more destination-specific outcomes. A new member join can become:\n   - a public welcome in `#clan-events`\n   - a factual leadership note in `#leaders`\n\n3. Scheduled recurring activities\n   Elixir runs recurring activities like the `v5-reactive-tick` proactive heartbeat, `war-poll`, `player-progression`, `weekly-recap`, `promotion-content`, and the daily `#ask-elixir` hidden-fact post.\n\n4. POAP KINGS website publishing\n   Elixir generates and publishes structured data for poapkings.com, pushes it to GitHub, and reports publish outcomes in `#website-updates`.\n\n## Current Channel Model\n\nElixir uses channel lanes instead of one overloaded public stream. A lane is a Discord destination contract: channel id, audience, allowed topics, reply policy, memory scope, and voice. Lanes are not independent agents; they are the rooms where one Elixir speaks.\n\nPrimary public/proactive lanes:\n- `#river-race` for River Race scoreboards, recaps, and meaningful war momentum\n- `#player-highlights` for curated player milestones and non-war battle pushes\n- `#clan-events` for joins, promotions, anniversaries, and clan recognitions\n- `#announcements` for the weekly recap and important clan-wide Elixir updates\n- `#recruiting` for recruiting copy members can reuse\n- `#website-updates` for website publish visibility\n\nPrimary interactive lanes:\n- `#ask-elixir` for open conversation with Elixir\n- `#clan-chat` for mention-driven general questions\n- `#welcome` for onboarding and identity verification\n- `#leaders` for leadership and clan operations\n\nThe live channel contract lives in [prompts/DISCORD.md](prompts/DISCORD.md).\n\n## Recurring Activities\n\nRecurring automated work is defined in [runtime/activities.py](runtime/activities.py). This is the canonical schedule registry.\n\nSee `runtime/activities.py` for the exact keys, schedules, and enabled state. The shape today:\n- `v5-reactive-tick`\n  The proactive heartbeat. Runs the Event Core engine (ingest → detections → recommendations/cases → communication intents → confirmed Discord delivery). This replaced the old `clan-awareness` / `war-awareness` ticks.\n- `war-poll`\n  Hourly live war ingest + River Race snapshot pipeline.\n- `player-progression`\n  Refreshes player profiles and battle logs, then emits curated member highlights.\n- `daily-clan-insight`\n  Daily `#ask-elixir` hidden fact when the data supports a genuinely interesting insight.\n- `weekly-recap`\n  Weekly public recap in `#announcements`, plus members-page sync for the website.\n- `promotion-content`\n  Weekly recruiting content for `#recruiting` and the website.\n- Plus `api-sentinel`, `card-catalog-sync`, `award-detection`, `weekly-discord-invite-relay`, `memory-synthesis`, `clan-wars-intel`, and `db-maintenance`.\n\n## Quick Start\n\n```bash\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\nCreate a `.env` file with the required secrets:\n\n```env\nDISCORD_TOKEN=your_discord_bot_token\nCLAUDE_API_KEY=your_anthropic_api_key\nCR_API_KEY=your_clash_royale_api_key\nELIXIR_LOG_WEBHOOK_URL=optional_discord_webhook_url_for_elixir_log\n```\n\nStart the bot locally:\n\n```bash\nvenv/bin/python elixir.py\n```\n\nSee [SETUP.md](SETUP.md) for production setup, `launchd`, optional site publishing config, and operational guidance.\n\n## Running Tests\n\n```bash\nvenv/bin/python -m pytest tests/ -v\n```\n\nTests use in-memory SQLite and mocked external services. No API keys are needed for the test suite.\n\n## Project Structure\n\nCore entrypoints:\n- [elixir.py](elixir.py)\n  Main bot runtime entrypoint.\n- [elixir_agent.py](elixir_agent.py)\n  Stable public LLM entrypoint for replies, updates, and site generation.\n- [heartbeat.py](heartbeat.py)\n  API-driven signal detection for clan, war, and progression events.\n- [cr_api.py](cr_api.py)\n  Clash Royale API client.\n\nPrompt and behavior stack:\n- [prompts/SOUL.md](prompts/SOUL.md)\n  Elixir's persistent identity and stance.\n- [prompts/PURPOSE.md](prompts/PURPOSE.md)\n  Mission and guardrails.\n- [prompts/GAME.md](prompts/GAME.md)\n  Clash Royale mechanics and stable game knowledge.\n- [prompts/CLAN.md](prompts/CLAN.md)\n  POAP KINGS-specific rules, thresholds, and clan identity.\n- [prompts/DISCORD.md](prompts/DISCORD.md)\n  Declarative channel contract.\n- [prompts/lanes/](prompts/lanes/)\n  Discord destination-lane behavior prompts.\n- [prompts/agents/](prompts/agents/)\n  Executable workflow prompts for awareness, memory synthesis, routing, and tournament commentary.\n\nRuntime architecture:\n- [runtime/activities.py](runtime/activities.py)\n  Canonical recurring activity registry.\n- [runtime/channel_router.py](runtime/channel_router.py)\n  Discord message routing and reply-policy enforcement.\n- [event_core/](event_core/)\n  Event-sourced v5 reactive engine (the proactive path that replaced the v4 signal/awareness loop).\n- [runtime/jobs/](runtime/jobs/)\n  Scheduled activity executors.\n- [runtime/admin.py](runtime/admin.py)\n  Admin command dispatch and manual activity execution.\n\nPersistence and intelligence:\n- [db/](db/)\n  SQLite schema and query helpers.\n- [storage/](storage/)\n  Identity, memory, analytics, and message persistence.\n- [agent/](agent/)\n  LLM prompt composition, workflow contracts, tool policy, and chat loop.\n\nModules:\n- [modules/poap_kings/](modules/poap_kings/)\n  POAP KINGS website integration and GitHub publishing.\n\n## Prompt Model\n\nPrinciple: prompts define what Elixir says and why. Code defines when, where, and how.\n\nThe current prompt stack is:\n- `SOUL.md`\n  Who Elixir is.\n- `PURPOSE.md`\n  What Elixir is for.\n- `GAME.md`\n  Stable Clash Royale knowledge.\n- `CLAN.md`\n  POAP KINGS-specific reality.\n- `DISCORD.md`\n  Server and channel contract.\n- `lanes/*.md`\n  Destination-lane behavior.\n- `agents/*.md`\n  Workflow/agent instructions that are not tied to one Discord channel.\n\nThis split matters. It keeps one consistent Elixir identity across very different channels without collapsing everything into one noisy system prompt.\n\n## Memory Model\n\nElixir uses two memory layers.\n\nConversational memory:\n- user, member, and channel conversation state\n- recent channel history\n- message summaries and episodes\n\nDurable scoped memory:\n- `public`\n- `leadership`\n- `system_internal`\n\nImportant rules:\n- public lanes only read public durable memory\n- `leader-lounge` can read public plus leadership durable memory\n- `reception` should stay focused on onboarding context\n- multi-outcome signals share a source identity, but public and leadership durable memories stay separated so private copy cannot overwrite public memory\n\n## POAP KINGS Website Integration\n\nElixir owns the dynamic site data written to poapkings.com:\n- `elixirClan.json`\n- `elixirRoster.json`\n- `elixirHome.json`\n- `elixirMembers.json`\n- `elixirPromote.json`\n\nGitHub-backed site publishing lives in [modules/poap_kings/site.py](modules/poap_kings/site.py).\n\nWhen a real publish happens, Elixir reports it in `#website-updates` with:\n- success or failure\n- commit SHA\n- direct GitHub commit URL\n- repo and branch\n- changed content types when useful\n\nNo-change publishes stay quiet.\n\n## Admin and Operations\n\nElixir's operator commands live in Discord `#leaders`; routine runtime notices go to `#elixir-log` when `ELIXIR_LOG_WEBHOOK_URL` is configured.\n\nUse slash commands under `/elixir ...`.\n\nExamples:\n\n```text\n/elixir system status\n/elixir activity show activity:v5-reactive-tick\n/elixir integration publish integration:poap-kings target:data preview:true\n/elixir member set member:Ditika field:join-date value:2026-03-07\n/elixir signal show view:recent limit:5\n```\n\nThe command model is object-first and grouped around:\n- `system`\n- `clan`\n- `member`\n- `memory`\n- `signal`\n- `activity`\n- `integration`\n\nUseful operational docs:\n- [SETUP.md](SETUP.md)\n  Installation, launchd, deploy/update flow, and logs.\n- [AGENTS.md](AGENTS.md)\n  Deeper architecture and repository conventions.\n\n## Reviewing Prompt Failures\n\nElixir stores failed or unusable Discord prompt attempts in the local `prompt_failures` table.\n\nReview the latest failures with:\n\n```bash\nvenv/bin/python scripts/review_agent_feedback.py --limit 20\nvenv/bin/python scripts/review_agent_feedback.py --workflow clanops --json\n```\n\nUse `--json` when you want to hand the failure set to another model for diagnosis.\n\n## Cleanup\n\n```bash\nvenv/bin/python scripts/clean.py\nvenv/bin/python scripts/clean.py --db\n```\n\nDefault cleanup removes caches like `__pycache__` and `.pytest_cache`.\n\n`--db` also removes local runtime files like `elixir.db` and `elixir.pid`.\n\n## Portability\n\nThe project is designed so a new clan can fork it and mostly rewrite:\n- [prompts/CLAN.md](prompts/CLAN.md)\n- [prompts/DISCORD.md](prompts/DISCORD.md)\n- selected files in [prompts/lanes/](prompts/lanes/)\n\nThe shared Elixir identity in `SOUL.md`, `PURPOSE.md`, and the game knowledge in `GAME.md` should remain broadly portable.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjthingelstad%2Felixir-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjthingelstad%2Felixir-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjthingelstad%2Felixir-bot/lists"}