TriBridge — Discord ↔ Hypixel Guild Chat Bridge

A Node.js bot that relays messages between a Discord channel and Hypixel guild chat in real time. Guild chat appears in Discord as embeds, Discord messages are spoken in guild chat, and slash commands let admins run guild management commands in-game.

One bot can bridge several Hypixel guilds at once — one Minecraft account per guild — through the same Discord channel. Each guild gets its own colour and chat tag, and a !tag prefix targets a single guild. Guilds can also be bridged to each other, so their members talk in-game without going through Discord at all.

Two things are called a "guild" here. A Hypixel guild is one of the Minecraft guilds the bot bridges; there can be several. A Discord server is the single community the bot serves; there is exactly one.

Features

• The bridge — one Discord channel and Hypixel guild chat, relayed both ways, joins and leaves included; @name in guild chat pings that member in Discord.
• Multiple Hypixel guilds — one Minecraft account each, all through the same channel, colour-coded and tagged on the way back.
• Guild tags — !sb hey reaches one guild; anything else reaches all of them. An unrecognised tag is delivered anyway and flagged, never dropped.
• Guild-to-guild bridging — chat shared directly between the bridged guilds, in-game, opt-in per guild.
• Officer chat — a two-way Discord channel for Hypixel officer chat, shared between guilds with !tag routing or one per guild, and optionally shared between the guilds in-game as well. Off until a channel is named, and everyone who can post there speaks as an officer in-game.
• Account linking — members link with the bridge's own /link (separate from the community bot's), and their Discord messages are reposted with their Minecraft head and name, with the guild-chat copy attributed to their Minecraft name.
• Hypixel guild registry — /guilds registers, edits and signs guilds in entirely from Discord; the Microsoft device code arrives in a private reply, never the console.
• Auto-reconnect — dropped accounts come back on their own, one guild per ten-second tick so a Hypixel restart can't throttle them all at once.
• Admin roles — a flat list of Discord roles that hold bot-admin, shared with the community bot and set with its /adminrole.
• Admin panel — /adminpanel, a button per admin function, with the running state on the embed.
• Global profile change — everybody's messages reposted wearing one member's name and face, for a set duration, with a switch per bridge direction and a test mode.
• Auditing — every disguised message recorded with a jump link, so the real author is never lost.
• Guild management — /invite, /kick, /promote, /demote, /mute, /unmute, /send and /login, each targeting one guild or the default.
• Blacklist — /blacklist bars a member from both bots' commands and from relaying into guild chat.
• Information — /online, /ping and /help.

See Features for what each one does in full, the docs site for the same material split by audience, and the change log for what's new in each release.

Prerequisites

Requirement	Details
Node.js	v22 or newer
npm	Included with Node.js
Discord bot	An application at the Discord Developer Portal with the Message Content privileged intent enabled
Minecraft account	One Microsoft account per Hypixel guild, each owning Minecraft: Java Edition and able to join mc.hypixel.net
PostgreSQL	The database shared with the THG community bot. This bot keeps its settings and links there in its own schema, and shares the blacklist and admin roles. Required — the bot does not start without it

Installation

1. Clone the repository

   git clone https://github.com/TheHypixelGuardians/TriBridge.git
   cd TriBridge

2. Install dependencies

   npm install

3. Create a .env file in the project root. Copy .env.example and fill it in:

   cp .env.example .env

   DISCORD_TOKEN=your_discord_bot_token
   DISCORD_CHANNEL_ID=your_bridge_channel_id
   LOG_CHANNEL=your_log_channel_id
   MINECRAFT_USERNAME=you@example.com
   DATABASE_URL=postgres://user:password@host:5432/thg
   HYPIXEL_API_KEY=
   RANK_ROLE_SENIOR_OFFICER=
   RANK_ROLE_OFFICER=
   RANK_ROLE_TRIAL_OFFICER=
   RANK_ROLE_VETERAN=
   RANK_ROLE_ELITE=
   RANK_ROLE_TITAN=

   Variable	Description
   DISCORD_TOKEN	Bot token from the Discord Developer Portal
   DISCORD_CHANNEL_ID	The bridge channel — the one channel wired to guild chat
   LOG_CHANNEL	Where connection notices and warnings go. A Hypixel guild can override it with its own channel
   MINECRAFT_USERNAME	Microsoft account email for the first Hypixel guild. Ignored once a guild registry exists
   DATABASE_URL	The PostgreSQL database shared with the community bot. The guild registry, global profile change, audit channel and account links are stored in it, and the blacklist and admin roles are shared through it. Required
   HYPIXEL_API_KEY	Optional. Hypixel API key used to learn each guild's Hypixel id on connect
   DISCORD_GUILD_ID	Optional. The only Discord server the bot accepts commands from. Defaults to the bridge channel's server
   RANK_ROLE_*	Optional. The Discord role id for each /promote rank (SENIOR_OFFICER, OFFICER, TRIAL_OFFICER, VETERAN, ELITE, TITAN). Unset, the role with the rank's name is used

   TriBridge serves a single Discord server, however many Hypixel guilds it bridges. Commands are registered globally, so it refuses any command sent from another server — otherwise an administrator of any other server the bot was added to could give themselves bot-admin over your Minecraft accounts.

4. Invite the bot with the permissions listed in Permissions.

5. Start it

   npm start

   On a fresh install the account in MINECRAFT_USERNAME is registered as the first Hypixel guild and a Microsoft device-code flow opens in the console. Tokens are cached in .minecraft-auth/, one entry per account.

6. Set the admin roles — on the community bot, /adminrole add role:@Staff, run by someone with the Discord Administrator permission. The list is shared, and until it has an entry nothing admin-gated works on either bot.

Full walkthrough: Installation.

Commands

Command	Category	Description
/invite <username> [guild]	Management	Invite a player to a Hypixel guild (admin only)
/kick <username> [reason] [guild]	Management	Kick a member from a Hypixel guild (admin only)
/promote <user> <rank> [guild]	Management	Give a member a rank in-game and on Discord (admin only)
/demote <username> [guild]	Management	Demote a member in a Hypixel guild (admin only)
/mute <username> <duration> [guild]	Management	Mute a member in a Hypixel guild's chat (admin only)
/unmute <username> [guild]	Management	Unmute a member in a Hypixel guild's chat (admin only)
/blacklist add/remove/list	Management	Bar a member from both bots and from the chat bridge (admin only)
/send <message> [guild]	Management	Run a command as the Minecraft account and show the reply (admin only)
/login [guild]	Management	Connect the bots; all disconnected guilds by default (admin only)
/guilds add/remove/list/edit/default/auth	Management	Manage the bridged Hypixel guilds and sign their accounts in (admin only)
/adminpanel	Management	Open the admin panel (admin only)
/auditchannel set/show/clear [guild]	Management	Choose where admin panel actions are recorded (admin only)
/link <username>	Linking	Link your Minecraft account for the bridge
/unlink [user]	Linking	Remove your link, or anyone's (admin only)
/links	Linking	List every bridge link (admin only)
/whois <user|username>	Linking	Look up a bridge link in either direction (admin only)
/online [guild]	Information	Who is online in every guild, or one
/ping	Information	Discord latency and each guild's Minecraft connection status
/help	Information	Browse all commands by category

Guild tags (!tag message) aim a bridge message at one guild. Full reference: Commands.

Usage

npm start

While working on the bot, npm run dev restarts it whenever a source file or the .env changes. Both are wrappers around node src/index.js, which still works on its own.

Everything past the first Hypixel guild is configured from Discord rather than from files:

/guilds add key:sb name:SkyBlock Guild tag:SB account:you@example.com
/guilds edit guild:sb crossbridge:True

Bot-admin roles are shared with the community bot and set with its /adminrole. Members link with /link, which is the bridge's own, separate from the community bot's.

Config files are written next to the repository and are all gitignored, so they survive a git pull — see Config files.

Updating

git pull
npm install

Then restart the bot. New or changed slash commands take up to an hour to propagate on Discord's side. See Updating.

Documentation

• Docs site — canonical public documentation (TriBridge + THG Community products; source in site/, preview with cd site && npx mint dev). See site/README.md.
• Privacy policy — what both THG bots store and how to have it removed (source in site/privacy.mdx)
• Features — the canonical in-repo description of everything the bot does
• Change log, and the Discord change log for the announcement channel
• Writing the changelog & releasing
• Commit structure
• CLAUDE.md — the after-every-change checklist and the project's conventions