# mcp-clipstream

**Clean clipboard capture for Claude Code.** An MCP server that pushes
copyable text into a persistent, scrollable TUI buffer — *before* the
terminal renderer mangles it with ANSI codes, box-drawing characters,
indentation padding, or hard line breaks.

> Status: **v0.3.1 (alpha)** — `clip`, `clip_table`, `clip_code`, `clip_cmd` tools; syntax-highlighted previews; per-kind row colours; live search (`f`), session filter (`s`), expand view (`e`); at-copy-time format picker for tables. macOS-tested. See the [roadmap](#roadmap) for what's next.

## Why

Copying text from Claude Code's terminal output is broken in ways that
have been documented for nearly a year (issues
[#4686](https://github.com/anthropics/claude-code/issues/4686),
[#5097](https://github.com/anthropics/claude-code/issues/5097),
[#15199](https://github.com/anthropics/claude-code/issues/15199),
[#18170](https://github.com/anthropics/claude-code/issues/18170),
[#26016](https://github.com/anthropics/claude-code/issues/26016),
[#35446](https://github.com/anthropics/claude-code/issues/35446)):
extra spaces in code blocks, vertical bars from TUI renderer, hard line
breaks at 80 characters, leading indentation baked in as real
characters. Existing workarounds clean up *after* the damage. This
captures the text *before* the terminal ever touches it.

## How it works

```
 Claude Code ──tool call──▶ MCP server ──UDS──▶ clipstream TUI ──pbcopy──▶ clipboard
                            (mcp-clipstream)    (clipstream)
```

1. `mcp-clipstream` is a small MCP server spawned by Claude Code.
2. It exposes four tools: `clip` (catch-all text), `clip_code` (code blocks
   with a language hint), `clip_cmd` (shell commands with a shell hint),
   and `clip_table` (structured tables). Claude Code picks the right one
   for whatever it's producing.
3. The tool writes the clean text as a JSON message to a Unix domain
   socket at `/tmp/clipstream.sock`.
4. `clipstream` is a Textual TUI you run in a dedicated terminal tab.
   It listens on the socket, buffers every clip from every Claude Code
   session, and lets you scroll, select, and copy.

No ANSI codes. No hard wraps. No "please pipe through pbcopy" prompts.

## Install

```bash
uv tool install mcp-clipstream
# or: pipx install mcp-clipstream
```

This gives you two entry points:

- `clipstream` — the TUI (you run this).
- `mcp-clipstream` — the MCP server (Claude Code runs this).

Upgrade later with `uv tool upgrade mcp-clipstream`.

## Setup

**1. Register the MCP server with Claude Code.** One command:

```bash
claude mcp add clipstream --scope user $(which mcp-clipstream)
```

Verify with `claude mcp list`.

**2. Auto-approve the clipstream tools** so Claude Code stops prompting on
every call. Merge this into `~/.claude/settings.json`:

```json
{
  "permissions": {
    "allow": ["mcp__clipstream__clip", "mcp__clipstream__clip_table"]
  }
}
```

Restart any running Claude Code sessions after either step.

**3. Tell Claude Code when to use it.** Add to `~/.claude/CLAUDE.md` (applies to every project) or a project-level `CLAUDE.md`:

```markdown
## Clipstream clipboard

Push copyable output through the clipstream MCP server so the user gets clean text without terminal-renderer artifacts. Pick the right tool by content kind:

- **Shell commands** → `clip_cmd(command, shell="bash", label="…")`. One per command (or one for a multi-line script).
- **Code blocks** → `clip_code(code, language, filename=None, label="…")`. Always pass `language` (e.g. `"python"`, `"typescript"`, `"sql"`). Pass `filename` when the user is creating or editing a specific file.
- **Tables** → `clip_table(headers, rows, label="…")`. Lists of column names and lists of cell strings. The user picks Markdown / TSV / HTML rich at copy time.
- **Everything else** (configs, URIs, tokens, file paths, structured prose) → `clip(content, label="…", lang="…" if applicable)`.

Always include a short `label` so entries are scannable in the TUI.

Do not clip:
- Conversational text or explanations.
- Single-word answers, yes/no, very short inline values.
- Content the user just asked about but isn't grabbing.
```

**4. Run the TUI in a spare terminal tab:**

```bash
clipstream
```

## Using it

- `↑` / `↓` — navigate clips
- `Enter` — copy selected clip to system clipboard
- `f` — find (live multi-token search across content, label, filename, kind, language, shell, session)
- `s` — cycle session filter (all → first session → second session → …)
- `e` — expand selected clip in a full-screen view (line numbers + syntax highlighting; `Enter` copies, `Esc` closes)
- `d` — delete selected clip
- `c` — clear all
- `q` — quit
- `Esc` — clear search / dismiss expand view

The status bar shows `sessions: N | clips: visible/total | filter: … | find: …` so you always know what's filtered.

New clips appear at the top with their source session label and a short preview. Each row is colour-coded by kind:

- **green** header — `clip_code` (Python, TypeScript, SQL, etc. — preview is syntax-highlighted)
- **yellow** header — `clip_cmd` (shell command, preview highlighted)
- **cyan** header — `clip_table` (preview shows markdown form)
- neutral — plain `clip`

**Tables:** when you press Enter on a `clip_table` row, a format picker appears:

- `m` — Markdown (GitHub, docs, chat)
- `t` — TSV (paste into Excel / Google Sheets / Numbers — each cell lands in its own column)
- `h` — HTML rich (paste into Gmail / Notion / Word / Apple Mail — renders as a real table, not raw markup)
- `Esc` — cancel

## Configuration

Environment variables (TOML config file lands in v0.3.0):

| Variable | Default | Purpose |
|---|---|---|
| `CLIPSTREAM_SOCKET` | `/tmp/clipstream.sock` | Unix domain socket path |
| `CLIPSTREAM_SPOOL` | `~/.clipstream/spool.jsonl` | Local fallback when TUI is down |
| `CLIPSTREAM_SESSION` | CWD basename | Override session label |

CLI flags on `clipstream`:

```
clipstream --socket /tmp/clipstream.sock --max-clips 500
```

## Roadmap

- **v0.1.0** — MVP: `clip` tool, UDS transport, list view, pbcopy, macOS only.
- **v0.2.x** — `clip_table` with at-copy-time format picker (Markdown / TSV / HTML rich for Gmail/Notion/Word).
- **v0.3.0** — `clip_code` and `clip_cmd` tools, syntax-highlighted previews (monokai), per-kind row colours.
- **v0.3.1** (current) — Live search (`f`), session filter (`s`), expand view (`e` for full-screen detail with line numbers).
- **v0.3.2** — `~/.clipstream/config.toml`, themes (default + minimal), `--persist` flag for JSONL history.
- **v0.3.3** — Linux clipboard validation (xclip / wl-copy), docs polish.
- **v0.4.0** — pinning, chaining, auto-copy mode, Claude Code post-response hook.

## Development

```bash
git clone https://github.com/shamis6ali/mcp-clipstream
cd mcp-clipstream
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run mypy src
```

## License

MIT © Orchestrator AI Systems Ltd.