{"_id":"@2marcelj/pi-agent-discord-bridge","name":"@2marcelj/pi-agent-discord-bridge","dist-tags":{"latest":"1.1.0"},"versions":{"1.1.0":{"name":"@2marcelj/pi-agent-discord-bridge","version":"1.1.0","description":"Bridge agent that connects Discord (and Telegram) to the pi coding agent. Install globally to run the bridge server alongside pi, or locally in a project.","main":"dist/index.js","types":"dist/index.d.ts","bin":{"pi-agent-discord-bridge":"bin/pi-agent-discord-bridge"},"engines":{"node":">=20.0.0"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","prepublishOnly":"npm run build"},"keywords":["pi","discord","bot","ai","agent","bridge","middleware"],"author":{"name":"Marcel Jardin"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/2marcelj/pi-agent-discord-bridge.git"},"bugs":{"url":"https://github.com/2marcelj/pi-agent-discord-bridge/issues"},"homepage":"https://github.com/2marcelj/pi-agent-discord-bridge#readme","dependencies":{"discord.js":"^14.18.0","dotenv":"^16.5.0"},"devDependencies":{"@types/node":"^22.15.0","tsx":"^4.19.0","typescript":"^5.8.0"},"gitHead":"5ed5c8c33b8546c458cd5721bebfe6c825534765","_id":"@2marcelj/pi-agent-discord-bridge@1.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-jwO6itDhS33o516TUWyG1EgYz8l4uQuw7p4t7011fB5Zg+LZSCNPn9FGwPn4e2w6u7NOJWaF7VP29nRiKVmpDQ==","shasum":"24c66dc97b9eb0736f31387a5007407fb4181a17","tarball":"https://registry.npmjs.org/@2marcelj/pi-agent-discord-bridge/-/pi-agent-discord-bridge-1.1.0.tgz","fileCount":34,"unpackedSize":87615,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDVk1oWsXN2YWhSABJ+blnzQiLHQlld4dhGmDqNsdn/ngIgEujYBZQWHLgwMDduVqwVnkuaQmawy3DDdFJ+o4MdNvo="}]},"_npmUser":{"name":"2marcelj","email":"2marceljanssen@gmail.com"},"directories":{},"maintainers":[{"name":"2marcelj","email":"2marceljanssen@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-agent-discord-bridge_1.1.0_1779019553919_0.8915891482439353"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-17T12:05:53.772Z","1.1.0":"2026-05-17T12:05:54.089Z","modified":"2026-05-17T12:05:54.297Z"},"maintainers":[{"name":"2marcelj","email":"2marceljanssen@gmail.com"}],"description":"Bridge agent that connects Discord (and Telegram) to the pi coding agent. Install globally to run the bridge server alongside pi, or locally in a project.","homepage":"https://github.com/2marcelj/pi-agent-discord-bridge#readme","keywords":["pi","discord","bot","ai","agent","bridge","middleware"],"repository":{"type":"git","url":"git+https://github.com/2marcelj/pi-agent-discord-bridge.git"},"author":{"name":"Marcel Jardin"},"bugs":{"url":"https://github.com/2marcelj/pi-agent-discord-bridge/issues"},"license":"MIT","readme":"# pi Discord Bridge\n\nLet **pi** act as an AI agent in your Discord server. Messages sent to Discord are forwarded to pi for processing, and pi's responses are sent back to the channel — all while pi retains full access to its tools (read, edit, write, bash, etc.).\n\n## Quick Start (TL;DR)\n\n```bash\n# 1. Install the bridge server (globally for CLI, or locally in a project)\nnpm install -g @2marcelj/pi-agent-discord-bridge\n\n# 2. Configure environment\ncp .env.example .env\n# Edit .env → add DISCORD_BOT_TOKEN, ALLOWED_CHANNELS, ALLOWED_GUILDS\n\n# 3. Run the bridge server (in Terminal 1)\npi-agent-discord-bridge\n\n# 4. In Terminal 2, set pi extension env vars and start pi\nexport PI_BRIDGE_PORT=9876\nexport PI_BRIDGE_SECRET=\"change-me-in-production\"\nexport PI_BRIDGE_MIDDLEWARE_HOST=\"http://localhost:9877\"\nexport PI_BRIDGE_DEFAULT_CHANNEL=\"your-channel-id\"\npi\n```\n\n> See [Step-by-Step Setup](#step-by-step-setup) below for creating a bot, server, and getting IDs.\n\n## What It Does\n\n- **Inbound →** A user sends a message in Discord → bridge queues it → pi receives it as a user prompt\n- **Processing →** pi thinks, optionally uses tools (read code, run bash, etc.)\n- **Outbound →** pi calls the `discord_send_message` tool → response appears in Discord\n\n## Repository Layout\n\n```\npi-agent-discord-bridge/\n├── README.md                      # This file\n├── LICENSE                        # MIT\n├── package.json                   # Package manifest\n├── tsconfig.json                  # TypeScript config\n├── bin/\n│   └── pi-agent-discord-bridge   # CLI entry point (global install)\n├── src/                           # Bridge server source (Node.js)\n│   ├── index.ts                   # Entry point — HTTP + Discord bot\n│   ├── discord.ts                 # Discord.js adapter\n│   ├── pi-proxy.ts                # pi extension API client\n│   ├── queue.ts                   # Dedup + retry queue\n│   ├── config.ts                  # .env config loader\n│   ├── logger.ts                  # Structured logging\n│   └── types.ts                   # Shared TypeScript types\n├── dist/                          # Compiled JS + .d.ts (published)\n└── extensions/\n    └── discord-bridge.ts          # pi extension — copy to ~/.pi/extensions/\n```\n\n## Installation\n\nThis package is the **bridge server** — a persistent Node.js process that connects Discord to pi. Install it wherever you run long-lived services.\n\n### Option A — Global install (recommended for CLI usage)\n\nInstalls the `pi-agent-discord-bridge` command globally so you can run it from anywhere:\n\n```bash\nnpm install -g @2marcelj/pi-agent-discord-bridge\n\n# After configuring .env (see below):\npi-agent-discord-bridge\n```\n\n### Option B — Install in a project/repo\n\nInstall as a local dependency if you want to manage it alongside other project tooling:\n\n```bash\n# In your project directory\nnpm install @2marcelj/pi-agent-discord-bridge\n\n# Run the compiled entry point\nnode node_modules/@2marcelj/pi-agent-discord-bridge/dist/index.js\n\n# Or via npx\nnpx @2marcelj/pi-agent-discord-bridge\n```\n\n### Option C — Clone and run from source\n\n```bash\ngit clone https://github.com/2marcelj/pi-agent-discord-bridge.git\ncd pi-agent-discord-bridge\nnpm install\nnpm run build\nnpm start\n```\n\n## Step-by-Step Setup\n\n### 1. Set Up a Discord Bot & Server\n\n#### A. Create a Discord Bot\n1. Go to [Discord Developer Portal](https://discord.com/developers/applications)\n2. Click **New Application** → name it → go to the **Bot** tab\n3. Click **Reset Token** → **Copy** the bot token (save it somewhere safe — you'll need it for `DISCORD_BOT_TOKEN`)\n4. Scroll to **Privileged Gateway Intents** → toggle **Message Content Intent** to **ON**\n\n#### B. Create a Discord Server (if you don't have one)\n- In Discord, click the **+** on the left sidebar → **Create My Own** → name your server\n\n#### C. Invite the Bot to Your Server\n1. In the Developer Portal, go to **OAuth2** → **URL Generator**\n2. Select scope: `bot`\n3. Select permissions: `Send Messages`, `Read Message History`, `View Channels`\n4. Copy the generated URL, open it in a browser, and select your server\n\n#### D. Get the Guild ID (Server ID)\n1. In Discord, go to **User Settings** → **Advanced** → turn on **Developer Mode**\n2. Right-click your **server name** → **Copy Server ID** → that's your **Guild ID** for `ALLOWED_GUILDS`\n\n#### E. Get the Channel ID\n1. In Discord, right-click the **text channel** where you want pi to respond\n2. Click **Copy Channel ID** → that's your **Channel ID** for `ALLOWED_CHANNELS`\n\n### 2. Configure the Bridge\n\n```bash\ncp .env.example .env\n# Edit .env with your values\n```\n\nRequired minimum `.env`:\n```env\nDISCORD_BOT_TOKEN=your-bot-token-here\nALLOWED_CHANNELS=your-channel-id-here\nALLOWED_GUILDS=your-guild-id-here\n```\n\nLeave `ALLOWED_CHANNELS` or `ALLOWED_GUILDS` empty to bridge **all** channels/guilds the bot can see.\n\n### 3. Configure the pi Extension\n\nThe pi extension (`extensions/discord-bridge.ts`) runs **inside** pi. You need to copy it to pi's extensions folder **and** set environment variables before starting pi.\n\n**Install the extension:**\n```bash\n# Global pi extensions (recommended)\ncp extensions/discord-bridge.ts ~/.pi/extensions/\n\n# Or project-local\n# cp extensions/discord-bridge.ts .pi/extensions/\n```\n\n**Set environment variables** (each time before running `pi`):\n\n**Bash (Linux / macOS / Git Bash):**\n```bash\nexport PI_BRIDGE_PORT=9876\nexport PI_BRIDGE_SECRET=\"change-me-in-production\"\nexport PI_BRIDGE_MIDDLEWARE_HOST=\"http://localhost:9877\"\nexport PI_BRIDGE_DEFAULT_CHANNEL=\"your-channel-id\"\npi\n```\n\n**PowerShell (Windows):**\n```powershell\n$env:PI_BRIDGE_PORT=9876\n$env:PI_BRIDGE_SECRET=\"change-me-in-production\"\n$env:PI_BRIDGE_MIDDLEWARE_HOST=\"http://localhost:9877\"\n$env:PI_BRIDGE_DEFAULT_CHANNEL=\"your-channel-id\"\npi\n```\n\n> **Tip:** Create a `.env` file in the directory where you run `pi` so dotenv can load these automatically.\n\n### 4. Run\n\n**Terminal 1 — start the bridge server:**\n```bash\n# If installed globally:\npi-agent-discord-bridge\n\n# If running from source:\nnpm start\n```\n\n**Terminal 2 — start pi (with extension env vars set):**\n```bash\npi\n```\n\n### 5. Chat\n\nSend a message in your Discord channel. pi receives it and replies.\n\n## How It Works\n\n### Message Flow\n\n```\nDiscord User → Discord Gateway → Bridge Queue → pi Extension → pi Agent\n                   (typing indicator)                                       │\n                                     pi Agent decides to reply ◀────────────┘\n                                         │\n                                     discord_send_message tool\n                                         │\n                                     POST to bridge /send\n                                         │\n                                     Discord REST API\n                                         │\n                                     Message appears in channel\n```\n\n### Components\n\n| Component | Role | Tech |\n|-----------|------|------|\n| **pi Extension** (`discord-bridge.ts`) | Runs inside pi. HTTP API for inbound messages. Registers `discord_send_message` tool. | TypeScript, `node:http` |\n| **Bridge** (this package) | Persistent Node.js service. Discord Gateway, deduplication, queue. | `discord.js`, `dotenv` |\n| **Discord Bot** | Bot application in Developer Portal. | Discord API |\n\n### Two-Stage Discord Reply\n\nWhen a message arrives from Discord:\n\n1. **Typing indicator** + **auto-ack** (`🔄 Working on it...`) posted immediately\n2. **System prompt hint** injected telling the LLM to use `discord_send_message` for the final result\n3. LLM works using tools\n4. Final `discord_send_message` → result posted in Discord\n5. **Safety-net fallback** — if the LLM forgets to use the tool entirely, the bridge captures any assistant text output and auto-sends it\n\n## pi Commands\n\n| Command | Description |\n|---------|-------------|\n| `/bridge-status` | Show active channels, message counts, uptime, local-only mode |\n| `/bridge-reset` | Reset message counters |\n| `/local-only` | **Toggle** — blocks LLM from auto-replying to Discord |\n| `/discord-send <message>` | **Direct post** to default Discord channel (bypasses LLM) |\n\n## Bridge HTTP API\n\n| Endpoint | Auth | Description |\n|----------|------|-------------|\n| `POST /send` | ✅ Secret | Send a message to Discord |\n| `POST /typing` | ✅ Secret | Send \"is typing...\" indicator |\n| `GET /health` | ❌ Public | Health check |\n| `GET /status` | ✅ Secret | Bridge status |\n| `GET /version` | ❌ Public | Version info |\n\n## Programmatic API\n\n```ts\nimport { startMiddlewareHttpServer, startDiscordBot } from \"@2marcelj/pi-agent-discord-bridge\";\n\nawait startDiscordBot();\nawait startMiddlewareHttpServer();\n```\n\n## Environment Variables\n\n### Bridge Server (this package)\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `DISCORD_BOT_TOKEN` | ✅ | — | Discord bot token |\n| `PI_BRIDGE_URL` | — | `http://localhost:9876` | pi extension URL |\n| `PI_BRIDGE_SECRET` | — | `change-me-in-production` | Must match pi extension |\n| `MIDDLEWARE_PORT` | — | `9877` | Bridge HTTP port |\n| `ALLOWED_CHANNELS` | — | *(none)* | Channel IDs to bridge |\n| `ALLOWED_GUILDS` | — | *(none)* | Guild IDs to bridge |\n| `REQUIRE_MENTION` | — | `false` | Only respond to @mentions |\n| `MAX_MESSAGE_LENGTH` | — | `2000` | Discord message limit |\n| `LOG_LEVEL` | — | `info` | `debug`, `info`, `warn`, `error` |\n\n### pi Extension\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PI_BRIDGE_PORT` | `9876` | Extension HTTP port |\n| `PI_BRIDGE_SECRET` | `change-me-in-production` | Auth secret (must match bridge) |\n| `PI_BRIDGE_MIDDLEWARE_HOST` | `http://localhost:9877` | Bridge URL |\n| `PI_BRIDGE_DEFAULT_CHANNEL` | *(none)* | Default channel ID for `/discord-send` |\n\n## Security\n\n- **Never commit `DISCORD_BOT_TOKEN` or `PI_BRIDGE_SECRET`**.\n- Both services validate each other via `X-Bridge-Secret` header.\n- Bot should have minimal permissions (read/send, no admin).\n\n## Limitations\n\n- One pi instance per bridge.\n- No file upload from Discord.\n- No thread / DM support yet.\n- Message queue is in-memory (lost on restart).\n\n## License\n\nMIT — Use at your own risk. This bot has full tool access; only deploy in trusted environments.\n","readmeFilename":"README.md","_rev":"1-63d8ed5d1f0505d4099692239b551d83"}