Use Thrum with Codex

With the Thrum plugin installed, you can ask your coordinator to put an agent on Codex. Your coordinator is the agent you talk to, which starts the other agents, hands out work and reports back to you. That agent starts with the same briefing as your Claude Code agents (a short summary of who it is, where the project stands and what it has been sent) and reads messages from the same inbox, so the whole team works from one place.

The quickstart starts your coordinator on Claude Code. This plugin matters for the agents the coordinator creates on Codex.

What the plugin gives you

• A briefing at the start of every Codex session. The agent loads its identity, the project state and its unread messages before its first turn.
• The Thrum skills. Codex agents get a matching set to the Claude Code plugin: the Thrum commands for messaging and restarts, and the playbooks for the coordinator, implementer and researcher roles.
• A guard on Codex shell commands and a nudge about unread mail. The plugin stops a shell command that would move into the folder holding Thrum’s message history, so an agent cannot write there by accident. It also stops a command that would add Thrum’s private keys to Git or send them over the network. It also reminds an agent to read unread messages before it stops.

Before you start

• Thrum set up in your repository, with a running coordinator. The quickstart starts one on Claude Code. That is the recommended way to begin, and the steps on this page assume it.
• Codex, version 0.130.0 or newer, on the machine where the agent will run. Sign in to Codex and start it once, so that it creates its settings file at ~/.codex/config.toml. Signing in is yours to do. Thrum does not sign in for you.
• jq and python3 on that machine, which the installer uses.
• thrum on your PATH. The installer stops with a message if your Thrum is too old for the plugin.

Add Codex agents through your coordinator

Caution

Thrum starts Codex agents with Codex’s sandbox set to full access, because they do not work without it. Thrum always starts them this way. Nothing in Codex then limits an agent to your repository: it can read and change whatever your user account can. Give a Codex agent only work you would trust with that access. For work where you’d rather approve commands yourself, use an agent on Claude Code, which stops to ask before running a command it hasn’t been allowed. Answer permission prompts shows how to answer.

1. Ask your coordinator (in its terminal, or in My Inbox, your inbox in Thrum’s web UI):

   Install the Thrum plugin for Codex in this repository.

   Your coordinator runs Thrum’s installer from inside the repository. It adds the Thrum plugin to Codex and sets up Codex’s permissions for this repository. Settings you already have stay as they are. What the installer changes lists each change.

   To update the plugin later, ask your coordinator: Update the Thrum plugin for Codex in this repository, then restart the Codex agents. Running Codex agents load the update only after a restart.

2. A worktree is a separate checkout of your repository on its own branch, so the agent’s changes stay apart from yours. Ask your coordinator: Create an agent on Codex to write tests for the parser. Give it its own worktree. Say the runtime in your message. A runtime is the AI coding tool an agent runs in, such as Claude Code or Codex. This is an example conversation. Your coordinator’s wording will differ.

   You:
     Create an agent on Codex to write tests for the parser. Give it its own worktree.
   
   Coordinator:
     Created tests_parser on Codex in a new worktree and sent it the task. I'll tell you when it replies.
   
   You:
     Which tool is tests_parser running?
   
   Coordinator:
     Codex.

   The New Agent dialog in the web UI has no runtime field and always creates Claude Code agents. For Codex, ask the coordinator.

3. Check it worked. On the Agents grid, a card for the new agent appears. Open it, then its Terminal tab, which shows Codex’s own screen. The agent prints one line that names itself:

   @tests_parser primed (implementer/parser). Writing parser tests. Standing by.

   If you see no such line, type $thrum:thrum-prime in that agent’s own terminal, or in its Terminal tab if you have Pro. It loads the briefing by hand. To check the install itself, ask your coordinator: Is the Thrum plugin installed in Codex? It should say thrum@thrum-marketplace is installed and enabled.

If your coordinator will run in Codex

Skip this section if your coordinator runs in Claude Code. If Codex will be your first agent, there is no coordinator to ask yet, so install the plugin yourself.

1. Check the prerequisites.

   codex --version
   jq --version
   python3 --version

2. Go to your repository, where Thrum is already set up, and run the installer there. That also sets up Codex’s permissions for this repository, and the installer names the folder it did this for. If you run it anywhere else, it says the repository is not set up yet: run it again in the repository. To read it first, save it, then run the saved copy. Thrum is published by THRUM LLC and built by Leon Letto (About).

   cd my_app
   curl -fsSLO https://raw.githubusercontent.com/thrum-team/thrum-pro/main/codex-plugin/plugins/thrum/scripts/install-plugin.sh
   less install-plugin.sh
   bash install-plugin.sh

   You can run the installer again at any time to update. If it says the plugin remains disabled, run the installer again. Use this installer, not Codex’s own plugin commands (codex plugin marketplace add and codex plugin add). Those commands skip the permission step, and Codex then blocks Thrum commands.

3. Start your coordinator with thrum tmux start, as in the quickstart. Start it this way, not by typing codex: Thrum then starts Codex with the settings it needs.

4. Check the install.

   codex plugin list

   It shows thrum@thrum-marketplace as installed and enabled.

What the installer changes

• It registers thrum-team/thrum-pro with Codex as a plugin catalog and copies the plugin into Codex’s plugin folder. thrum-team/thrum-pro is where the plugin is distributed from. It holds the plugin’s text files, not the Thrum program. Free and Pro both use this same plugin.
• In ~/.codex/config.toml, it turns the plugin on, and turns on features.plugin_hooks, the Codex setting that lets plugins run hooks. Hooks are scripts Codex runs by itself at a set moment, such as when a session starts.
• It adds a permission profile named thrum-workspace to ~/.codex/config.toml. The profile lets the Codex sandbox reach Thrum’s daemon, its background process on your machine, and its log folder for this repository.
• Settings you already have stay as they are.

Tips

Tip

After you upgrade Thrum, ask your coordinator: Refresh the Codex setup in my existing Codex worktrees. The new Thrum version then installs its updated Codex hooks there.

Note

A Codex agent reloads its briefing by itself after a compaction. Mix runtimes and models has the details.

Next steps

• Mix runtimes and models: choose the tool and model for each task.
• Messaging between agents: how the coordinator and a Codex agent talk.
• Use Thrum with Cursor: the same idea for Cursor.