piscord

A lightweight Discord gateway for pi coding agent. It receives Discord messages, queues them in SQLite, invokes pi as a subprocess, and sends responses back -- keeping a persistent session per channel.

Current version: 1.4.2 (see Changelog for details)

npm install -g piscord
piscord setup                 # interactive wizard -- walks you through everything

That's it. The setup wizard checks prerequisites, asks for your Discord bot token, lets you pick a channel policy, and optionally installs + starts a systemd service. Your bot is live in under a minute.

Prerequisites

• Node.js ≥ 20
• pi installed and on PATH, with login completed (~/.pi/agent/auth.json)
• Discord bot token — create one here
  • Enable Message Content Intent under Privileged Gateway Intents
  • Bot permissions: Send Messages, Read Message History, View Channels, Attach Files

Features

• Bridges to your existing pi — shells out to the pi binary and reuses your login + model access
• Per-channel sessions — each Discord channel gets its own persistent conversation history
• Per-channel working directories — optionally override PI_CWD for specific channels without changing the global default
• Channel access policy — open (all channels), open-trigger (all channels, @mention required), or allowlist (manual registration only)
• SQLite message queue — survives crashes, auto-recovers stuck messages
• Concurrency control — per-channel serial processing + configurable global limit
• DM auto-registration — direct messages work out of the box
• Discord slash commands — /pi status, /pi model, /pi thinking, /pi new, /pi stop
• Abort command — /pi stop terminates the running task and clears queued messages
• Attachment relay — Discord file uploads are downloaded and passed to pi via @file
• Message and file sending — piscord send lets pi send plain text, files, or both to any Discord channel
• Scheduled tasks — cron or one-time tasks that trigger pi sessions on schedule
• Archive auto-cleanup — archived sessions are cleaned up after a configurable retention period
• Typing indicators — shows "bot is typing" while pi processes
• Message splitting — handles Discord's 2000-character limit automatically
• systemd integration — piscord daemon install generates a user service
• XDG-compliant paths — config in ~/.config/, data in ~/.local/share/

How It Works

Discord ──discord.js──→ Gateway ──pi subprocess──→ Pi Agent
                           │                          │
                         SQLite                  Session dirs
                      (message queue)           (per channel)

The gateway does not embed or replace pi. It finds and runs your installed pi:

1. Binary discovery — uses PI_BIN config or finds pi in PATH
2. Auth reuse — pi reads its own ~/.pi/agent/auth.json when invoked
3. Model catalog — the gateway imports the pi SDK to populate slash command autocomplete
4. Invocation — each message is processed as pi --session-dir <dir> --continue -p <message>

Channel Policy

During setup you pick one of three policies. This controls how the bot interacts with server channels:

| Policy | Behavior | |--------|----------| | open | All guild channels auto-register on first message. No @mention needed. | | open-trigger | All guild channels auto-register, but only respond when @mentioned. | | allowlist | Only manually registered channels are active. |

• DMs always auto-register when AUTO_REGISTER_DMS=true (the default).
• Use EXCLUDED_CHANNELS to block specific channels from auto-registration in open / open-trigger mode.

If you chose allowlist, register channels manually:

piscord register 123456789012345678 "my-server #general" --no-trigger
piscord register 123456789012345678 "my-server #general" --cwd /srv/repos/app

Re-running piscord register with --cwd updates that channel's working directory override. If no override is set, the gateway uses the global PI_CWD.

Slash Commands

The gateway registers a global /pi command on Discord:

| Subcommand | Description | |------------|-------------| | /pi status | Show model, thinking, working directory, session info, token usage | | /pi model | Set the channel's model (autocomplete from pi's available models) | | /pi reset-model | Clear the channel's model override | | /pi thinking | Set thinking level: off / minimal / low / medium / high / xhigh | | /pi new | Start a fresh session for this channel | | /pi stop | Abort the current task and clear queued messages |

Tools for Pi

The gateway exposes two capabilities through its CLI that pi itself can invoke. You don't type these commands in your terminal — you just tell pi in Discord, and it handles the rest.

For example, you can say to pi:

"Create a daily task at 9am UTC that generates a summary report" "Send me report.pdf with a message saying here you go" "Set a one-time reminder for the 2pm meeting today"

pi will run the appropriate piscord task or piscord send command behind the scenes.

Scheduled tasks

pi can schedule cron-based or one-time prompts through the gateway's scheduler. Tasks are injected into the normal message queue, so they use the channel's configured model, thinking level, and working directory.

Under the hood, pi runs commands like:

piscord task add \
  --name "daily-report" \
  --schedule "0 9 * * *" \
  --channel dc:123456789 \
  --prompt "Generate today's summary report"

piscord task add \
  --name "meeting-reminder" \
  --schedule "2026-04-05T14:00:00Z" \
  --channel dc:123456789 \
  --prompt "Remind Colin about the 2pm meeting" \
  --once

The --schedule value uses standard 5-field cron syntax (minute hour day month weekday). For one-time tasks, add --once and pass an ISO 8601 datetime.

Task management — also available via pi:

piscord task list              # List all tasks
piscord task disable <id>      # Pause
piscord task enable <id>       # Resume
piscord task remove <id>       # Delete

Sending messages and files to Discord

pi can send plain text messages, files, or both to any Discord channel using the gateway's built-in relay.

When you ask pi to send something, it runs commands like:

piscord send --channel dc:123456789 --text "hello"
piscord send --channel dc:123456789 --file /path/to/report.pdf --text "Here's the report"
piscord send --channel dc:123456789 --file chart.png --file data.csv

• --text works on its own
• Up to 10 files per message (Discord limit)
• Respects MAX_ATTACHMENT_BYTES per file
• Works independently — no running gateway daemon required

systemd Service

The setup wizard offers to install a systemd user service automatically. You can also manage it manually:

piscord daemon install   # Generate + enable user service
piscord daemon start     # Start
piscord daemon status    # Check status
piscord daemon logs      # Tail journal output
piscord daemon stop      # Stop
piscord daemon uninstall # Remove the service

Headless servers: enable user lingering so the service runs without an active login session:

sudo loginctl enable-linger $USER

Configuration Reference

Config file: ~/.config/pi-discord-gateway/config.env

Most users won't need to edit this file directly — piscord setup generates it for you. If you do want to tweak advanced settings, you can edit the file manually, or ask your pi to configure it for you.

| Variable | Default | Description | |----------|---------|-------------| | DISCORD_BOT_TOKEN | (required) | Discord bot token | | PI_BIN | pi | Path to pi binary | | PI_MODEL | (none) | Default model override | | PI_THINKING | (none) | Default thinking level | | PI_CWD | $HOME | Default working directory for pi; can be overridden per registered channel | | PI_EXTRA_FLAGS | (none) | Extra flags passed to pi | | TRIGGER_NAME | pi | Bot trigger name for @mentions | | CHANNEL_POLICY | open | Channel access: open, open-trigger, or allowlist | | EXCLUDED_CHANNELS | (none) | Comma-separated channel IDs to exclude from auto-registration | | MAX_CONCURRENCY | 3 | Max parallel pi invocations | | MAX_SCHEDULED_CONCURRENCY | 1 | Max scheduled tasks enqueued per tick | | POLL_INTERVAL_MS | 1000 | Queue poll interval (ms) | | SHUTDOWN_TIMEOUT_MS | 15000 | Graceful shutdown timeout (ms) | | AUTO_REGISTER_DMS | true | Auto-register DM channels | | ARCHIVE_RETENTION_DAYS | 30 | Days to keep archived sessions (0 = never clean) | | MAX_ATTACHMENT_BYTES | 26214400 | Max size per attachment (0 = no limit) | | MAX_TOTAL_ATTACHMENT_BYTES | 52428800 | Max combined attachment size (0 = no limit) | | SESSIONS_DIR | ~/.local/share/piscord-gateway/sessions | Session storage directory | | DB_PATH | ~/.local/share/piscord-gateway/gateway.db | SQLite database path | | LOG_LEVEL | info | Log level: debug/info/warn/error |

After changing config, restart the service: piscord daemon stop && piscord daemon start

CLI Reference

piscord setup [token]                         Interactive setup wizard
piscord start                                 Start gateway (foreground)
piscord status                                Show diagnostics

piscord channels                              List registered channels
piscord register <id> <name> [options]        Register a channel
piscord unregister <id>                       Unregister a channel

piscord send --channel <jid> [--text <msg>] [--file <path> ...]

piscord task add --name <n> --schedule <cron|iso> --channel <jid> --prompt <text> [--once]
piscord task list | remove <id> | enable <id> | disable <id>

piscord archive list                          List archived sessions
piscord archive cleanup [--dry-run]           Clean up expired archived sessions

piscord daemon install | uninstall | start | stop | status | logs

piscord help                                  Show help

Register options

| Flag | Effect | |------|--------| | --no-trigger | Respond to all messages (not just @mentions) | | --main | Mark as main channel (implies --no-trigger) | | --folder <name> | Custom session folder name | | --cwd <path> | Override PI_CWD for this channel only |

Data Locations

| Item | Default path | |------|-------------| | Config | ~/.config/pi-discord-gateway/config.env | | Database | ~/.local/share/piscord-gateway/gateway.db | | Sessions | ~/.local/share/piscord-gateway/sessions/ | | pi auth | ~/.pi/agent/auth.json |

Alternative Installation

npx (quick trial, no global install)

npx piscord@latest setup

From source

git clone https://github.com/Crokily/pi-discord-gateway.git
cd pi-discord-gateway
npm install && npm run build
node dist/cli/index.js setup

Troubleshooting

piscord status shows "Pi binary: not found".

• Check pi --version works in the same shell
• Set PI_BIN=/full/path/to/pi in config.env
• Restart: piscord daemon stop && piscord daemon start

piscord status shows "Pi auth: missing".

• Run pi and complete the login flow
• Confirm ~/.pi/agent/auth.json exists for the same user running the gateway

• piscord daemon status — check for errors
• piscord daemon logs — see journal output
• For headless servers: sudo loginctl enable-linger $USER

• open policy: check EXCLUDED_CHANNELS doesn't include your channel
• allowlist policy: run piscord channels — at least one channel must be registered
• For trigger-only channels: mention the bot by name or use @TriggerName
• DMs auto-register when AUTO_REGISTER_DMS=true

Development

npm install
npm run dev          # Start with tsx (no build needed)
npm run build        # Compile TypeScript
npm test             # Run Vitest suite

Security

• Protect config.env — it contains your Discord bot token
• Anyone who can message a registered channel can spend your pi usage
• Review attachment size limits before exposing the bot
• Run the service as a normal user, not root

License

MIT

Version History

| Version | Date | Changes | |---------|------|---------| | 1.4.2 | 2026-04-06 | Fixed default XDG data directory mismatch | | 1.4.1 | 2026-04-06 | Fixed text-only sends via piscord send | | 1.4.0 | 2026-04-06 | Added per-channel working directories | | 1.3.0 | 2026-04-04 | Improved setup UX, faster install | | 1.2.0 | 2026-04-04 | Added channel policy, abort, scheduler, send-file | | 1.1.0 | 2026-03-31 | Renamed package to piscord | | 1.0.0 | 2026-03-28 | Initial release |

See Changelog for full details.

Acknowledgments

• Architecture inspired by NanoClaw
• Built for pi-mono by @badlogic