CodexNexus

A slash-command Discord bot for one team: manage GitHub issues from your channels, keep a shared to-do list, see the time across the team — and summon an unhinged cat meme when it all gets too much.

Command	What it does	Needs
🕒 /showtime	Show a time across the team's timezones	nothing
🌐 /timezones	Configure which zones /showtime shows	nothing
✅ /todo	Shared server-wide to-do list	nothing
🐙 /issue	Create / view / update GitHub issues	GitHub App
🔗 /repos	Map a channel to GitHub repos (admins)	GitHub App
🐱 /mood	Cat meme GIF matching your mood	Tenor key
🏓 /ping	Is the bot alive?	nothing

📖 Full command reference → · ⚙️ Detailed setup → · 🏗️ Architecture →

---

How to use it

🕒 Time across the team — /showtime

Type a time once, see it for everyone. Bare times (9, 9:00, 9 am) are read in the first configured zone; add a zone token to convert the other way:

/showtime                → current time everywhere
/showtime 9 am           → 9 am in the first zone, converted for the rest
/showtime 9:00 swe       → 9:00 in Stockholm, converted for the rest

Out of the box it shows Kathmandu 🇳🇵, Stockholm 🇸🇪, Sydney 🇦🇺. Admins change the list with /timezones add zone:America/New_York / /timezones remove — /showtime picks it up immediately, and /timezones list shows the zones and the short tokens (swe, ktm, syd, …) you can type.

✅ Shared to-do list — /todo

One list per server, usable from any channel, no GitHub required. Items remember who added them and who owns them, and survive restarts:

/todo add title:"write release notes" assignee:@maya
/todo list                 → the whole board, grouped by status
/todo mine                 → just your items (only you see it)
/todo status id:2 to:In progress
/todo done id:1

🐙 GitHub issues without leaving Discord — /issue

First, an admin links repos to a channel once — no owner/repo slugs to memorize, just type to search:

/repos add repo:lex…       → autocompletes from the repos your GitHub App can see
/repos list                → what's linked here

Then anyone in that channel can work issues. The number field is type-to-search by title — start typing and pick from the list:

/issue create title:"Add dark mode" labels:ui assignees:maya-dev
/issue view number:…       → embed with state, labels, assignees + checklist progress
/issue list state:open
/issue comment number:… text:"shipping today"
/issue close number:…      (and reopen / update / assign)

If a channel maps to one repo, commands just work; with several, pass repo: to pick. GitHub stays the source of truth.

🐱 Emergency cat — /mood

/mood text:monday

Always a meme-ey cat — never a stock one.

The images above are mockups of the bot's actual output, so your Discord may differ cosmetically.

---

Setup

You need: Python 3.13 + uv (or just Docker), a Discord bot token, and optionally a GitHub App (for /issue + /repos) and a Tenor key (for /mood).

1. Discord app — create an application + bot at the Developer Portal, copy the bot token, and invite it with the bot and applications.commands scopes. No privileged intents needed.

2. GitHub App (optional) — create a GitHub App with Issues: Read & write and Metadata: Read, install it on your org/repos, note the App ID and Installation ID, download the private key .pem.

3. Tenor (optional) — grab a free API key for /mood.

4. Configure — cp .env.example .env and fill it in. Just DISCORD_TOKEN is enough for /showtime + /todo; the GitHub commands stay politely disabled until the GITHUB_* vars are set.

5. Run:

   uv sync
   uv run python main.py

6. In Discord — an admin runs /repos add in each project channel to link its repo(s). Done.

Step-by-step portal walkthroughs (with the exact clicks): docs/setup.md.

Tip: set DISCORD_GUILD_ID during development so slash-command changes appear instantly (global sync can take up to an hour).

Hosting

The repo ships a Dockerfile + docker-compose.yml. Put your .env and the GitHub App key (as codenexus.pem) next to them, set GITHUB_PRIVATE_KEY_PATH=codenexus.pem in .env, then:

docker compose up -d --build     # build + start
docker compose logs -f bot       # watch it come up
docker compose pull && docker compose up -d --build   # update

State (data/store.db — repo links, to-dos, timezones) lives in the mounted ./data folder, so it survives rebuilds. The bot is an outbound-only gateway client: no ports to expose, any small VPS or home server works. Details in docs/setup.md.

Docs

• docs/commands.md — every command, option, and permission
• docs/setup.md — detailed setup, configuration reference, Docker hosting
• docs/architecture.md — code layout, storage, and the manual test checklist