Skip to content

Official plugins and packages

pi-roundtable ships three plugins as files you copy into your project. You can read, change, or delete your copy like any plugin file.

Plugin What it does
codex-images Draws agents’ avatars from a prompt and reference pictures, through your ChatGPT subscription login.
dice Gives agents a roll_dice tool.
release-notice After a deploy, posts once which commits the new release added, and which channels the last shutdown cut short.

Run add plugin with the plugin’s name inside your project:

Terminal window
bunx roundtable add plugin dice
bunx roundtable add plugin codex-images
bunx roundtable add plugin release-notice

Each command writes plugins/<name>.ts and plugins/<name>.test.ts, imports the plugin in roundtable.config.ts, and lists it in plugins. The three names are reserved: add plugin copies the official plugin for them and keeps the hello template for every other name. If either file of a plugin already exists, the command stops without writing anything. See CLI for everything add plugin checks.

Run the tests in your project:

Terminal window
bun test

dice adds one tool, roll_dice, that members and above can call. It takes an expression and answers with plain text:

2d6+3: [3, 5] + 3 = 11

You can ask for it in a message to an agent, such as “Roll 4d6 and drop the lowest.” The agent calls the tool and reads you the result.

Write It means
2d6, d20 Roll that many dice with that many sides.
+3, -1 Add or subtract a number.
2d6+1d4-1 Several groups in one expression.
4d6k3, 4d6kh3 Keep the 3 highest dice.
4d6kl1 Keep the lowest die.
4d6d1, 4d6dl1 Drop the lowest die.
4d6dh1 Drop the highest die.
dF, 3dF Fate dice, which add -1, 0, or +1 each. Without a count it rolls 4.

Dropped dice show in parentheses, as in 4d6k3: [5, (1), 6, 3] = 14. If an expression exceeds the limits or cannot be parsed, the tool says what to fix so the agent can try again. The limits are 100 dice in all, 1000 sides on a die, 200 characters, and 1000000 in a plain number.

dice needs no login and no setting. Its copy-in source template implements the tool.

codex-images fills the images slot, the part the core uses to draw pictures for generate_image. Agents’ own avatars are composed characters since 0.23 and do not use it. roundtable doctor reports whether a plugin fills the slot. Its copy-in source template is a short file: it builds the plugin with createCodexImages from pi-roundtable/kit, which draws through the kit’s drawCodexImage. A fix to the protocol arrives with an upgrade of the package, not with a new copy.

It needs a login to the openai-codex provider, the same login mechanism the agents use for their models. When the host has none, the plugin refuses to start and the message says to log in to openai-codex. The plugin reads the login each time it draws, picking up refreshed tokens. Pass createCodexImages({ onMissingLogin: "warn" }) to let a host without the login start: setup logs a warning, and a drawing then fails with the same error.

When Codex refuses a request, usually because of the prompt, it fails with ImageNotGeneratedError. Repeating the same prompt fails again. A drawing is aborted with the turn that asked for it. A request has a five-minute limit, and a response over 32 MiB is refused. The model name only routes the request, because the backend picks the image model itself; it is the kit’s CODEX_IMAGE_MODEL, and createCodexImages({ model }) changes it. A copy made before 0.19.0 holds the whole client and keeps working as it was, without the abort and the size limit, until you copy the template again.

release-notice announces a deploy. Its copy-in source template implements the announcement and shutdown tracking. It posts in the coordinator’s channel, once, after the agent server’s channels are up:

  • When the running release is not the one last announced, it posts the new sha and the commits the release added.
  • When the previous shutdown cut work short, it also names those channels. A shutdown waits three minutes by default (drainSeconds) for running work before it gives up on it.
  • A restart of the same release with nothing cut short posts nothing, and so does a start with no release.json.

It needs your deploy to write release.json into the directory the bot runs in, before the bot starts. The file holds the commit the release was built from and the subjects of the commits it added since the release last announced, newest first, so a release whose announcement failed or never ran is not skipped over:

{ "sha": "abc1234", "commits": ["fix: handle an empty reply", "feat: add a notes tool"] }

The plugin keeps the sha it last announced in data/announced-release, so a deploy script on the same host can read the range’s start from there. This script stops the deploy when git log or jq fails, and the first deploy, with nothing announced yet, gets an empty commits list:

Terminal window
set -euo pipefail
previous=$(cat data/announced-release 2>/dev/null || true)
commits='[]'
if [ -n "$previous" ]; then
commits=$(git log --format=%s "$previous..HEAD" | jq -R . | jq -s .)
fi
printf '{"sha":"%s","commits":%s}\n' "$(git rev-parse --short HEAD)" "$commits" > release.json

The plugin remembers what it announced in announced-release, and the channels a shutdown cut short in aborted-on-shutdown.json, both in ./data. It records an announcement only after the post succeeds, so a failed post is tried again at the next start. A release.json that is not valid, such as one with an empty sha, fails with its path in the log and posts nothing.

The copy lives in your project, so edit it like any plugin.

  • In plugins/dice.ts, the limits are constants at the top of the file, and the tool’s description repeats them to the model, so change both together.
  • In plugins/codex-images.ts, the model that routes the request is a constant.
  • plugins/release-notice.ts exports createReleaseNotice({ releaseFile, dataDir, announce }). Give it dataDir when your config’s dataDir is not ./data, releaseFile when your deploy writes the file elsewhere, and announce to post somewhere other than the coordinator’s channel; the config then lists the result of that call in place of releaseNotice. The announcement text is the noticeText function.
  • Each file exports a function (createDice, createCodexImages, createReleaseNotice) that takes the part a test replaces, a random source, a fetch, or the places release-notice reads and posts to, and the ready-made plugin built from it (dice, codexImages, releaseNotice) that the config lists.
  • The tests beside them run offline: dice with a fake random source, codex-images with a fake fetch, release-notice with temporary directories and its own announce.

To remove one, delete its two files and its entry in roundtable.config.ts.

The official packages install with bun add at their matching lockstep versions. Each requires the matching pi-roundtable minor version.

Package What it adds
pi-roundtable-drawing Local image tools for relationship maps, symbols, geometry, and card spreads.
pi-roundtable-coding Repository tools backed by an out-of-process Pi coding worker.
pi-roundtable-web The owner app: rooms with the agent team, approval cards, yolo and long-running modes, an installable PWA with push, and a console for conversations, team status, and memory notes.
pi-roundtable-sandbox Guest-only Discord channels isolated in Docker on Linux.
pi-roundtable-mcp Owner-managed MCP connectors and remote MCP access.
pi-roundtable-browser A browser worker for agents: browser_task drives agent-browser in a Docker container with no route to the host’s private networks.
pi-roundtable-webchat A web chat for people an OpenID Connect provider signs in, with private conversations, live progress, and approval cards.
pi-roundtable-line A LINE Messaging API transport: a signed webhook, an allowlist of chats, one consumer, and pushes sent under a sender name, a retry key, and a quota check.

See What plugins can add for other plugin features and Test a plugin for testing.