Agent integration: add first-party Cursor plugin and mixed-agent setup guidance

Start with the existing shared plugin payload, the plugin-layout test test_plugin_layout_is_consolidated, and the canonical Agent Integration documentation. Verify Cursor's actual plugin loader and hook behavior, then trace the existing plugin installation, marker, approval, and documentation-sync paths before choosing the implementation scope. Done means the acceptance criteria and tests pass; an open linked pull request (#4225) indicates work is already underway.

Description

Add a first-party Cursor integration so teams using Claude Code, Cursor, and Codex in the same repositories can keep Worktrunk configuration and lifecycle behavior consistent.

Worktrunk already ships configuration skills and activity tracking for Claude Code, Codex, OpenCode, Pi, oh-my-pi, and Gemini CLI. Cursor now has the corresponding extension points:

• Cursor Plugins with .cursor-plugin/plugin.json and repository marketplaces
• Agent Skills using SKILL.md
• agent lifecycle hooks, including beforeSubmitPrompt, stop, and sessionEnd
• Cursor CLI (agent / cursor-agent), including plugin marketplaces and --worktree
• checked-in .cursor/worktrees.json setup for Cursor-created worktrees

There is currently no .cursor-plugin manifest, wt config plugins cursor command, Cursor section in wt config show, or Cursor-specific guidance in the Agent Integration documentation. Searches for Cursor in the tracker return terminal-cursor issues rather than Cursor-the-product; this does not appear to duplicate an existing request.

Context

At our company, contributors to the same repositories use Claude Code, Cursor, and Codex. The shared team behavior belongs in .config/wt.toml, but each agent needs enough integration to discover that configuration and participate in Worktrunk workflows.

The desired default is that Worktrunk owns worktree creation and lifecycle for every agent:

wt switch --create -x claude feature
wt switch --create -x agent feature
wt switch --create -x codex feature

Claude Code can additionally route its native worktree lifecycle through Worktrunk because it exposes WorktreeCreate / WorktreeRemove. Cursor does not expose equivalent hooks. The integration should state this difference rather than promise feature parity: Cursor gets the Worktrunk skill, local activity markers, and a documented Worktrunk-owned launch path; Cursor-native worktrees get only the setup compatibility that Cursor's API permits.

Proposed scope

Cursor plugin packaging

• Add the loader-mandated .cursor-plugin/marketplace.json repository pointer.
• Add a Cursor manifest under the existing shared plugins/worktrunk/ payload, rather than creating a second copy of the skills or shim.
• Reuse the generated real-file plugins/worktrunk/skills/ mirror so the canonical skills/worktrunk/SKILL.md remains single-sourced.
• Give Cursor its own native hook definition (inline or at a Cursor-specific path). Do not make Cursor and Claude compete for the conventional hooks/hooks.json slot.
• Extend test_plugin_layout_is_consolidated and plugins/worktrunk/CLAUDE.md with the verified Cursor loader paths and drift guards.
• Verify the result through Cursor's real plugin loader (agent --plugin-dir and/or a scratch marketplace), not only by validating JSON.

This follows the consolidation work in #2789, #2807, #3431, and #3440: one shared payload, one loader-mandated pointer per tool, generated skill mirrors rather than hand-maintained copies, and tests that pin each loader's actual conventions.

Activity tracking

Map Cursor's local agent lifecycle to the existing marker contract:

• beforeSubmitPrompt → wt config state marker set 🤖
• stop → wt config state marker set 💬
• sessionEnd → wt config state marker clear

The commands should:

• reuse the canonical wt.sh / Windows shim rather than duplicate command-resolution logic;
• resolve against CURSOR_PROJECT_DIR (or the verified stable workspace path) with global -C, so a shell cd during a turn cannot mark another repository;
• fail open when Worktrunk is unavailable, as the existing decorative marker hooks do;
• be verified against Cursor IDE and Cursor CLI behavior, including Windows if Cursor's hook runner supports it.

Cloud Agents do not provide the same sessionStart / sessionEnd boundary and their Git config is remote, so the docs should scope these markers to local sessions instead of claiming that they update a developer's local wt list from a cloud VM.

Configuration skill and mixed-agent workflow

Ship the existing /worktrunk configuration skill to Cursor. Extend the canonical skill/reference material only where Cursor behavior differs; do not fork a Cursor-only copy of the Worktrunk guidance.

The skill should be able to help configure a downstream repository that uses Worktrunk by:

• keeping shared lifecycle commands in checked-in .config/wt.toml;
• recommending wt switch --create -x agent when full Worktrunk lifecycle behavior is required;
• explaining that Cursor's /worktree and agent --worktree create Cursor-owned worktrees under Cursor's own path and retention policy;
• explaining that a skill cannot relocate the current Cursor chat into a newly created Worktrunk worktree;
• configuring Cursor-native worktree setup only when the user explicitly chooses that compatibility path.

Cursor-created worktrees

Document and test the safest supported bridge for downstream projects that intentionally use Cursor-native worktrees. A project-level .cursor/worktrees.json can live in the downstream repository, but it must not silently bypass Worktrunk's project-command approval system.

One candidate is to invoke the existing hooks from the Cursor-created worktree without --yes:

{
  "setup-worktree-unix": [
    "wt hook pre-start --foreground",
    "wt hook post-start"
  ]
}

The implementation should verify whether Cursor's setup runner can support that safely. If approval cannot be requested, the operation should fail and tell the user to review and pre-approve commands with wt config approvals add; the skill must never approve project commands on the user's behalf.

The limitations should be explicit:

• Cursor, not Worktrunk, chooses the worktree path and branch lifecycle.
• Cursor has no corresponding worktree-removal event, so Worktrunk pre-remove / post-remove hooks do not run when Cursor deletes the worktree.
• Cursor's automatic cleanup can discover and remove externally-created worktrees, so the interaction with Worktrunk-owned worktrees needs verification and documentation.
• This setup bridge is not equivalent to Claude Code's WorktreeCreate / WorktreeRemove integration.

If the safe bridge needs a new Worktrunk command rather than direct wt hook calls, that should be decided as a separate product surface rather than hidden in the plugin.

Installation and diagnostics

Provide one complete, accurately described installation path.

Cursor CLI currently supports non-interactive marketplace registration:

agent plugin marketplace add https://github.com/max-sixty/worktrunk

Plugin installation itself is available through /plugin / Customize. If added, wt config plugins cursor install can mirror the initial Codex integration by registering the marketplace and clearly directing the user to install Worktrunk interactively; it should not report the plugin installed when it only registered the marketplace. Add an uninstall command only if its behavior is a truthful inverse.

Also consider:

• Cursor availability detection that does not mistake an unrelated generic agent binary for Cursor (cursor-agent or structured version output may be safer);
• a Cursor section in wt config show with actionable installed / not-installed status;
• test harness support and snapshots for availability, install failures, already-installed state, and uninstall behavior;
• atomic writes for any Worktrunk-managed user file. Prefer asking Cursor's own CLI for marketplace/plugin state instead of inspecting undocumented internal paths.

These expectations follow the install and diagnostic coverage in #1807, #2512, #2819, #3594, #4019, and #4135.

Documentation scope

Update the existing canonical Agent Integration page rather than creating a separate Cursor page or broadly replacing existing Claude examples:

• Add Cursor to the capability table.
• Add Cursor installation instructions.
• Describe local activity tracking.
• Document wt switch --create -x agent as the full Worktrunk-owned workflow.
• Document the narrower .cursor/worktrees.json compatibility path and its approval, cleanup, and removal-hook limitations.
• Keep worktree isolation marked Claude-only unless Cursor adds create/remove interception hooks.
• Update the FAQ inventory of files Worktrunk creates or modifies if a new installer writes any state.
• Update wt config plugins help and snapshots if a Cursor subcommand is added.
• Update plugin-layout maintainer documentation.
• Regenerate skills/worktrunk/reference/ and plugins/worktrunk/skills/ through test_docs_are_in_sync; do not hand-edit generated mirrors.

This matches the maintainer direction on #2512: fold new agents into the existing integration page, avoid unrelated find/replace churn, and describe capability differences instead of presenting every agent as feature-identical.

Acceptance criteria

• A Cursor user can install or load the Worktrunk Cursor plugin from this repository.
• Cursor discovers the canonical Worktrunk configuration skill.
• Local Cursor sessions set 🤖 while working, 💬 while waiting, and clear the marker on a normal session end.
• Hook commands stay attached to the session's repository after shell directory changes.
• The documented default creates Cursor sessions in Worktrunk-owned worktrees with wt switch --create -x agent.
• The optional Cursor-native worktree setup path preserves Worktrunk's approval boundary and clearly documents its incomplete lifecycle semantics.
• wt config show and installer behavior are covered if CLI integration is added.
• Plugin layout, packaged assets, hooks, help output, and documentation sync are covered by tests.
• cargo run -- hook pre-merge --yes passes, including generated docs/help snapshots and the plugin-layout guard.

Out of scope

• Claiming Cursor has Claude Code's worktree-lifecycle parity when Cursor exposes no create/remove interception events.
• A Cursor statusline equivalent; no corresponding API is currently documented.
• An MCP server around wt; the CLI and skills already provide the needed interface.
• Automatically approving project-defined commands or adding --yes to generated project setup.