# chatback

**Find unfinished and on-hold Cursor agent chats — then pick them up again.**

Local-only MCP server for the [Cursor](https://cursor.com) community. Indexes your agent transcripts under `~/.cursor/projects`, scores **open loops** (aborted, errored, interrupted, open todos, hold language), and exposes tools so the agent can show you a Chatback inbox.

No cloud. No upload. MIT licensed.

## Why this exists

Generic chat search helps you *find* old threads. **chatback** helps you *finish* them — ranked by what looks unfinished or explicitly on hold.

## Install (30 seconds)

### Cursor Marketplace / plugin

Once listed, install **Chatback** from Marketplace. Until then, add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "chatback": {
      "command": "npx",
      "args": ["-y", "github:princemuichkine/chatback"]
    }
  }
}
```

Restart Cursor (or **Developer: Reload Window**).

### Local development

```bash
git clone https://github.com/princemuichkine/chatback.git
cd chatback
npm install && npm run build
```

Point MCP at your build:

```json
{
  "mcpServers": {
    "chatback": {
      "command": "node",
      "args": ["/absolute/path/to/chatback/dist/index.js"]
    }
  }
}
```

Or symlink as a Cursor plugin:

```bash
ln -s "$(pwd)" ~/.cursor/plugins/local/chatback
```

## MCP tools

| Tool | Purpose |
|------|---------|
| `list_open_loops` | Ranked inbox of unfinished / on-hold chats |
| `search_chats` | Keyword search across indexed transcripts |
| `get_chat` | Full transcript body by chat id |
| `recent_chats` | Recently updated chats |
| `mark_loop` | Mark `hold`, `done`, or `ignore` (local only) |
| `reindex` | Rescan transcript folders |

**Resource:** `chatback://inbox` — markdown summary of top open loops.

## CLI (debug without MCP)

```bash
npx -y github:princemuichkine/chatback --help
npx -y github:princemuichkine/chatback --print-inbox 10
```

## Open-loop signals

- **Last agent paragraph** — cleaned user-facing closing (monologue and `[REDACTED]` stripped); inbox shows up to ~480 chars
- **Agent invitation closings** on that paragraph (`want me to`, `if you want`, `say the word`, `when you're ready`, …) — not generic “follow-up migration” notes
- `turn_ended` with `aborted` or `error`
- Last message is from the user (interrupted mid-turn)
- Open `TodoWrite` items with non-empty content
- Strong hold phrases in user text (`on hold`, `come back later`, `close this chat`, …)
- Your local `hold` mark via `mark_loop`

Recent chats rank higher; threads older than ~30 days are gently demoted.

Marks are stored in `~/.cursor/chatback/marks.json`. The search index lives at `~/.cursor/chatback/index.db` (schema v3; atomic writes; per-file index errors are collected, not thrown).

## Privacy

Reads only Cursor agent transcript files on your machine. Never sends data off-device.

## Publish checklist

- [cursor.directory](https://cursor.directory) — community listing
- [Cursor Marketplace](https://cursor.com/marketplace/publish) — submit open-source repo

## License

MIT — see [LICENSE](LICENSE).