mira-pi

a pi extension that connects a pi agent to discord via project threads. it uses discord.js to listen for messages and registers tools so the agent can interact with threads.

install with pi install npm:mira-pi

how it works

the extension runs inside the pi runtime. on startup it:

1. loads config from env vars, .pi/discord.json, and ~/.pi/discord.json
2. restores the thread registry from ~/.mira/registry.json
3. connects to discord via discord.js (listening for messageCreate events)
4. registers five tools that the agent can call

when a message arrives in a project thread, the extension either passes it to a waiting wait_for_message call, queues it, or pushes it to the agent via pi.sendUserMessage().

config

config is loaded from three sources, highest priority first:

| priority | source | notes | |----------|--------|-------| | 1 | env vars | DISCORD_TOKEN, DISCORD_CHANNEL_ID, MIRA_PROJECT | | 2 | .pi/discord.json | project-local override | | 3 | ~/.pi/discord.json | global fallback |

{
  "token": "your-bot-token",
  "channelId": "parent-channel-id",
  "project": "optional-override"
}

project defaults to the basename of the current working directory. set MIRA_PROJECT or the json key to override it. placeholder values like "your-bot-token" are treated as empty so example configs don't break things.

message flow

discord message arrives (messageCreate)
  │
  ├─ not a thread? → ignore
  ├─ thread name ≠ project? → ignore
  ├─ author is a bot? → ignore
  │
  ├─ wait_for_message is waiting? → resolve the promise, wake the agent
  ├─ queue is empty, agent is in session? → pi.sendUserMessage() to push it
  └─ otherwise → queue it for later

the wait_for_message tool blocks until a message comes in or the timeout expires. the queue drains into wait_for_message first — if there's a queued message when the tool is called, it returns immediately.

registry

thread metadata is persisted to ~/.mira/registry.json:

{
  "threads": {
    "my-project": {
      "threadId": "1513348392011694264",
      "project": "my-project",
      "name": "my-project",
      "parentChannelId": "1513094027011166279",
      "createdAt": "2026-06-08T00:00:00.000Z"
    }
  }
}

this survives restarts so find_or_create_thread can return existing threads without hitting the discord api.

tools

the extension registers these tools with the pi runtime:

| tool | description | |------|-------------| | find_or_create_thread | look up a thread in the registry or create a new one. posts a link in the parent channel on creation | | send_message | send a message to a thread by id | | read_messages | fetch recent messages (default 20, chronological). includes the agent's own messages | | list_threads | list all tracked project threads from the registry | | wait_for_message | block until a message arrives. timeout in seconds (default 300) |

install

mkdir -p ~/.pi/agent/extensions/mira
cp index.ts package.json ~/.pi/agent/extensions/mira/
npm --prefix ~/.pi/agent/extensions/mira install --omit=dev

dependencies

• discord.js ^14 — discord gateway client
• @earendil-works/pi-coding-agent (peer) — pi extension api types
• typebox (peer) — runtime tool parameter validation