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. |
Add one
Section titled “Add one”Run add plugin with the plugin’s name inside your project:
bunx roundtable add plugin dicebunx roundtable add plugin codex-imagesbunx roundtable add plugin release-noticeEach 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:
bun testdice 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 = 11You 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
Section titled “codex-images”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
Section titled “release-notice”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
shaand 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:
set -euo pipefailprevious=$(cat data/announced-release 2>/dev/null || true)commits='[]'if [ -n "$previous" ]; then commits=$(git log --format=%s "$previous..HEAD" | jq -R . | jq -s .)fiprintf '{"sha":"%s","commits":%s}\n' "$(git rev-parse --short HEAD)" "$commits" > release.jsonThe 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.
Change the copy
Section titled “Change the copy”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.tsexportscreateReleaseNotice({ releaseFile, dataDir, announce }). Give itdataDirwhen your config’sdataDiris not./data,releaseFilewhen your deploy writes the file elsewhere, andannounceto post somewhere other than the coordinator’s channel; the config then lists the result of that call in place ofreleaseNotice. The announcement text is thenoticeTextfunction.- Each file exports a function (
createDice,createCodexImages,createReleaseNotice) that takes the part a test replaces, a random source, afetch, or the placesrelease-noticereads and posts to, and the ready-made plugin built from it (dice,codexImages,releaseNotice) that the config lists. - The tests beside them run offline:
dicewith a fake random source,codex-imageswith a fakefetch,release-noticewith temporary directories and its ownannounce.
To remove one, delete its two files and its entry in roundtable.config.ts.
Official packages
Section titled “Official packages”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.