# Notch MCP

A status readout at the top of your Mac that **any agent can write to, from any
MCP client**: Claude Code, Cursor, Windsurf, Zed, Conductor.

![Pendant style](docs/img/pendant.png)

---

## Why

Three agents running. One is refactoring, one is partway through the test suite,
one has been "almost done" for ten minutes, and you can't tell which without
finding the right window and reading back through scrollback.

So you check less often. Then you forget, and something that finished four
minutes ago sits there waiting for you.

The expensive part was never the two seconds of switching. It's that after you
switch, you don't come back.

Being an MCP server rather than an editor extension is what makes the fix
portable. Any agent in any MCP client calls one tool, and you get a line at the
top of your screen you can read without leaving what you're doing.

---

## Install

```bash
git clone https://github.com/avoguru/notch-mcp.git
cd notch-mcp
npm install
```

Then add it to your agent.

**Claude Code**

```bash
claude mcp add notch --scope user -- node "$(pwd)/bin/server.mjs"
```

**Cursor**, in `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "notch": {
      "command": "node",
      "args": ["/path/to/notch-mcp/bin/server.mjs"]
    }
  }
}
```

**Conductor** runs Claude Code underneath, so the Claude Code command covers it.
Use `--scope user` so every workspace gets it.

**Windsurf**, in `~/.codeium/windsurf/mcp_config.json`, same shape as Cursor.

**Zed**, in `context_servers` in `settings.json`, same shape as Cursor.

### Try it

Ask your agent:

> Show a build progressing in the notch, then mark it done.

---

## Styles

Four readouts for four kinds of job. Your agent calls `notch_styles` and picks
one on its own. Default is **pendant**.

### pendant, for the thing you're waiting on

![pendant](docs/img/pendant.png)

Hangs below the notch, sized to its text. The bottom edge fills as it
progresses. For builds, test runs, deploys.

### belt, for background work you can ignore

![belt](docs/img/belt.png)

A thin strip across the whole display. Label on the left, detail and percent on
the right (both ends shown above). The whole strip fills as it progresses. For
syncs, watchers, queues.

### pill, for a quick message

![pill](docs/img/pill.png)

A capsule floating below the notch. No progress bar. For "deployed", "pushed",
"done in 12s".

### glow, for when something is happening

![glow](docs/img/glow.png)

A line of light under the notch and nothing else. No text. The bright segment
travels as it progresses. For when you only need to know it's alive.

---

## Tools

| Tool | What it does |
|---|---|
| `notch_styles` | Lists the styles so the agent can choose |
| `notch_status` | Show or update, with `text`, `detail`, `progress`, `style` |
| `notch_done` | Green, then hides itself |
| `notch_error` | Red, stays a bit longer |
| `notch_clear` | Hide now |

A typical run:

```
notch_status  { text: "Running test suite", progress: 0,    style: "pendant" }
notch_status  { text: "Running test suite", progress: 0.68, detail: "342/500" }
notch_done    { text: "Tests passed",       detail: "500 in 41s" }
```

---

## Getting rid of it

Click it. On pendant, pill and glow you can click anywhere on the readout; the
belt has an × on the right because it spans the screen.

It also clears itself:

- when your agent finishes
- when you quit or force-quit your editor
- after 30 minutes if something was left running

It can't get stuck on screen, and there's nothing to clean up by hand.

---

## Supported

macOS · Node 18+ · zero runtime dependencies

Needs Xcode Command Line Tools for the display component
(`xcode-select --install`). `npm install` builds it.

Tested on MacBook Pro 16" (M4 Pro), macOS 15.6 Sequoia.

Works with the lid closed or on an external monitor. There's no notch to hang
from, so the readouts sit under the menu bar instead.

---

## Contributions welcome

Plenty left to do. A few I'd find useful:

- **Stack concurrent agents.** One readout shows at a time and the most recently
  updated session wins. Three agents visible in the belt at once would be better,
  and it's the thing this most needs.
- **More styles.** `docs/catalogue.html` has 33 treatments that were explored.
  Four shipped.
- **Windows and Linux.** The MCP server is portable. The renderer is AppKit.
- **A rules snippet** so agents call it consistently without being asked each time.

`bin/server.mjs` is about 300 lines with no dependencies, so it's readable end to
end if you want to see what an MCP server is underneath. Open an issue or a PR.

## Development

```bash
npm test             # 28 checks against the real server and display
npm run shots        # re-render docs/img at 3x (npm run shots 4 for 4x)
npm run build        # rebuild bin/notchd
```

## License

MIT