# Wire Cursor into your menu bar

Cursor has no first-class notification hook, but the agent is excellent at following rules. We'll set up two paths: a Cursor rule the agent will execute on task completion, and a `tasks.json` entry you can bind to a keystroke for manual pings.

## One-click setup

### Skip the manual steps

Copy a ready-made prompt and paste it into any AI coding agent — Claude Code, Codex, Gemini, Cursor, or Aider. It detects your CLI and wires Lounge up for you.

## Step 1 — Enable the Monitor in Lounge

1. Right-click the Lounge icon in the menu bar and pick **Settings**.
2. Open the **Monitor** tab.
3. Toggle **HTTP listener** on. Optionally enable the unread badge and auto-open.

The Monitor tab and the listener itself only become active with a valid Lounge Pro license. The toggle is a no-op until you activate one in Settings → License.

## Step 2 — Smoke-test the listener

Before touching your AI agent, confirm the listener accepts a request. Run this in any terminal — you should see a new row appear in the LoungePanel.

```bash
curl -X POST http://127.0.0.1:8866/notify \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello from curl","body":"Lounge is listening","source":"smoke-test","level":"info","project":"setup","event":"smoke-test","status":"complete"}'
```

## Step 3 — Add a Cursor rule (recommended)

Create `.cursor/rules/lounge-notify.md` in your project root. Cursor loads rule files automatically and the agent will pick up the instruction to curl Lounge whenever it finishes a task or needs you.

````markdown
# .cursor/rules/lounge-notify.md

When you finish a long-running task or hit a point where you need my input,
run this shell command so Lounge pings my menu bar:

```bash
curl -s -X POST http://127.0.0.1:8866/notify \
  -H 'Content-Type: application/json' \
  -d '{"title":"Cursor finished","body":"<short summary here>","source":"cursor","level":"info","project":"$(basename \"$PWD\")","status":"complete"}'
```

Use status: "blocked" and level: "warn" when you are waiting on my input instead of a completion. Keep the body under 240 characters.
````

## Step 4 — Optional: a manual task

If you prefer pressing a keystroke to fire a ping yourself, drop this into `.cursor/tasks.json`. Run it from the command palette via _Tasks: Run Task_.

```json
// .cursor/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Lounge: notify task complete",
      "type": "shell",
      "command": "curl -s -X POST http://127.0.0.1:8866/notify -H 'Content-Type: application/json' -d '{\"title\":\"Cursor task done\",\"body\":\"${input:message}\",\"source\":\"cursor\",\"level\":\"info\",\"project\":\"${workspaceFolderBasename}\",\"status\":\"complete\"}'",
      "presentation": { "reveal": "silent", "panel": "dedicated" },
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "message",
      "type": "promptString",
      "description": "What finished?",
      "default": "Task complete"
    }
  ]
}
```

## Step 5 — Background Agents (advanced)

**Security note:** a Cloudflare tunnel exposes your Lounge listener to the public internet. The endpoint has no authentication — only do this on a trusted network, and tear the tunnel down when you're finished.

Cursor Background Agents run in Cursor's cloud and cannot reach `127.0.0.1`. If you really want cloud-agent notifications, tunnel your loopback out:

```bash
# Expose 127.0.0.1:8866 to Cursor's cloud (advanced, security-sensitive!).
# Only do this on a trusted network — the tunnel URL is world-reachable.

brew install cloudflared
cloudflared tunnel --url http://127.0.0.1:8866

# In Cursor: Settings → Background Agents → Webhook URL →
# paste https://<something>.trycloudflare.com/notify
```

## Troubleshooting

### Nothing shows up in Lounge

Confirm Settings → Monitor is enabled and your license is active. The listener silently refuses to start without a valid license, even if the toggle is on.

### Port 8866 already in use

Another process is bound to 8866. Find it with `lsof -iTCP:8866 -sTCP:LISTEN` and stop it. The port is fixed in the current build.

### Connection refused from the CLI

The listener only binds to 127.0.0.1. If your agent runs in a container or VM, forward the port or use `host.docker.internal:8866` instead of localhost.

### Cursor tasks.json does not fire automatically

tasks.json only runs on demand (via the command palette or a keybinding). For automatic post-turn notifications, prefer the Cursor rule approach — the agent itself decides to run the curl as part of its workflow.

### Background Agent cannot reach 127.0.0.1

Cursor Background Agents run in the cloud, so loopback is unreachable. Use the Cloudflare tunnel recipe above, or keep using the local IDE flow — Background Agents are the exception, not the default path.