Codex Plugin

Prerequisites: Thrum installed and initialized (thrum init), and Codex installed with a local skills directory (~/.codex/skills).

Overview

Codex does not currently use the Claude-style plugin marketplace model. Instead, Thrum integration is packaged as a Codex skill bundle in codex-plugin/skills.

The bundle is split into focused skills:

• thrum-core — durable messaging, groups, identity, worktree boundaries
• thrum-ops — quickstart/inbox/sent/wait/context/daemon/sync operational flows
• thrum-role-config — generate or update .thrum/role_templates
• project-setup — turn design docs into Beads epics/tasks before coding

Prerequisites

• Thrum installed and available on PATH
• Thrum initialized in the repo (thrum init)
• Codex installed with local skills directory (~/.codex/skills)

If you have not initialized Thrum yet:

thrum init  # also starts the daemon automatically
thrum quickstart --name myagent --role implementer --module auth

Installation

From GitHub

Clone the Thrum repository and run the install script:

git clone https://github.com/leonletto/thrum.git
cd thrum
./codex-plugin/scripts/install-skills.sh

From Local Clone

If you already have the Thrum repository cloned locally:

cd /path/to/thrum
./codex-plugin/scripts/install-skills.sh

This installs the bundled skills into ~/.codex/skills (or $CODEX_HOME/skills if CODEX_HOME is set).

Verify installed skills

find "${CODEX_HOME:-$HOME/.codex}/skills" -maxdepth 1 -type d -name "thrum-*" -o -name "project-setup"

Restart Codex

Restart Codex after installation so the new skills are loaded.

Updating Skills During Development

After editing files under codex-plugin/skills/, sync updates into your local Codex installation:

./codex-plugin/scripts/sync-skills.sh

sync-skills.sh replaces installed copies with your local versions.

Usage Patterns

Multi-agent coordination

Ask Codex to coordinate work across agents using Thrum. The thrum-core skill handles audience routing (@agent, @group, @everyone) and durable message/reply workflows.

Session operations and triage

When you need to bootstrap sessions, triage unread messages, verify delivery on messages you authored, or check daemon health, thrum-ops provides operational workflows and command references.

Role template generation

When team structure changes, use thrum-role-config to detect environment context and regenerate .thrum/role_templates/<role>.md with clear autonomy and scope boundaries.

Manual Installation (Optional)

If you prefer manual copy instead of scripts:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R codex-plugin/skills/thrum-core "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R codex-plugin/skills/thrum-ops "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R codex-plugin/skills/thrum-role-config "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R codex-plugin/skills/project-setup "${CODEX_HOME:-$HOME/.codex}/skills/"

Troubleshooting

Skills do not appear in Codex

• Confirm install destination: echo "${CODEX_HOME:-$HOME/.codex}/skills"
• Re-run ./codex-plugin/scripts/install-skills.sh --force
• Restart Codex

Skill updates are not reflected

• Run ./codex-plugin/scripts/sync-skills.sh
• Restart Codex after sync

Thrum commands fail inside skill workflows

• Check daemon status: thrum daemon status
• Verify identity/session: thrum whoami && thrum session start
• Confirm repo initialization: thrum status

Codex Bundle vs Claude Plugin

Next Steps

• Claude Code Plugin — the equivalent plugin for Claude Code users, with slash commands and automatic hooks
• Agent Coordination — practical multi-agent workflows that the Codex skills support
• Role Templates — role-based preamble templates that thrum-role-config generates
• Workflow Templates — the project-setup skill's design → plan → implement pipeline in detail