gemini-discord

Discord bridge for Gemini CLI / ACP agent workflows.

gemini-discord connects your Discord app to Gemini CLI, providing a chat interface for your agent. Using the CLI's native Agent Client Protocol (ACP) mode, it lets you manage sessions, automate tasks, and interact with your agent via Discord DMs or server channels.

Send a task from your phone. Your agent picks it up, works in the same workspace, and replies in the same channel. Sessions stay warm. Credentials stay local. Authority stays with one Discord user ID you control.

This extension leverages native multimodal capabilities of Gemini models, allowing you to send images, video, audio, PDFs, and source files directly through the Discord interface for immediate, in-context interpretation by the agent.

Discord Bot Setup

You need a bot application before installing:

Create an application at discord.com/developers/applications.
Go to Bot → Reset Token → copy it. This is DISCORD_BOT_TOKEN.
Enable Message Content Intent (required) and Server Members Intent (required by default; requested unless DISCORD_ENABLE_SERVER_MEMBERS_INTENT is set to false). Ensure both are toggled ON in the Developer Portal under the Bot tab.
Go to OAuth2 → URL Generator. Scopes: bot, applications.commands. Minimum permissions: View Channels, Read Message History, Send Messages, Attach Files, Use Slash Commands, Add Reactions.
Open the generated URL to invite the bot to your server.
Enable Developer Mode in Discord (Settings → Advanced), then right-click your username and copy your User ID. This is DISCORD_BOSS_USER_ID.

Install

Requires Gemini CLI, Node.js 22+, and a Discord bot token.

For this bridge workflow, authenticate Gemini CLI with non-interactive credentials that the daemon can pass to child processes:

export GEMINI_API_KEY="YOUR_API_KEY"

Vertex AI is also supported through Gemini CLI's GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_API_KEY, GOOGLE_CLOUD_PROJECT, and GOOGLE_CLOUD_LOCATION environment variables. Browser OAuth is not recommended for unattended bridge sessions.

gemini extensions install https://github.com/Yamato-main/gemini-discord

The installer prompts for Discord setup values and Gemini auth values. GEMINI_API_KEY is recommended for unattended bridge sessions; Vertex AI users can leave it blank and set the Vertex variables instead. Restart Gemini CLI and the bot should come online.

Prompt	What it is
Discord Bot Token	From the Discord Developer Portal
Boss User ID	Your stable numeric Discord user ID — the only ID with full authority
Server ID	The server where the bot is installed
Gemini API Key	Recommended API-key auth for Gemini CLI child processes
Vertex AI settings	Optional `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_API_KEY`, `GOOGLE_CLOUD_PROJECT`, and `GOOGLE_CLOUD_LOCATION` values

Legacy owner and admin routing IDs are auto-derived from Boss User ID unless overridden in advanced configuration.

If startup fails, see docs/troubleshooting.md.

Updating Configuration

To rotate credentials or update setup values:

gemini extensions config gemini-discord

For local development:

npm run setup

What it can do

From Discord, you can:

Chat with your agent in any channel, thread, or DM
Send attachments — images, video, audio, PDFs, text, Markdown, JSON, source files — and the agent receives them in-session
Trigger scheduled tasks and cron jobs
Search local media files and post them back when authorized

Your agent gains Discord tools:

Tool	Actions
`discord_message`	Send, reply, create native Discord threads, edit, delete, react, fetch reactions, pin, unpin
`discord_admin`	Status, restart, reset sessions, discover channels/users, set presence, kick, timeout
`discord_history`	Read recent exchanges and archived sessions
`discord_cron`	Schedule and manage reminders and recurring jobs
`discord_find_media`	Search host machine media and post to Discord

Slash commands:

Command	Description
`/new`	Fresh session for the current channel
`/model`	Switch the Gemini CLI model or alias. Defaults to `auto`; custom `GEMINI_AVAILABLE_MODELS` values only affect autocomplete suggestions.
`/status`	Daemon health and runtime info
`/pool`	Process pool state (boss only)
`/kill`	Kill a pooled process (boss only)
`/workflow`	Create and start a monitored workflow thread for a task (boss only)
`/ping`	Round-trip latency

Slash command visibility model:

Global slash commands are registered only for bot DMs. They use Discord's BotDM interaction context and guild-install integration type so public global commands do not appear across every server channel.
Guild slash commands are registered separately for each guild where the bot is installed. Guild payloads intentionally omit global contexts and integration_types; Discord scopes those commands to that guild install.
Discord command visibility is not treated as authorization. The daemon still checks DISCORD_BOSS_USER_ID, owner IDs, and allowed users at interaction time.
Privileged commands such as /model, /pool, /kill, and /workflow remain boss-gated even if Discord shows the command to someone else because of guild command permissions or server UI state.

Permissions

Two roles: BOSS and GUEST.

Boss authority is granted only by DISCORD_BOSS_USER_ID — never by username, display name, role, server owner status, or any other Discord metadata. If that value is missing or malformed, privileged actions fail closed.

Guests are globally disabled by default. Human users in DISCORD_ALLOWED_USER_IDS can chat in allowed channels even when DISCORD_ENABLE_GUESTS=false; other human users can chat only when DISCORD_ENABLE_GUESTS=true. When available, simple public Google Search may be allowed for guests. Guest attachment processing, including image viewing, is disabled by default and can be enabled with DISCORD_ENABLE_GUEST_ATTACHMENTS=true; boss attachment processing is unaffected. Guests cannot use MCP tools, shell access, filesystem access, history, discovery, cron, admin, moderation, or outbound Discord actions. Peer bots remain separate and must be listed in DISCORD_ALLOWED_AGENT_IDS.

Server replies require an explicit mention by default; set RESPOND_TO_REPLIES=true only if you want direct replies to bot messages to trigger responses. All message sends require an explicit target. If a target can't be proven, the action fails — there is no fallback channel.

Credentials and runtime state stay local. Do not commit .env, .gemini-discord/, logs, databases, tokens, or real Discord IDs.

Configuration

Most users only need the install prompts. Full reference via docs/configuration.md.

Prompt	Purpose
Discord Bot Token	Lets the bridge connect to Discord
Boss User ID	The only Discord user ID with full authority
Server ID	Server where the bot is installed
Gemini API Key	Recommended API-key auth for Gemini CLI child processes
Vertex AI settings	Optional Vertex AI auth for Gemini CLI child processes

Update these later with:

gemini extensions config gemini-discord

Agent instructions: This extension does not ship a GEMINI.md. Keep your agent instructions in ~/.gemini/GEMINI.md. The bridge adds only transport context — message metadata, channel/thread/DM scope, attachment refs, and permission metadata.

Development

git clone https://github.com/Yamato-main/gemini-discord
cd gemini-discord
npm ci && npm run setup && npm run build

Install a local path:

gemini extensions install /absolute/path/to/gemini-discord

npm run typecheck       # Type-check
npm run version:check   # Verify package, manifest, lockfile, and runtime version fields
npm run version:bump -- 0.1.2
npm test                # Run tests
npm run dev:daemon      # Daemon in dev mode
npm run start:daemon    # Start daemon
npm run start:server    # Start MCP server
npm run install-service # Install as system service

Before releasing: follow RELEASE.md. Run npm ci, npm run version:check, npm run typecheck, npm run build, and npm test; commit dist/; keep .env and .gemini-discord/ untracked; use placeholder IDs in examples; add the gemini-cli-extension GitHub topic.

Contributing

See CONTRIBUTING.md.

License

MIT

Gemini Discord

README