---
name: patchcord-subscribe
description: >
  Start a persistent background WebSocket listener that wakes the Cursor agent
  when new Patchcord messages arrive. Use ONLY when the user runs
  /patchcord-subscribe or when a project explicitly asks to auto-arm it.
---

User invoked `/patchcord-subscribe` — do NOT substitute `wait_for_message()`.
Start the persistent listener in a background Shell.

## Start

1. **Drain the inbox first.** Call the Patchcord `inbox` MCP tool (Cursor may
   expose it as `mcp_patchcord_inbox`). Process every pending message according
   to the patchcord inbox skill before starting the listener.

2. **Find the absolute project root.** Use the current session's git root or
   agent worktree. Do not rely on the ambient Shell cwd: the listener must read
   the `.cursor/mcp.json` for this project and therefore needs an explicit
   `cd`.

3. **Spawn the background listener** with Cursor's Shell tool:

   ```text
   Shell(
     description: "Patchcord realtime listener",
     block_until_ms: 0,
     command: "cd <ABSOLUTE_PROJECT_DIR> && patchcord subscribe | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}",
     notify_on_output: { pattern: "^PATCHCORD:", reason: "Patchcord message" }
   )
   ```

   Replace `<ABSOLUTE_PROJECT_DIR>` with the root found in step 2. The grep
   filter drops listener diagnostics and heartbeat lines; only `PATCHCORD:`
   lines wake the agent. `${PIPESTATUS[0]}` preserves `patchcord subscribe`'s
   exit code through the pipe. `subscribe.mjs` owns the pidfile and
   reconnect/backoff loop; do not re-arm it after every notification.

4. **Confirm one line:**
   `Patchcord listener active — I'll pick up new messages as they arrive.`

## When a notification fires

Cursor surfaces a line such as `PATCHCORD: 1 new from <sender>`:

1. Say: `Got a Patchcord ping — checking inbox.`
2. Call the Patchcord `inbox` MCP tool.
3. Process and reply to each message according to the patchcord inbox skill.
4. Do not spawn another listener unless the background Shell exited.

## Stopping

- End the Cursor agent session. The listener stops with it.
- Or run `patchcord subscribe --stop` from the project directory.

## Errors

Read the background Shell terminal output and surface the exact cause:

- `already running (pid N)` (exit 2) — another listener is active; report it
  and do not respawn.
- `ticket: token rejected (HTTP 401|403)` — the bearer token is invalid or
  expired.
- `no patchcord config found` — the listener was not started from a project
  containing `.cursor/mcp.json` (or a parent project directory).
- `subscribe: fatal: ...` — report the fatal line verbatim.

If the stream ends without one of these errors, it likely ended with the Cursor
session or because its stdout consumer closed. Start it again only when the
user invokes `/patchcord-subscribe` again.

**Forbidden on failure:** no hand-rolled `nohup ... &`, no pidfile editing, no
`curl`-to-MCP workarounds, and no re-arm loop after each inbox notification.