Cursor Plugin

See also: Quickstart Guide for basic Thrum setup, Claude Code Plugin for the Claude Code integration, Codex Plugin for the Codex skill bundle, MCP Server for the native MCP transport.

Overview

The Thrum plugin for Cursor deploys coordination infrastructure into your project's .cursor/ directory. It gives Cursor agents native access to Thrum messaging through slash commands, lifecycle hooks, safety rules, and MCP configuration — without manual setup.

What you get:

• 11 slash commands — prime, send, inbox, quickstart, restart, and more
• 5 hooks — SessionStart, beforeShellExecution, Stop, PreCompact, and PostCompact keep your agent oriented across sessions and compaction
• 2 rules — .mdc files for sync worktree safety and session lifecycle
• 4 skills — Thrum coordination, orchestration, project setup, and role configuration
• 1 agent — Background message listener sub-agent template
• MCP config — Thrum MCP server wired up automatically

Prerequisites

Before installing the plugin, you need Thrum installed and initialized:

# Install thrum
curl -fsSL https://raw.githubusercontent.com/leonletto/thrum/main/scripts/install.sh | sh
# Or: brew install leonletto/tap/thrum
# Or: git clone https://github.com/leonletto/thrum.git && cd thrum && make install

# Initialize in your repository
cd /path/to/your/repo
thrum init

thrum init handles the full setup: prompts for runtime detection, generates coordination instructions, starts the daemon, registers your agent, and starts a session.

Verify the daemon is running:

thrum daemon status

Installation

The Cursor plugin is installed via a local install script. It deploys files directly into your project's .cursor/ directory.

From local clone

# Clone the Thrum repository (if you haven't already)
git clone https://github.com/leonletto/thrum.git
cd thrum

# Install into the current repo (or specify --target)
cursor-plugin/local-install.sh
cursor-plugin/local-install.sh --target /path/to/project

The installer:

1. Creates .cursor/rules/, .cursor/skills/, .cursor/commands/, .cursor/agents/
2. Copies .mdc rule files
3. Copies skills, commands, and agent definitions (if synced)
4. Writes hooks.json with resolved absolute paths to hook scripts
5. Writes mcp.json with the Thrum MCP server configuration
6. Adds .cursor/ to .gitignore

Verify installation

Start a new Cursor session. The SessionStart hook will prompt you to run thrum prime to load your session context. Running it displays your agent identity, team roster, unread messages, and daemon health.

Updating

After upstream changes to the Thrum repository, re-sync and re-install:

scripts/sync-skills.sh        # Sync skills/commands from claude-plugin source
cursor-plugin/local-install.sh # Re-deploy to .cursor/

Slash Commands

All commands are available as .md files in .cursor/commands/.

Hooks

The plugin configures five hooks in .cursor/hooks.json:

SessionStart

Prompts the agent to run thrum prime when a Cursor session begins. Running prime loads agent identity, team roster, unread messages, git branch, and daemon health.

beforeShellExecution

Runs block-sync-worktree-cd.sh before any shell command. Blocks commands that would cd into Thrum's internal .git/thrum-sync/a-sync worktree — this prevents accidental writes to the sync branch.

Stop

Runs stop-check-messages.sh when the agent stops. Checks for unread messages and reminds the agent to process them before ending. Has a 15-second timeout.

PreCompact

Runs pre-compact-save-context.sh before context compaction. Saves session state (decisions, next steps, work-in-progress) so it can be restored afterward.

PostCompact

Runs post-compact-recover.sh after context compaction. Tells the agent to run thrum prime to recover its bearings. In multi-agent mode, it also checks the listener heartbeat and respawns if stale.

Rules

Two .mdc rule files are deployed to .cursor/rules/:

Both rules have alwaysApply: true — they're active in every conversation.

Skills

Four skills are deployed to .cursor/skills/:

The thrum skill includes the same 8 resource documents as the Claude Code plugin:

MCP Server Integration

The installer writes .cursor/mcp.json with the Thrum MCP server configuration:

{
  "mcpServers": {
    "thrum": {
      "type": "command",
      "command": "thrum",
      "args": ["mcp", "serve"]
    }
  }
}

This provides 4 core messaging tools (send_message, check_messages, wait_for_message, list_agents) plus broadcast_message. See MCP Server for the full API.

Background Listener

The plugin includes a message-listener.md agent definition in .cursor/agents/. This is a lightweight sub-agent template that blocks on thrum wait for incoming messages — useful for async coordination in multi-agent setups.

Cursor Plugin vs Claude Code Plugin

Both plugins share the same underlying skill content — scripts/sync-skills.sh keeps them in sync from the Claude plugin source.

Troubleshooting

"Thrum not initialized" on session start

Run thrum init in your repository root (it starts the daemon automatically).

No context injected after install

Verify the hook is present: check that .cursor/hooks.json exists and contains the sessionStart entry. Re-run local-install.sh if missing.

Messages not arriving

Check daemon status with thrum daemon status. The daemon must be running for messaging to work. Start it with thrum daemon start.

Skills or commands missing

Run scripts/sync-skills.sh from the Thrum repository root to sync the latest skills and commands from the Claude plugin source, then re-run local-install.sh.

Next Steps

• MCP Server — the MCP server the plugin configures
• Claude Code Plugin — the equivalent plugin for Claude Code users
• Codex Plugin — the equivalent skill bundle for Codex users
• Multi-Agent Support — coordination patterns across agents
• Identity System — agent naming, THRUM_NAME, and multi-agent worktree setup