🤖 Discord.py × OMP Plugin Cheat Sheet

June 8, 2026 • Updated June 8, 2026 • 12 min read • 2355 words

discord omp plugin mcp extension discord.py cheatsheet

🤖 Discord.py × OMP Plugin Cheat Sheet

Bridge a discord.py bot (Python) with the OMP coding agent extension system (Bun/TS) — from zero to full bidirectional integration.

🧠 Core Concept

OMP extensions = TypeScript/Bun. discord.py = Python. They’re separate runtimes. You bridge them via one of three tiers:

	🪝 Tier 1: Webhook	🔧 Tier 2: MCP Server	🌉 Tier 3: Extension + Bot
Direction	OMP → Discord only	Both (LLM invokes tools)	Both (event-driven)
Needs Python?	❌ No	✅ Yes	✅ Yes
Needs Bot Token?	❌ No (webhook URL)	✅ Yes	✅ Yes
Discord → OMP?	❌	❌	✅
Auto-notify events?	✅	❌	✅
LLM calls Discord?	❌	✅	✅
Setup time	~5 min	~15 min	~30–60 min
Deps	None	`discord.py`, `mcp`	`discord.py`, `aiohttp`

⚡ OMP Extension Contract (All Tiers)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// ~/.omp/agent/extensions/my-ext/index.ts
import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";

export default function myExt(pi: ExtensionAPI) {
  // ── Registration Phase (sync) ──
  pi.setLabel("My Extension");

  pi.on("agent_end", async (event, ctx) => { /* ... */ });
  pi.on("session_start", async (event, ctx) => { /* ... */ });

  pi.registerTool({ name: "my_tool", /* ... */ });
  pi.registerCommand("my-cmd", { /* ... */ });

  // ⚠️ CANNOT call pi.sendMessage() during load — only in handlers
}

📡 Key Lifecycle Events

1
2
3


session_start → input → agent_start → turn_start
  → tool_call → tool_execution_start → tool_execution_end → tool_result
  → turn_end → agent_end → session_shutdown

Event	Use Case	Return
`agent_end`	“Done” notification to Discord	—
`tool_call`	Audit / block dangerous ops	`{ block, reason }`
`tool_result`	Redact secrets before logging	`{ content }`
`session_start`	Init bot connection	—
`session_shutdown`	Cleanup / final flush	—

🪝 Tier 1 — Webhook (Zero-Dep, 5 min)

No bot. No Python. Just fetch(). OMP → Discord one-way.

📁 `~/.omp/agent/extensions/discord-notify/index.ts`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";

export default function discordNotify(pi: ExtensionAPI) {
  const WEBHOOK = process.env.DISCORD_WEBHOOK_URL;
  if (!WEBHOOK) return;

  const send = (content: string) =>
    fetch(WEBHOOK, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ content }),
    }).catch(() => {});

  // 🔔 Auto-notify when agent finishes
  pi.on("agent_end", async () => {
    await send(`✅ **Agent finished** — ${new Date().toLocaleTimeString()}`);
  });

  // 💬 Slash command: /discord-ping <message>
  pi.registerCommand("discord-ping", {
    description: "Send a message to the Discord webhook",
    handler: async (args, ctx) => {
      await send(args.trim() || "Ping from OMP!");
      ctx.ui.notify("Sent to Discord", "info");
    },
  });
}

🔑 Setup

1
2
3
4
5


# 1. Create webhook: Discord → Server Settings → Integrations → Webhooks → New
# 2. Export URL
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/123/abc..."

# 3. Drop file, restart OMP. Done.

⚠️ Rate limit: Discord enforces 5 requests / 5 seconds per webhook.

🔧 Tier 2 — MCP Server (Bot as Tool Provider)

discord.py bot runs as a stdio MCP server. OMP launches it, the LLM calls its tools.

1

OMP Agent ◀──stdio JSON-RPC──▶ Python MCP Server ◀──gateway──▶ Discord

📁 `~/.omp/tools/discord-mcp/server.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92


#!/usr/bin/env python3
"""Discord bot exposed as MCP tool server."""
import asyncio, os
import discord
from discord.ext import commands
from mcp.server import Server
from mcp.server.stdio import stdio_server
import mcp.types as types

# ── Bot ──
intents = discord.Intents.default()
intents.message_content = True
bot = commands.Bot(command_prefix="!", intents=intents)
ready = asyncio.Event()

@bot.event
async def on_ready():
    ready.set()

# ── MCP Server ──
app = Server("discord-mcp")

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="discord_send",
            description="Send a message to a Discord channel",
            inputSchema={
                "type": "object",
                "properties": {
                    "channel_id": {"type": "string"},
                    "content": {"type": "string"},
                },
                "required": ["channel_id", "content"],
            },
        ),
        types.Tool(
            name="discord_read",
            description="Read recent messages from a Discord channel",
            inputSchema={
                "type": "object",
                "properties": {
                    "channel_id": {"type": "string"},
                    "limit": {"type": "integer", "default": 10},
                },
                "required": ["channel_id"],
            },
        ),
        types.Tool(
            name="discord_guilds",
            description="List all guilds the bot is in",
            inputSchema={"type": "object", "properties": {}},
        ),
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    await ready.wait()

    if name == "discord_send":
        ch = bot.get_channel(int(arguments["channel_id"]))
        if not ch:
            return [types.TextContent(type="text", text="Channel not found")]
        await ch.send(arguments["content"])
        return [types.TextContent(type="text", text=f"Sent to #{ch.name}")]

    if name == "discord_read":
        ch = bot.get_channel(int(arguments["channel_id"]))
        if not ch:
            return [types.TextContent(type="text", text="Channel not found")]
        msgs = []
        async for m in ch.history(limit=arguments.get("limit", 10)):
            msgs.append(f"[{m.created_at:%H:%M}] {m.author.display_name}: {m.content}")
        return [types.TextContent(type="text", text="\n".join(reversed(msgs)) or "(empty)")]

    if name == "discord_guilds":
        lines = [f"{g.name} (id={g.id})" for g in bot.guilds]
        return [types.TextContent(type="text", text="\n".join(lines) or "(none)")]

    return [types.TextContent(type="text", text=f"Unknown tool: {name}")]

async def main():
    token = os.environ["DISCORD_TOKEN"]
    async with bot:
        bot_task = asyncio.create_task(bot.start(token))
        async with stdio_server() as (r, w):
            await app.run(r, w, app.create_initialization_options())
        bot_task.cancel()

if __name__ == "__main__":
    asyncio.run(main())

📁 `~/.omp/agent/mcp.json`

1
2
3
4
5
6
7
8
9


{
  "mcpServers": {
    "discord": {
      "command": "python3",
      "args": ["/home/dev/.omp/tools/discord-mcp/server.py"],
      "env": { "DISCORD_TOKEN": "DISCORD_TOKEN" }
    }
  }
}

📦 Install deps

1
2
3
4


pip install discord.py mcp
# env value "DISCORD_TOKEN": "DISCORD_TOKEN" = copy from shell env
export DISCORD_TOKEN="your-bot-token"
# Restart OMP — it auto-discovers mcp.json and launches the server

🌉 Tier 3 — Full Extension + Sidecar Bot

Most powerful. OMP extension (TS) ↔ discord.py bot (Python) over localhost HTTP. Full bidirectional event-driven bridge.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


┌──────────────────────────────────┐
│ OMP Extension (Bun/TS)          │
│ ├ on(agent_end) → POST /notify  │
│ ├ registerTool(discord_notify)  │
│ └ registerCommand(/discord)     │
└──────────┬───────────────────────┘
           │ HTTP :8901
┌──────────▼───────────────────────┐
│ discord.py Bot + aiohttp (Py)   │
│ ├ POST /notify → channel.send() │
│ ├ GET  /status → bot info       │
│ ├ GET  /channels → list all     │
│ └ !ask-omp <prompt> → omp CLI   │
└──────────┬───────────────────────┘
           │ Discord Gateway
┌──────────▼───────────────────────┐
│ Discord                         │
└──────────────────────────────────┘

📁 Python Sidecar: `discord_omp_bot.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87


#!/usr/bin/env python3
"""discord.py sidecar bot with HTTP API for OMP."""
import asyncio, logging, os, subprocess
import discord
from discord import app_commands
from discord.ext import commands
from aiohttp import web

log = logging.getLogger("discord-omp")
intents = discord.Intents.default()
intents.message_content = True
bot = commands.Bot(command_prefix="!", intents=intents)

NOTIFY_CH = int(os.environ.get("DISCORD_NOTIFY_CHANNEL", "0"))
HTTP_PORT = int(os.environ.get("DISCORD_HTTP_PORT", "8901"))

# ── HTTP endpoints (called by OMP extension) ──
async def handle_notify(req: web.Request) -> web.Response:
    data = await req.json()
    ch = bot.get_channel(NOTIFY_CH)
    if not ch:
        return web.json_response({"error": "channel not found"}, status=404)

    embed_data = data.get("embed")
    if embed_data:
        embed = discord.Embed(
            title=embed_data.get("title", ""),
            description=embed_data.get("description", ""),
            color=embed_data.get("color", 0x5865F2),
        )
        for f in embed_data.get("fields", []):
            embed.add_field(
                name=f["name"], value=f["value"], inline=f.get("inline", False)
            )
        await ch.send(content=data.get("content"), embed=embed)
    else:
        await ch.send(data.get("content", "📨 (empty)"))
    return web.json_response({"ok": True})

async def handle_status(_: web.Request) -> web.Response:
    return web.json_response({
        "bot": str(bot.user), "guilds": len(bot.guilds),
        "latency_ms": round(bot.latency * 1000, 1), "ready": bot.is_ready(),
    })

async def handle_channels(_: web.Request) -> web.Response:
    return web.json_response([
        {"id": str(c.id), "name": c.name, "guild": g.name}
        for g in bot.guilds for c in g.text_channels
    ])

async def start_http():
    app = web.Application()
    app.router.add_post("/notify", handle_notify)
    app.router.add_get("/status", handle_status)
    app.router.add_get("/channels", handle_channels)
    runner = web.AppRunner(app)
    await runner.setup()
    await web.TCPSite(runner, "127.0.0.1", HTTP_PORT).start()
    log.info(f"HTTP API → 127.0.0.1:{HTTP_PORT}")

# ── Discord commands ──
@bot.event
async def on_ready():
    await start_http()
    await bot.tree.sync()
    log.info(f"Ready as {bot.user}")

@bot.hybrid_command(name="ask-omp", description="Ask the OMP coding agent")
@app_commands.describe(prompt="Your question")
async def ask_omp(ctx: commands.Context, *, prompt: str):
    await ctx.defer()
    try:
        r = subprocess.run(
            ["omp", "-p", prompt, "--no-input"],
            capture_output=True, text=True, timeout=120, cwd="/home/dev",
        )
        out = r.stdout.strip()[:1900] or "(no output)"
        await ctx.send(f"```\n{out}\n```")
    except subprocess.TimeoutExpired:
        await ctx.send("⏱️ Timed out (120s)")
    except Exception as e:
        await ctx.send(f"❌ {e}")

if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    asyncio.run(bot.start(os.environ["DISCORD_TOKEN"]))

📁 OMP Extension: `~/.omp/agent/extensions/discord-bridge/index.ts`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";

const BOT = process.env.DISCORD_BOT_URL ?? "http://127.0.0.1:8901";

export default function discordBridge(pi: ExtensionAPI) {
  const { z } = pi.zod;
  pi.setLabel("Discord Bridge");

  // 🔔 Auto-notify on agent completion
  pi.on("agent_end", async (_ev, ctx) => {
    const tokens = ctx.getContextUsage?.()?.tokens ?? "?";
    await fetch(`${BOT}/notify`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        embed: {
          title: "✅ Agent Run Complete",
          description: `Session: ${pi.getSessionName?.() ?? "—"}`,
          color: 0x00ff00,
          fields: [{ name: "Tokens", value: `${tokens}`, inline: true }],
        },
      }),
    }).catch(() => {});
  });

  // 🛠️ LLM-callable tool
  pi.registerTool({
    name: "discord_notify",
    label: "Discord Notify",
    description: "Send a notification to the configured Discord channel",
    parameters: z.object({
      message: z.string().describe("Message to send"),
    }),
    async execute(_id, params) {
      const res = await fetch(`${BOT}/notify`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ content: params.message }),
      });
      const data = (await res.json()) as { ok?: boolean; error?: string };
      return data.ok
        ? { content: [{ type: "text", text: "✅ Sent to Discord" }] }
        : { content: [{ type: "text", text: `❌ ${data.error}` }], isError: true };
    },
  });

  // ⌨️ OMP slash command: /discord
  pi.registerCommand("discord", {
    description: "Check Discord bot status",
    handler: async (_args, ctx) => {
      try {
        const s = (await (await fetch(`${BOT}/status`)).json()) as Record<string, unknown>;
        ctx.ui.notify(`🤖 ${s.bot} | ${s.guilds} guilds | ${s.latency_ms}ms`, "info");
      } catch {
        ctx.ui.notify("Bot unreachable", "warning");
      }
    },
  });
}

🚀 Deploy the Sidecar as systemd

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# ~/.config/systemd/user/discord-omp-bot.service
[Unit]
Description=Discord OMP Bridge Bot
After=network.target

[Service]
ExecStart=/usr/bin/python3 /home/dev/discord_omp_bot.py
Environment=DISCORD_TOKEN=your-token
Environment=DISCORD_NOTIFY_CHANNEL=123456789
Environment=DISCORD_HTTP_PORT=8901
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

1
2
3


systemctl --user daemon-reload
systemctl --user enable --now discord-omp-bot
journalctl --user -u discord-omp-bot -f

📦 Packaging as Distributable OMP Plugin

📁 File Structure

1
2
3
4
5


omp-discord-bridge/
├── index.ts          ← source
├── package.json
└── dist/
    └── index.js      ← bundled (generated)

📁 `package.json`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
  "name": "omp-discord-bridge",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "omp": { "extensions": ["./dist/index.js"] },
  "peerDependencies": {
    "@oh-my-pi/pi-coding-agent": "*"
  },
  "scripts": {
    "build": "bun build ./index.ts --outdir ./dist --target node --external @oh-my-pi/pi-coding-agent"
  }
}

🔨 Build & Install

1
2
3
4
5
6
7
8
9


# Bundle (CRITICAL — OMP legacy loader copies to /tmp, breaking relative imports)
bun build ./index.ts --outdir ./dist --target node \
  --external @oh-my-pi/pi-coding-agent

# Install as plugin
omp plugin link /path/to/omp-discord-bridge

# Verify
omp plugin list

🚨 NEVER skip bundling. OMP mirrors extensions to /tmp/omp-legacy-pi-file/ — unbundled relative require() calls break silently. Always --external @oh-my-pi/pi-coding-agent.

🐍 discord.py Essentials

🔑 Bot Token Setup

1
2
3
4
5
6


1. discord.com/developers/applications → New Application
2. Bot tab → Reset Token → 📋 copy
3. Bot tab → ✅ MESSAGE CONTENT Intent
4. OAuth2 → URL Generator → bot + applications.commands
   → Send Messages, Read History, Embed Links, Use Slash Commands
   → Copy invite URL → open in browser → select server

🧩 Intents Quick-Ref

1
2
3
4


intents = discord.Intents.default()
intents.message_content = True   # ⚠️ Required for prefix commands
intents.guilds = True            # Guild join/leave events
intents.members = True           # ⚠️ Privileged — needs portal toggle

🔀 Hybrid Commands (Slash + Prefix)

1
2
3
4
5
6
7
8


@bot.hybrid_command(name="ping", description="Pong!")
async def ping(ctx: commands.Context):
    await ctx.send(f"🏓 {bot.latency*1000:.0f}ms")

# Don't forget:
@bot.event
async def on_ready():
    await bot.tree.sync()  # ← registers slash commands with Discord

🧱 Cog Pattern

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


class MyCog(commands.Cog):
    def __init__(self, bot): self.bot = bot
    async def cog_load(self):   ...  # setup
    async def cog_unload(self): ...  # teardown

    @commands.hybrid_command()
    async def hello(self, ctx): await ctx.send("Hi!")

async def setup(bot):  # ← entry point
    await bot.add_cog(MyCog(bot))

⏰ Background Tasks

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from discord.ext import tasks

@tasks.loop(minutes=5)
async def heartbeat():
    ...  # periodic work

@heartbeat.before_loop
async def wait_ready():
    await bot.wait_until_ready()

heartbeat.start()  # call in on_ready or cog_load

🖱️ Views (Buttons)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


class Confirm(discord.ui.View):
    value: bool | None = None

    @discord.ui.button(label="✅ Yes", style=discord.ButtonStyle.green)
    async def yes(self, interaction, button):
        self.value = True
        await interaction.response.edit_message(content="Confirmed!", view=None)
        self.stop()

    @discord.ui.button(label="❌ No", style=discord.ButtonStyle.red)
    async def no(self, interaction, button):
        self.value = False
        await interaction.response.edit_message(content="Cancelled.", view=None)
        self.stop()

# Usage:
view = Confirm(timeout=60)
await ctx.send("Proceed?", view=view)
await view.wait()

🔐 Security Checklist

Rule	Why
❌ Never commit `DISCORD_TOKEN` or webhook URLs	They’re bearer credentials
🔒 Bind HTTP API to `127.0.0.1` only	No external exposure
⏳ Rate-limit webhook calls (5/5s)	Discord enforces this
🛡️ Validate all Discord input	Before passing to OMP tools
🎯 Use least-privilege bot permissions	Only what you actually need
🔄 Store tokens in env vars or systemd `Environment=`	Not in code or config files

🗺️ Quick Decision Flowchart

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Need Discord integration?
│
├─ Just notifications? ──────────── 🪝 Tier 1 (Webhook)
│   └─ Drop index.ts, set env var, done.
│
├─ LLM needs to call Discord? ──── 🔧 Tier 2 (MCP)
│   └─ Write Python MCP server, add mcp.json, done.
│
└─ Full two-way bridge? ─────────── 🌉 Tier 3 (Extension + Bot)
    └─ OMP ext (.ts) + sidecar bot (.py) + systemd service.

📚 Reference Links

Resource	URL
discord.py Docs	`https://discordpy.readthedocs.io/`
MCP Spec	`https://spec.modelcontextprotocol.io/`
MCP Python SDK	`pip install mcp`
OMP Extension Docs	`omp://extensions.md`
OMP MCP Config	`omp://mcp-config.md`
OMP Plugin System	`omp://plugin-manager-installer-plumbing.md`

Last updated: 2026-06-08 · Grounded in OMP extension docs, pi-langfuse reference impl, and discord.py v2.x API.

🤖 Discord.py × OMP Plugin Cheat Sheet

🧠 Core Concept

⚡ OMP Extension Contract (All Tiers)

📡 Key Lifecycle Events

🪝 Tier 1 — Webhook (Zero-Dep, 5 min)

📁 ~/.omp/agent/extensions/discord-notify/index.ts

🔑 Setup

🔧 Tier 2 — MCP Server (Bot as Tool Provider)

📁 ~/.omp/tools/discord-mcp/server.py

📁 ~/.omp/agent/mcp.json

📦 Install deps

🌉 Tier 3 — Full Extension + Sidecar Bot

📁 Python Sidecar: discord_omp_bot.py

📁 OMP Extension: ~/.omp/agent/extensions/discord-bridge/index.ts

🚀 Deploy the Sidecar as systemd

📦 Packaging as Distributable OMP Plugin

📁 File Structure

📁 package.json

🔨 Build & Install

🐍 discord.py Essentials

🔑 Bot Token Setup

🧩 Intents Quick-Ref

🔀 Hybrid Commands (Slash + Prefix)

🧱 Cog Pattern

⏰ Background Tasks

🖱️ Views (Buttons)

🔐 Security Checklist

🗺️ Quick Decision Flowchart

📚 Reference Links

📁 `~/.omp/agent/extensions/discord-notify/index.ts`

📁 `~/.omp/tools/discord-mcp/server.py`

📁 `~/.omp/agent/mcp.json`

📁 Python Sidecar: `discord_omp_bot.py`

📁 OMP Extension: `~/.omp/agent/extensions/discord-bridge/index.ts`

📁 `package.json`