Discord community bot powered by a summoned Octo agent — the mascot of The Reef comes alive.
Status: Alpha — Discord bot with slash commands, webhook handlers, streaming chat, scheduled posts, and gateway integration with 97 tests passing.
reef-bot is the official Discord bot for The Reef, the OpenOctopus community server. Unlike a typical moderation bot, reef-bot is a summoned Octo agent — the project mascot brought to life through the Summon engine.
Octo lives in The Reef, answers questions about OpenOctopus, helps newcomers get started, showcases realm packages, and occasionally drops octopus-themed wisdom.
- Conversational AI — Chat with Octo using natural language, powered by the Summon engine
- Realm lookup —
/realm info petto get details about any realm package - SOUL.md preview — Paste a SOUL.md and see a formatted personality card
- New member onboarding — Welcome messages with role assignment guidance
- Showcase highlights — Pin and promote community showcase posts
- GitHub integration — Post release notes and notable PRs to
#announcements - Summon demo —
/summon demoto see a live Summon interaction
| Component | Choice |
|---|---|
| Runtime | Node.js >= 22 + TypeScript |
| Discord Library | Discord.js v14 |
| Connection to Core | WebSocket RPC (port 19789) |
| Personality | SOUL.md (Octo mascot personality) |
reef-bot runs on a SOUL.md file that defines the Octo mascot personality:
- Calm and knowledgeable — like a wise deep-sea creature
- Helpful but concise — answers directly, no fluff
- Occasional humor — octopus puns and tentacle metaphors, used sparingly
- Multilingual — responds in English and Chinese
"A deep-sea octopus, definitely." — Octo
---
name: Octo
entityId: entity_octo_mascot
realm: community
identity:
role: community mascot and guide
personality: >-
Calm, knowledgeable, and approachable. Wise like a deep-sea
creature that has seen many things. Concise but warm.
background: >-
Born from the depths of The Reef when OpenOctopus was created.
Knows every corner of the ecosystem.
speaking_style: >-
Direct and helpful. Occasional octopus metaphors and dry humor.
Never uses emojis excessively. Responds in the user's language.
catchphrases:
- "Let me reach into that realm for you."
- "Eight arms, always ready to help."
coreMemory:
- The Reef community launched with OpenOctopus
- Every Realm deserves its own tentacle
proactiveRules:
- trigger: event
action: Welcome new members with a brief intro to OpenOctopus
- trigger: schedule
action: Post weekly Realm of the Week showcase
interval: weekly
---| Command | Description |
|---|---|
/realm info <name> |
Show details about a realm package |
/realm list |
List available realms |
/summon demo |
Live demo of a Summon interaction |
/soul preview |
Paste a SOUL.md and see a formatted card |
/docs <topic> |
Quick link to relevant documentation |
/help |
How to get started with OpenOctopus |
# Clone
git clone https://github.com/open-octopus/reef-bot.git
cd reef-bot
# Install
pnpm install
# Configure
cp .env.example .env
# Edit .env with your Discord bot token and ink gateway URL
# Run in development
pnpm dev
# Run tests
pnpm test| Variable | Description |
|---|---|
DISCORD_BOT_TOKEN |
Discord bot token (from Discord Developer Portal) |
INK_GATEWAY_URL |
ink gateway WebSocket URL (ws://localhost:19789) |
DISCORD_GUILD_ID |
The Reef server ID (for slash command registration) |
- Discord.js bot scaffold with slash commands
- WebSocket RPC connection to ink gateway
- Octo SOUL.md personality file
- Conversational responses via Summon engine
-
/realmand/summonslash commands - GitHub webhook integration
- New member welcome flow
| Project | Description |
|---|---|
| openoctopus | Core monorepo — Summon engine and ink gateway |
| community | The Reef community policies and docs |
| soul-gallery | SOUL.md template gallery |
reef-bot is in the planning phase. Join The Reef (Discord) to discuss the design, or open an issue with feature ideas.
See CONTRIBUTING.md for general guidelines.
MIT — see the .github repo for the full license text.