{"id":50979409,"url":"https://github.com/mizarc/astrokat","last_synced_at":"2026-06-19T12:34:01.432Z","repository":{"id":359817282,"uuid":"1247413592","full_name":"mizarc/astrokat","owner":"mizarc","description":"A modular, multiplatform chatbot with useful features to enhance the chat experience.","archived":false,"fork":false,"pushed_at":"2026-06-13T16:48:01.000Z","size":821,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T18:26:45.180Z","etag":null,"topics":["chatbot","discord","fluxer","utilities"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mizarc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T09:28:37.000Z","updated_at":"2026-06-13T16:48:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mizarc/astrokat","commit_stats":null,"previous_names":["mizarc/spacecat","mizarc/astrokat"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mizarc/astrokat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizarc%2Fastrokat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizarc%2Fastrokat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizarc%2Fastrokat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizarc%2Fastrokat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mizarc","download_url":"https://codeload.github.com/mizarc/astrokat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizarc%2Fastrokat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34532256,"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-06-19T02:00:06.005Z","response_time":61,"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":["chatbot","discord","fluxer","utilities"],"created_at":"2026-06-19T12:33:58.264Z","updated_at":"2026-06-19T12:34:01.411Z","avatar_url":"https://github.com/mizarc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Astrokat — A Chat Companion for All\n\n![License](https://img.shields.io/badge/license-AGPLv3-red)\n![Node](https://img.shields.io/badge/node-24.x-blue)\n![Version](https://img.shields.io/github/v/release/mizarc/astrokat)\n\nA multi-platform chat bot that brings a shared set of fun and useful commands to **Fluxer** and **Discord**. Whether you need to do a quick calculation, a Wikipedia lookup, perform automated tasks, or a GIF of someone getting slapped, Astrokat has you covered!\n\n## 🤖 Official Instance\n\nWe have an officially hosted public Astrokat instance ready to use! Invite it to your server with no setup required:\n\n[**Invite Astrokat on Fluxer**](https://web.fluxer.app/oauth2/authorize?client_id=1513393888411254785\u0026scope=bot\u0026permissions=387072)\n\n[**Invite Astrokat on Discord**](https://discord.com/oauth2/authorize?client_id=503580226035384340\u0026scope=bot%20applications.commands\u0026permissions=2147870720)\n\n\u003e 💡 **Prefer to self-host?** You can run Astrokat on your own infrastructure using Docker, all it takes is a token and a couple of commands. Head over to [Getting Started](#-getting-started) to set up your own instance.\n\n## ✨ Features\n\n- **Multi-platform by design** — Built on a shared command system. Write a command once, it works everywhere. Currently supports Discord and Fluxer.\n- **20+ commands** — From utility (ping, calc, QR codes, timestamps) to social (coinflip, diceroll, wheelspin, slap with animated GIFs) to knowledge (Wikipedia, thesaurus, translations).\n- **Persistent reminders** — Set `!remindme in 30 minutes ...` and get pinged when the time comes. Backed by SQLite (zero setup) or PostgreSQL for clustered deployments.\n- **Fully localised** — All user-facing text is managed through locale files. Drop in a new language and Astrokat speaks it.\n- **Pluggable adapters** — Adding a new chat platform is as simple as implementing a handful of methods.\n- **Docker-first** — One command to start. SQLite for small deployments, PostgreSQL for larger scale clusters.\n\n## 🏁 Getting Started\n\nBefore you can run the bot, you need to create bot applications on the platforms you want to use and obtain their tokens.\n\n### Fluxer\n\n#### 1. Create a bot application\n\n1. Open the Fluxer client and go to **User Settings → Applications**.\n2. Click **Create Application**, give it a name, and confirm.\n3. Regenerate and copy the token. This is your `FLUXER_TOKEN`.\n\n#### 2. Invite the bot to your server\n\n1. Go to the **OAuth2 URL Builder** section in the application settings.\n2. Under **Scopes**, select `bot`.\n3. Under **Bot Permissions**, select:\n   - `Send Messages`\n   - `Read Message History`\n   - `Manage Messages`\n   - `Embed Links`\n   - `Attach Files`\n   - `Use External Emoji`\n4. Copy the generated URL, open it in your browser, and select the server to add the bot to.\n\n### Discord\n\n#### 1. Create a bot application\n\n1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and click **New Application**.\n2. Give it a name (e.g. \"Astrokat\") and click **Create**.\n3. Go to the **Bot** tab in the left sidebar.\n4. Under **Token**, click **Reset Token** then **Copy** — this is your `DISCORD_TOKEN`.\n5. Under **Privileged Gateway Intents**, enable:\n   - **Message Content Intent** — required for text-based commands (`!ping`, `!help`, etc.)\n\n#### 2. Invite the bot to your server\n\n1. Go to the **OAuth2 → URL Generator** tab.\n2. Under **Scopes**, select `bot` and `applications.commands`.\n3. Under **Bot Permissions**, select:\n   - `Use Slash Commands`\n   - `Send Messages`\n   - `Read Message History`\n   - `Manage Messages`\n   - `Embed Links`\n   - `Attach Files`\n   - `Use External Emoji`\n4. Copy the generated URL, open it in your browser, and select the server to add the bot to.\n\n## 🐳 Docker Deployment\n\n### Prerequisites\n- [Docker](https://docs.docker.com/engine/install/) \u0026 [Docker Compose](https://docs.docker.com/compose/install/)\n\n### Quick Start (SQLite — no external services)\n\n1. **Create a project folder and download the files:**\n   ```bash\n   mkdir astrokat\n   cd astrokat\n   curl -LO https://raw.githubusercontent.com/mizarc/astrokat/main/docker-compose.yml\n   curl -LO https://raw.githubusercontent.com/mizarc/astrokat/main/.env.example\n   ```\n\n2. **Configure the environment:**\n   ```bash\n   cp .env.example .env\n   ```\n   Open `.env` in any text editor and fill in at least `DISCORD_TOKEN` and/or `FLUXER_TOKEN` with the tokens you got from the previous category.\n\n   If you want to use operator-only commands (`status`, `presence`), also add your operator ID:\n\n   - **Fluxer:** Right-click your profile and click **Copy User ID**.\n   - **Discord:** Enable Developer Mode (Settings → Advanced → Developer Mode), then right-click your profile and click **Copy User ID**.\n\n   ```bash\n   BOT_OPERATOR_IDS=123456789012345678\n   ```\n\n   For multiple operators, separate with commas:\n   ```bash\n   BOT_OPERATOR_IDS=123456789012345678,987654321098765432\n   ```\n\n3. **Start the bot:**\n   ```bash\n   docker compose up\n   ```\n   Astrokat is now running with SQLite storage, no external database needed.\n\n### Start with PostgreSQL\n\n```bash\ndocker compose --profile postgres up\n```\n\nThe `postgres` profile spins up a PostgreSQL 17 container alongside the bot and configures it automatically via `DATABASE_URL`.\n\n### Choose which adapters to run\n\nSet `ADAPTERS` in your `.env` file:\n\n| Value | Adapters |\n|---|---|\n| `discord,fluxer` | Both (default) |\n| `discord` | Discord only |\n| `fluxer` | Fluxer only |\n\n### Run in background\n\n```bash\ndocker compose up -d\ndocker compose --profile postgres up -d\n```\n\n### Stop\n\n```bash\ndocker compose down\ndocker compose --profile postgres down\n```\n\n### View logs\n\n```bash\ndocker compose logs -f\n```\n\n### Updating\n\nPull the latest image and restart:\n\n```bash\ndocker compose pull\ndocker compose up -d\n```\n\nYour `.env` file and SQLite data volume are preserved across updates.\n\n### Backup (SQLite)\n\nThe SQLite database lives in a Docker named volume. To back it up:\n\n```bash\n# Find the exact volume name (pattern: \u003cproject\u003e_astrokat-data)\ndocker volume ls | grep astrokat-data\n\n# Back up to a compressed archive\ndocker run --rm -v \u003cproject\u003e_astrokat-data:/data alpine tar czf - -C /data . \u003e astrokat-backup-$(date +%F).tar.gz\n```\n\n\u003e **Note:** Replace `\u003cproject\u003e_astrokat-data` with your actual volume name from the first command.\n\nTo restore from a backup:\n\n```bash\ndocker run --rm -v \u003cproject\u003e_astrokat-data:/data alpine tar xzf - -C /data \u003c astrokat-backup-2026-06-09.tar.gz\n```\n\n## 🚀 Local Development\n\n### Prerequisites\n- Node.js 24+\n- npm\n\n### Setup\n\n```bash\n# Install dependencies\nnpm install\n\n# Copy and configure environment\ncp .env.example .env\n# Edit .env with your tokens\n\n# Deploy Discord slash commands (also auto-deploys on startup)\nnpm run deploy\n```\n\n### Run\n\n```bash\nnpm run dev    # development mode with file watching\nnpm start      # production start\n```\n\n### Test\n\n```bash\nnpm test\nnpm run test:coverage   # with coverage report\n```\n\n## ⚙️ Environment Variables\n\nAstrokat is configured through environment variables set in your `.env` file. Below is the full list of supported variables. Copy `.env.example` to `.env` and fill in the values relevant to your setup. Anything left as the default can be safely omitted.\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `ADAPTERS` | No | `discord,fluxer` | Which chat platforms to connect to |\n| `DISCORD_TOKEN` | Conditional | — | Discord bot token (needed for Discord) |\n| `FLUXER_TOKEN` | Conditional | — | Fluxer bot token (needed for Fluxer) |\n| `DISCORD_ID` | Yes, for slash commands | — | Discord application ID (slash commands auto-deploy on startup) |\n| `BOT_OPERATOR_IDS` | No | — | Comma-separated user IDs allowed to run owner commands (!status, !presence) |\n| `DATABASE_URL` | No | — | PostgreSQL connection string (unset → SQLite) |\n\n## 📦 Storage Backends\n\nAstrokat stores data in one of two backends. The bot picks automatically based on whether `DATABASE_URL` is set in your `.env` file. If set, it connects to PostgreSQL; otherwise it uses an embedded SQLite database.\n\n| Backend | When to use | Setup |\n|---|---|---|\n| **SQLite** (default) | Single-instance deployment, quick start | No setup. Data persists in a Docker volume at `/app/data/astrokat.db`. |\n| **PostgreSQL** | Multi-instance deployments where multiple bot processes share reminder data | Either spin up the bundled database via `docker compose --profile postgres up`, or set `DATABASE_URL` in `.env` to point at your own PostgreSQL instance. |\n\n## 🤝 Contributing\n\nContributions are welcome! We're looking for people to help with bug fixes, new commands, translations, or documentation improvements. All we ask is that you follow the guidelines.\n\nSee **[CONTRIBUTING.md](./CONTRIBUTING.md)** for:\n\n- Project structure overview\n- How to add a new command\n- Localization (i18n) workflow\n- Testing and coding conventions\n- Pull request process\n\nPlease also note that this project is governed by a [Code of Conduct](./CODE_OF_CONDUCT.md).\n\n## 🔧 Troubleshooting\n\n- **Bot is online but doesn't respond to commands.**\nMake sure you invited the bot with the required permissions (see the permissions list for each platform above). On Discord, also verify the **Message Content Intent** is enabled in the Bot settings of the Developer Portal.\n\n- **Bot joins the server but no slash commands (`/`) appear.**\nThe bot auto-deploys slash commands on startup. Restart the bot and after waiting a few seconds, they should appear. If they don't, verify `DISCORD_ID` is set correctly in your `.env` file.\n\n- **`docker compose up` fails with \"Cannot connect to the Docker daemon\".**\nDocker isn't running or isn't installed. Make sure Docker Desktop is open, or if on Linux, that the Docker service is started (`sudo systemctl start docker`).\n\n- **`docker compose pull` says \"pull access denied\".**\nYou're trying to pull a private image. Astrokat is public. Make sure the image name is `ghcr.io/mizarc/astrokat:latest` (not `astrokat:latest` or another shorthand).\n\n- **Bot runs but data isn't saved after a restart.**\nThe SQLite data volume isn't persisting. Check that the volume mapping is present in your `docker-compose.yml` (`astrokat-data:/app/data`) and that you're not running with `docker compose down -v` (the `-v` flag deletes volumes).\n\n- **Permission denied when running Docker commands on Linux.**\nAdd your user to the Docker group: `sudo usermod -aG docker $USER`, then log out and back in.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizarc%2Fastrokat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmizarc%2Fastrokat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizarc%2Fastrokat/lists"}