Add your own agent roles with role bundles

A role is what an agent is for, such as coordinator, implementer or reviewer. A role bundle is a role you wrote yourself, packed into one zip file: the instructions agents of that role start from, and optional skills. A skill is a folder of instructions an agent loads for one kind of job. Install a bundle once, and every agent you give that role gets its instructions and skills. Installing a bundle needs Pro.

Make a bundle

Ask your coordinator, the agent you talk to, which starts the other agents and hands out work. For example: Design a role for writing release notes that checks every entry against the changelog, and pack it into a role bundle. It drafts the role’s files and skills, checks the names, and packs them into a zip. It does this with Thrum’s role-setup skill, which comes with Thrum’s plugin for Claude Code, Codex, Cursor, OpenCode and Muse. Update the plugin first if your coordinator doesn’t know the skill.

Ask the coordinator to keep the folder it packed the zip from. To change the role later, it changes that folder and packs it again.

Install a bundle

In the web UI, open Settings, then Roles, and choose Upload bundle. Pick the zip, up to 10 MB. The result shows the old and new version, the skills, and any warnings.

In a terminal, give the command the path to the zip:

thrum roles bundle install release-notes.zip

Installing a bundle for a role you already installed replaces it, and the old one is saved in an archive folder. If an install fails, the bundle you had stays as it was. If a step after the swap goes wrong, the result lists it as a warning.

If the install says no role_config found, run /thrum:configure-roles in your AI tool, then install again.

On Free, Upload bundle is switched off and says “Role bundle upload is a Pro feature.” The command says the install needs a licence.

See and remove your bundles

Settings, Roles lists each installed bundle with its version, skills and state. thrum roles bundle list shows the same list. Seeing, removing and packing bundles are Free.

To remove a bundle, choose Remove on its row, or run thrum roles bundle remove <role>. Its files are moved to the archive, not deleted. Thrum refuses while an agent still has the role, and names the agents.

Role Rules on a bundle’s row opens the extra rules for that role. Role Rules are not part of a bundle, so each machine keeps its own. See Role Rules.

What your agents get

When you start or restart an agent whose role has a bundle with skills, Thrum copies the skills into the folder the agent works in, before its AI tool starts. They go in the folder that tool reads skills from, such as .claude/skills for Claude Code. This works on Claude Code, Codex, Cursor, OpenCode, GitHub Copilot and Muse.

Thrum tells git to ignore the copies, and replaces them at the next start. If you edit a copy, Thrum moves your edited version to the archive instead of overwriting it. Change the bundle, not the copy. A problem shows as a warning and never stops an agent from starting.

A bundle that is already installed keeps working, and its skills keep being copied, without a licence.

Back up your bundles

Thrum’s backups include your installed bundles and the Role Rules of every role. A restore puts them back. A bundle or rules file already on the machine is moved to the archive first, never overwritten. Back up and restore your Thrum data has the steps.

From the command line

• thrum roles bundle install <zip> installs or replaces a bundle. Pro.
• thrum roles bundle list lists installed bundles.
• thrum roles bundle remove <role> moves a bundle’s files to the archive.
• thrum roles bundle pack <folder> -o <zip> zips a folder after checking that it would install. It needs no running Thrum.

Each takes --json. See the CLI reference.

Next steps

• Watch your agents in the web UI: the Roles tab sits in Settings with the rest of the web UI.
• Plan with a coordinator, build with an implementer: the roles your agents already have.