## @remixhq/cursor-plugin

Cursor plugin for Remix collaboration workflows. Functional mirror of the [Claude Code plugin](https://github.com/RemixDotOne/remix-claude-plugin), adapted for Cursor's hook and plugin schemas.

### Install

In Cursor, open the command palette and run:

```
Plugins: Add Marketplace
```

Enter the marketplace URL:

```
https://github.com/RemixDotOne/remix-cursor-marketplace
```

Then install the `remix` plugin from the marketplace browser. After installation, reload Cursor's agent (close and reopen the chat panel) so the hooks and MCP server come up.

### What's included

| Component | Files | Purpose |
| --- | --- | --- |
| MCP server | `dist/mcp-server.cjs` (registered via `mcp.json`) | Exposes the full `remix_collab_*` tool surface to the Cursor agent. |
| Skills | `skills/*/SKILL.md` (9 skills) | Workflow guidance the agent can read on demand. |
| Agent | `agents/remix-collab.md` | A specialized Remix collaboration subagent. |
| Hooks | `hooks/hooks.json` (5 hooks) | Wires Cursor's hook events to the plugin's recording / advisory logic. |

### Hook map

| Cursor event | Script | Purpose |
| --- | --- | --- |
| `beforeSubmitPrompt` | `dist/hook-user-prompt.cjs` | Creates per-turn pending state, surfaces recovery status, and auto-spawns branch init when hook-owned recovery is needed. |
| `preToolUse` (matches `Shell`) | `dist/hook-pre-git.cjs` | Surfaces "prefer Remix memory over raw git" advisories on the agent message channel. |
| `postToolUse` (matches MCP / `Shell` / `Read` / `Write` / `Delete`) | `dist/hook-post-collab.cjs` | Tracks which Remix-bound repos this turn touched. |
| `afterAgentResponse` | `dist/hook-after-response.cjs` | Primary recorder: caches the assistant text and finalizes the completed turn into Remix. |
| `stop` | `dist/hook-stop-collab.cjs` | Backstop: sweeps orphaned or queued prompts, retries pending finalization, and drains local recording queues. |

### Differences vs. the Claude plugin

These are intentional — Cursor and Claude expose different hook event sets and payload schemas:

- **No prompt context injection.** Cursor's `beforeSubmitPrompt` cannot inject "additional context" into the agent the way Claude's `UserPromptSubmit` could. Routing advisories ("prefer memory before git") live primarily in the bundled `agents/` and `skills/` markdown plus MCP tool descriptions; when useful, the hook also folds recovery/routing notes into Cursor's `user_message` channel. Branch-unbound recovery is hook-owned: when the prompt fires on a checked-out branch that hasn't been bound but the repo has at least one other bound branch, the hook spawns `remix collab init` detached and tells the user via `user_message` that the first turn will be recorded retroactively once init finishes.
- **Assistant response captured separately.** Cursor's `stop` payload omits the assistant text, so the plugin uses an `afterAgentResponse` hook to cache the latest assistant message per conversation and finalize the turn. The cache lives next to the pending-turn state in `${TMPDIR}/remix-cursor-plugin-hooks/<conversation_id>.assistant-response.json` and is cleared after a successful finalize. The `stop` hook remains as a sweep and retry backstop.
- **No per-turn token usage.** Cursor does not yet expose token usage in any hook payload. Turns are recorded with `turnUsage = null`; the dashboard's "charged on" badge will read as `(unknown)` for Cursor turns until Cursor exposes usage.
- **No subscription-tier capture.** Cursor has no equivalent of `claude auth status --json`. The `agent.plan` field is recorded as `null` for Cursor turns.

### Local development

```bash
npm install
npm run build:local-deps   # builds @remixhq/core and @remixhq/mcp from sibling dirs
npm run build              # bundles the MCP server + 5 hook entrypoints
```

The build emits to `dist/` with executable bits set on every `.cjs` entry.

### Configuration

| Env var | Default | Purpose |
| --- | --- | --- |
| `REMIX_CURSOR_PLUGIN_HOOK_STATE_ROOT` | `${TMPDIR}/remix-cursor-plugin-hooks` | Per-conversation pending-turn state and assistant-response cache. |
| `REMIX_CURSOR_PLUGIN_HOOK_DIAGNOSTICS_DIR` | `~/.cursor/plugins/data/remix-remix` | NDJSON hook diagnostics log + last 50 events surfaced via `remix_collab_hook_diagnostics`. |
| `CURSOR_CONFIG_DIR` | `~/.cursor` | Override the Cursor config root used to derive the diagnostics dir. |
| `CURSOR_PROJECT_DIR` / `CLAUDE_PROJECT_DIR` | — | Final fallback when the hook payload contains no `cwd` or `workspace_roots`. |
# remix-cursor-plugin
