# todoglow-mcp

Lets Claude Code, Codex CLI, Cursor, and any MCP-compatible tool read your todos and report what they're working on, through [todoglow](https://devglow.app/todoglow).

todoglow is a keyboard-first todo app for macOS and Windows. It opens with one global shortcut, takes a line of text, and closes. This package is the MCP server that connects it to your coding tools.

**Requires the todoglow desktop app.** This server talks to it. [Download for macOS or Windows](https://devglow.app/todoglow).

## Threads and todos are separate

**Agent threads.** Run several agents at once and you lose track of which one is doing what. Agents call `update_thread` when a conversation starts and again as work progresses, so todoglow's AGENTS section shows what each one is on: working, done, or failed. This happens on its own, without you asking.

**Todos.** Your own list. Agents add to it only when you say so ("add this to my todos"). An agent narrating its progress belongs in a thread, so it never lands in your list.

## Install

**Claude Code**

```bash
claude mcp add -s user todoglow -- npx -y --prefer-offline todoglow-mcp@latest
```

**Codex CLI**

```bash
codex mcp add todoglow -- npx -y --prefer-offline todoglow-mcp@latest
```

**Cursor and other clients.** Add as a stdio MCP server in your client's settings (don't run it directly):

```
npx -y --prefer-offline todoglow-mcp@latest
```

**HTTP / SSE transport**

```bash
npx -y --prefer-offline todoglow-mcp@latest --transport http --port 26214
```

Keep the `@latest` tag. A bare `todoglow-mcp` spec makes npx cache a second copy and the handshake can time out.

Requires todoglow v1.1.0 or newer.

## Tools

| Tool | What it does |
|---|---|
| `update_thread` | Register and update an agent's work status in the AGENTS section |
| `get_threads` | Read current agent threads |
| `set_topic` | Add a todo, only on an explicit request from you |
| `list_todos` | List active todos, optionally filtered by status |
| `get_active_todo` | The todo currently in progress |
| `advance_todo` | Move a todo along: pending → in_progress → completed |
| `list_receipt_todos` | List a month's completed todos as the receipt shows them |
| `set_receipt_titles` | Give a todo a public title so the receipt shows it unmasked |

The receipt is a shareable monthly summary. With its privacy mode on, a todo appears in the clear only if you gave it a display title; the rest stay masked. The last two tools exist so an agent can help you pick which ones are safe to show.

## Data

Todos are stored locally as JSON files on your machine. Nothing is sent anywhere.

## Links

- [todoglow](https://devglow.app/todoglow) (product page and download)
- [FAQ](https://devglow.app/todoglow/faq)
- [Philosophy: todo ≠ task](https://devglow.app/todoglow/philosophy)
- [Changelog](https://devglow.app/todoglow/changelog)

## License

MIT