{"id":"07bdd64f-026c-44a7-8838-135efed80af7","slug":"chatbraid","kind":"mcp","name":"ChatBraid","summary":"Braid your AI threads into one: a cross-thread /compact for Claude Code, Codex, ChatGPT and claude.ai","owner":"oaishi","repoUrl":"https://github.com/oaishi/ChatBraid","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-18T23:14:05.000Z","addedAt":"2026-10-21T09:54:59.709Z","logoUrl":"https://avatars.githubusercontent.com/u/22328326?u=00d0908e87a0e6b390c6a2674860a1ffa49c0cd4&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","memory-knowledge"],"tags":["chatgpt","claude-code","claude-code-plugin","codex","context","llm"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T01:57:21.876Z","sample":false,"url":"https://conduits.dev/tools/chatbraid","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p align=\"center\">\n  <img src=\"assets/logo-readme.png\" alt=\"ChatBraid logo\" width=\"300\">\n</p>\n\n<h1 align=\"center\">ChatBraid</h1>\n\n<p align=\"center\"><b>Braid your AI threads into one.</b> It's <code>/compact</code>, but across threads.<br>\nClaude Code · Codex · ChatGPT · claude.ai</p>\n\n---\n\nYou've got one Claude Code tab fixing the API, a Codex session that built the frontend, and a ChatGPT chat where you settled the database schema. None of them knows what the others did. ChatBraid lets you pick any of those threads, from any of those tools, and fold them into **one dense, faithful context**. You can then:\n- continue in the thread you're in,\n- start a fresh session from it, or\n- save it and load it somewhere else.\n\n```text\n/braid                          ← pick from a list of your recent threads\n/braid last-codex               ← pull your latest Codex session into this Claude Code thread\n/braid 4afd43c2 019e1d45 focus: auth token refresh\n\"braid my chats about the results section\"      ← on claude.ai / ChatGPT, via the web skill\n```\n\nThe merged context always has the same six sections:\n1. **Unified goal**\n2. **Per-thread state**\n3. **Decisions & facts** (tagged with their source thread)\n4. **Conflicts between threads**\n5. **Code & artifacts** (exact paths, commands, errors)\n6. **Next steps**\n\n---\n\n## Contents\n\n1. [Which pieces do I need?](#1-which-pieces-do-i-need)\n2. [Install](#2-install)\n   - [2.1 Core (required for terminal & apps)](#21-core-cli--required-for-every-terminal--app-integration)\n   - [2.2 Claude Code (CLI, VS Code / JetBrains, desktop)](#22-claude-code-cli-vs-code--jetbrains-desktop)\n   - [2.3 Codex (CLI, Codex / ChatGPT desktop app, IDE extension)](#23-codex-cli-codex--chatgpt-desktop-app-ide-extension)\n   - [2.4 claude.ai web skill](#24-claudeai-web-ui--skill)\n   - [2.5 ChatGPT web skill](#25-chatgpt-web-ui--skill)\n   - [2.6 Browser extension (ChatGPT + claude.ai)](#26-browser-extension-chatgpt--claudeai)\n   - [2.7 Claude Desktop chat app & other MCP hosts](#27-claude-desktop-chat-app--other-mcp-hosts)\n3. [Use cases: step-by-step recipes](#3-use-cases--step-by-step-recipes)\n4. [Picking threads: ids, refs and the pickers](#4-picking-threads-ids-refs-and-the-pickers)\n5. [Reference: commands, MCP tools, file mode](#5-reference)\n6. [Configuration](#6-configuration)\n7. [How it works](#7-how-it-works)\n8. [Privacy](#8-privacy)\n9. [Troubleshooting](#9-troubleshooting)\n10. [Limitations](#10-limitations)\n11. [Development](#11-development)\n\n---\n\n## 1. Which pieces do I need?\n\nChatBraid comes in three forms. They share one engine and produce identical merges.\n\n| Piece | What it is | Runs in |\n|---|---|---|\n| **Plugin / MCP server** (`chatbraid`) | Python, no dependencies. Reads your local Claude Code and Codex history and any imported web chats. | Claude Code, Codex, Claude Desktop, any MCP app, your terminal |\n| **Web skill** (`dist/chatbraid-web-skill.zip`) | A `SKILL.md` plus the same engine, run inside the chat's code sandbox | claude.ai, ChatGPT |\n| **Browser extension** (`extension/`) | Reads your ChatGPT / claude.ai history from your logged-in tabs | Chrome, Edge, Brave, Arc |\n\n**Install by where you work:**\n\n| You work in… | Install | You get |\n|---|---|---|\n| Claude Code (terminal) | [2.1](#21-core-cli--required-for-every-terminal--app-integration) + [2.2](#22-claude-code-cli-vs-code--jetbrains-desktop) | `/braid`, `/threads`, auto-skill, thread id in each tab |\n| Claude Code in VS Code / JetBrains / desktop | [2.1](#21-core-cli--required-for-every-terminal--app-integration) + [2.2](#22-claude-code-cli-vs-code--jetbrains-desktop) | same, because the plugin is shared through `~/.claude` |\n| Codex CLI | [2.1](#21-core-cli--required-for-every-terminal--app-integration) + [2.3](#23-codex-cli-codex--chatgpt-desktop-app-ide-extension) | MCP tools, `$merge-threads` skill, `/prompts:braid` |\n| Codex in the Codex / ChatGPT desktop app or the IDE extension | [2.1](#21-core-cli--required-for-every-terminal--app-integration) + [2.3](#23-codex-cli-codex--chatgpt-desktop-app-ide-extension) | same, because they share `~/.codex/config.toml` |\n| claude.ai (web, desktop, mobile) | [2.4](#24-claudeai-web-ui--skill) and/or [2.6](#26-browser-extension-chatgpt--claudeai) | skill: merge past chats or uploaded files · extension: one-click merges, full transcripts |\n| chatgpt.com | [2.5](#25-chatgpt-web-ui--skill) and/or [2.6](#26-browser-extension-chatgpt--claudeai) | skill: merge uploaded exports/bundles · extension: one-click merges |\n| Claude Desktop (chat), Cursor, other MCP apps | [2.1](#21-core-cli--required-for-every-terminal--app-integration) + [2.7](#27-claude-desktop-chat-app--other-mcp-hosts) | MCP tools over your local threads |\n| Just a terminal | [2.1](#21-core-cli--required-for-every-terminal--app-integration) | `chatbraid pick`, `merge`, `--copy`, `--launch` |\n\n**Which threads each surface can reach:**\n\n| Surface ↓ / threads → | Claude Code | Codex | ChatGPT | claude.ai |\n|---|:-:|:-:|:-:|:-:|\n| Claude Code, Codex, Claude Desktop, terminal | ✅ direct | ✅ direct | ✅ after export¹ | ✅ after export¹ |\n| claude.ai + web skill | ✅ upload bundle² | ✅ upload bundle² | ✅ upload export | ✅ past-chat search or upload export |\n| ChatGPT + web skill | ✅ upload bundle² | ✅ upload bundle² | ✅ upload export | ✅ upload export |\n| Browser extension | via paste³ | via paste³ | ✅ direct | ✅ direct |\n\n¹ The extension's **Send to terminal** button, or `chatbraid import <data-export.zip>`.\n² `chatbraid export <refs> -o threads.chatbraid.json`, then upload that file.\n³ `chatbraid merge … --copy`, then paste into the chat.\n\n---\n\n## 2. Install\n\n### 2.1 Core CLI: required for every terminal / app integration\n\nRequirements: **Python 3.9+** (no packages needed) and macOS, Linux or WSL.\n\n```bash\ngit clone https://github.com/oaishi/ChatBraid && cd ChatBraid\n./install.sh            # Codex + Claude Code + ~/.local/bin/chatbraid   (or: ./install.sh codex | ./install.sh claude)\n```\n\nCheck that it sees your history:\n```bash\nchatbraid list -n 10        # if \"command not found\": add ~/.local/bin to PATH, or use  python3 bin/chatbraid\n```\nYou should see a numbered list of your recent Claude Code (`[claude]`) and Codex (`[codex]`) threads.\n\nOptional: install [`fzf`](https://github.com/junegunn/fzf) (`brew install fzf`) for a multi-select picker with live previews.\n\n### 2.2 Claude Code (CLI, VS Code / JetBrains, desktop)\n\nInstall the plugin from GitHub inside any Claude Code session:\n```text\n/plugin marketplace add oaishi/ChatBraid\n/plugin install chatbraid@chatbraid\n```\nThen **restart Claude Code**. That gives you:\n- **MCP server** `chatbraid`, with the tools `list_threads`, `merge_threads`, `save_merge`, `load_merge`, `read_thread`, `tag_thread`.\n- **`/braid [refs] [focus: …]`**: merge threads into this one. With no arguments it lists threads and asks you to pick.\n- **`/threads [source] [words]`**: just list threads.\n- **`merge-threads` skill**: Claude uses it on its own when you say things like \"pull in my Codex session\".\n- **SessionStart hook**: tells each session its own thread id, so it never merges itself and can tell you the id. It also labels the terminal tab `🧵 <id>` where the terminal allows.\n\nPlugins live in `~/.claude`, so the same install works in the **VS Code / JetBrains extensions** and the **desktop app**.\n\nOptional: show each tab's thread id in the status line. Add this to `~/.claude/settings.json`:\n```json\n\"statusLine\": { \"type\": \"command\", \"command\": \"python3 /path/to/ChatBraid/bin/chatbraid statusline\" }\n```\n\nVerify: in a new session, ask *\"what's this thread's chatbraid id?\"*. It should answer from the session-start note. Then try `/threads`.\n\n### 2.3 Codex (CLI, Codex / ChatGPT desktop app, IDE extension)\n\n```bash\n./install.sh codex          # or: chatbraid install --codex\n```\nThis:\n1. appends this to `~/.codex/config.toml`, without touching your other servers:\n   ```toml\n   [mcp_servers.chatbraid]\n   command = \"/absolute/path/to/python3\"\n   args = [\"/path/to/ChatBraid/bin/chatbraid\", \"mcp\"]\n   ```\n2. copies the skill to `~/.codex/skills/merge-threads/SKILL.md`;\n3. copies the prompt to `~/.codex/prompts/braid.md`.\n\nThen **fully restart** Codex. For the desktop app, quit with ⌘Q; closing the window isn't enough. The CLI, desktop app and IDE extension all read the same `~/.codex`.\n\nVerify:\n```bash\ncodex mcp list              # should list chatbraid\n```\nIn a Codex thread, type `$merge-threads` or just ask: *\"use chatbraid to list my recent threads\"*. Newer Codex versions favor skills over custom prompts, so `/prompts:braid` may not appear. Natural language and `$merge-threads` always work.\n\n> Codex **cloud** tasks (chatgpt.com/codex) run in a remote container and can't see your local history. For those, use the web skill or `--copy`.\n\n### 2.4 claude.ai web UI: skill\n\nThe same skill works in the claude.ai **website, desktop app and mobile app**.\n\n1. Get the zip: download [`dist/chatbraid-web-skill.zip`](dist/chatbraid-web-skill.zip) from this repo, or build it with `scripts/build-web-skill.sh`.\n2. In claude.ai, open **Settings → Capabilities** and turn on:\n   - **Code execution and file creation**, which skills need, and\n   - **Search and reference chats**, which lets the skill find your past chats. This is a paid-plan feature.\n3. **Settings → Capabilities → Skills → Upload skill** → choose `chatbraid-web-skill.zip`. Menu names may differ slightly between versions.\n4. Verify: in a new chat, say *\"braid my recent chats\"*. Claude should list recent chats and ask which to merge.\n\n### 2.5 ChatGPT web UI: skill\n\nThe same zip works in ChatGPT, which supports the same `SKILL.md` format.\n\n1. Get `dist/chatbraid-web-skill.zip` (as in 2.4).\n2. In ChatGPT, open the **Skills** page (under Plugins / Skills) → **Create** → **Upload from your computer** → choose the zip. Skills availability depends on your plan and workspace settings, so check OpenAI's help center if you don't see it.\n3. Verify: upload a ChatGPT data export (see [UC5](#uc5--chatgpt-threads-only)) and say *\"braid these\"*. ChatGPT should run the engine and list the conversations inside.\n\n> ChatGPT has no tool for fetching a specific past chat on demand. Its built-in memory works implicitly. So in ChatGPT the skill works on **uploaded files**: data exports, `.chatbraid.json` bundles, or Claude Code / Codex transcripts. For one-click merges of your live ChatGPT history, use the extension (2.6).\n\n### 2.6 Browser extension (ChatGPT + claude.ai)\n\n1. Open `chrome://extensions` (Edge: `edge://extensions`).\n2. Turn on **Developer mode**.\n3. Click **Load unpacked** → select the `extension/` folder of this repo.\n4. Pin **🧵 ChatBraid** from the puzzle-piece menu.\n5. Open and sign in to **chatgpt.com** and/or **claude.ai**. Reload any tabs that were already open.\n6. Verify: click the icon. You should see `ChatGPT: N conversations` / `Claude: N conversations` and a checklist.\n\nThe popup gives you four buttons:\n- **Merge → new chat**: opens a new chat with the merge prompt in the message box, ready for you to review and send.\n- **Merge → this chat**: inserts the merge prompt into the chat in the current tab.\n- **Copy**: puts the merge prompt on your clipboard.\n- **Send to terminal**: saves the selected chats to `~/Downloads/chatbraid/`, where Claude Code, Codex and the CLI see them automatically.\n\n### 2.7 Claude Desktop chat app & other MCP hosts\n\nAny app that runs local stdio MCP servers can use ChatBraid. For example, **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"chatbraid\": { \"command\": \"python3\", \"args\": [\"/path/to/ChatBraid/bin/chatbraid\", \"mcp\"] }\n  }\n}\n```\nRestart the app, then ask *\"use chatbraid to merge my last Claude Code and Codex threads\"*. Cursor, Windsurf and others take the same `command` + `args`.\n\n---\n\n## 3. Use cases: step-by-step recipes\n\nEach recipe lists the options for that case. **★** marks the recommended one.\n\n### Terminal & apps\n\n#### UC1: Codex threads only\n*\"I have two Codex sessions and want one to know what the other did.\"*\n\n- **★ Inside Codex** (CLI, desktop app or IDE):\n  1. Open the Codex thread you want to continue.\n  2. Type `$merge-threads`, or ask *\"use chatbraid to list my Codex threads\"*.\n  3. Reply with numbers (e.g. `2`), or name a ref like `last-codex` or an id prefix.\n  4. Codex writes the merged context and saves it with `save_merge`, then you carry on.\n- **From a terminal, into a fresh Codex session:**\n  ```bash\n  chatbraid pick -s codex --launch codex       # pick several → new Codex session seeded with the merge\n  chatbraid merge 019e1d45 019e22a7 --launch codex\n  ```\n- **Find a Codex thread's id:** run `/status` in Codex, or `chatbraid list -s codex`.\n\n#### UC2: Claude Code threads only\n*\"Two Claude Code tabs worked on related things.\"*\n\n- **★ Inside Claude Code:**\n  1. In the tab you want to continue, run `/braid`.\n  2. Tick threads in the multi-select, or run `/braid <id> [<id> …]` directly.\n  3. Claude writes the merged context and continues.\n- **Find another tab's id:** with the hook, every session knows its id (ask *\"what's this thread's id?\"*). With the status line, it's displayed in each tab as `🧵 4afd43c2`. `/threads` shows which terminal each live session runs in.\n- **Fresh session:** `chatbraid pick -s claude --launch claude`.\n- **Tip:** name a thread once (`chatbraid tag 4afd43c2 api-auth`) and use `/braid api-auth` from then on.\n\n#### UC3: Claude Code + Codex, mixed\n*\"Claude Code did the backend, Codex did the frontend.\"*\n\n- **★ In Claude Code:** `/braid last-codex`, or `/braid 019e1d45 focus: the API contract`.\n- **★ In Codex:** *\"use chatbraid to merge `last-claude` into this thread\"*.\n- **Terminal:** `chatbraid pick --here` lists both tools' threads for the current directory; pick, then `--launch claude` or `--launch codex`.\n- **Hand the result over:** after a merge in tool A, tool B can run `load_merge` (*\"load the latest chatbraid merge\"*). Or run `chatbraid last` in a terminal to print it.\n\n#### UC4: Start a brand-new session from several threads\n```bash\nchatbraid pick --launch claude                     # or --launch codex\nchatbraid merge last-claude last-codex -f \"release checklist\" --launch claude\n```\nThe new session's first message is the merge prompt. The agent replies with the merged context and waits for your next instruction.\n\n### Web UIs\n\n#### UC5: ChatGPT threads only\n*\"Several ChatGPT chats about one project.\"*\n\n- **★ Extension, one click:**\n  1. On chatgpt.com, open the ChatBraid popup.\n  2. Tick the chats and add a focus if you like.\n  3. Click **Merge → new chat** (or **→ this chat**).\n  4. Review the inserted prompt and press Enter.\n- **Web skill, no extension:**\n  1. Export your data: ChatGPT → **Settings → Data controls → Export data**. You'll get an email with a zip.\n  2. In a ChatGPT chat with the skill installed, upload the zip (or the `conversations.json` inside it).\n  3. Say *\"braid my chats about <topic>\"*. The skill runs `braid.py files …`, lists matching conversations, and you reply with numbers.\n  4. It writes the merged context.\n- **Manual:** copy the chats' text into one message and say *\"braid these\"*. The skill treats pasted text as threads.\n\n#### UC6: claude.ai threads only\n- **★ Web skill with past-chat search** (no files needed):\n  1. Enable **Search and reference chats** ([2.4](#24-claudeai-web-ui--skill)).\n  2. In a new chat say *\"braid my recent chats about <topic>\"*, or paste `claude.ai/chat/…` links.\n  3. Pick numbers from the list, and Claude writes the merged context.\n\n  This uses retrieval, so very long chats come through as excerpts. Claude flags anything thin.\n- **Extension, full transcripts:** on claude.ai, open the popup → tick chats → **Merge → new chat**.\n- **Web skill + export, full transcripts, no extension:**\n  1. claude.ai → **Settings → Privacy → Export data**.\n  2. Upload the zip to a chat and say *\"braid these\"*.\n\n#### UC7: ChatGPT + claude.ai, mixed\n- **★ Extension:**\n  1. Keep one chatgpt.com tab and one claude.ai tab open, both signed in.\n  2. The popup lists conversations from **both** sites in one checklist. Tick across them.\n  3. **Merge → new chat** on whichever site you're in.\n- **Web skill:** upload the ChatGPT export to a claude.ai chat, or the claude.ai export to a ChatGPT chat, and say *\"braid these\"*.\n- **On claude.ai, combine both sources:** pull in claude.ai chats with past-chat search **plus** an uploaded ChatGPT export, in one request: *\"braid my claude chats about X with the ChatGPT chats in this export\"*.\n\n### Across terminal ↔ web\n\n#### UC8: Web chats → Claude Code / Codex\n*\"I designed it in ChatGPT/claude.ai; now I want the coding agent to know.\"*\n\n- **★ Extension:**\n  1. Tick the chats in the popup → **Send to terminal**. They're saved to `~/Downloads/chatbraid/`.\n  2. In Claude Code run `/braid last-web` (or pick them from `/braid`, where they show up as `[gpt]` / `[claude.ai]`). In Codex, ask it to merge `last-web`.\n- **Data export instead:**\n  ```bash\n  chatbraid import ~/Downloads/chatgpt-export.zip ~/Downloads/claude-export.zip\n  chatbraid list -s web -q \"schema\"         # find them\n  ```\n  Then use `/braid <id>`, or a chat URL: `/braid https://chatgpt.com/c/6720…`.\n\n#### UC9: Claude Code / Codex threads → ChatGPT / claude.ai\n*\"I want to discuss what my coding agents did in a regular chat.\"*\n\n- **★ Clipboard:**\n  ```bash\n  chatbraid pick --copy                              # or: chatbraid merge last-claude last-codex --copy\n  ```\n  Paste into a new ChatGPT or claude.ai chat and send.\n- **Upload a bundle to the web skill.** Better when you want to pick inside the chat, or mix with web chats:\n  ```bash\n  chatbraid export last-claude last-codex 019e1d45 -o threads.chatbraid.json\n  ```\n  Upload `threads.chatbraid.json` and say *\"braid these\"*.\n- **Raw transcripts work too.** You can upload `~/.claude/projects/<project>/<id>.jsonl` or `~/.codex/sessions/…/rollout-….jsonl` straight to the web skill.\n\n#### UC10: Everything mixed: Claude Code + Codex + ChatGPT + claude.ai\n- **★ From Claude Code or Codex:**\n  1. Bring the web chats local (UC8: **Send to terminal** or `chatbraid import`).\n  2. Run `/braid` and tick threads from all four sources. They're listed together, newest first.\n- **From claude.ai or ChatGPT:**\n  1. Run `chatbraid export <local refs> -o local.chatbraid.json`.\n  2. Upload it **plus** the web exports to a chat with the skill, and say *\"braid these\"*. On claude.ai you can add past chats via search in the same request.\n- **Terminal only:** `chatbraid import <exports>`, then `chatbraid pick --launch claude`.\n\n#### UC11: Reuse one merge in several places\nEvery merge is saved to `~/.chatbraid/merges/` (`latest.md` is always the newest):\n- Claude Code / Codex / MCP apps: *\"load the latest chatbraid merge\"* (`load_merge`), or `/prompts:braid last` in Codex.\n- Terminal: `chatbraid last`, `chatbraid merges`, `chatbraid last | pbcopy`.\n- Web: the skill offers `merged-context.md` as a download after each merge. Paste or upload it anywhere.\n\n---\n\n## 4. Picking threads: ids, refs and the pickers\n\nA **ref** can be any of these, anywhere ChatBraid asks for threads:\n\n| Ref | Example |\n|---|---|\n| Full id | `4afd43c2-b638-4108-9be9-25c1d8fcc1a2` |\n| Id prefix (≥ 4 chars) | `4afd43c2` |\n| Tag | `api-auth` (after `chatbraid tag 4afd api-auth`) |\n| Chat URL | `https://chatgpt.com/c/6720…`, `https://claude.ai/chat/0b1e…` |\n| Source-qualified | `codex:019e1d45`, `claude-code:4afd`, `chatgpt:6720…` |\n| Most recent | `last`, `last-claude`, `last-codex`, `last-web` |\n| File path | `~/.codex/sessions/2026/10/12/rollout-….jsonl` |\n\n**Finding the id of a thread:**\n\n| Where | How |\n|---|---|\n| Claude Code | Ask *\"what's this thread's id?\"* (the hook told it), check the `🧵` status line, or run `/threads` |\n| Codex | `/status` |\n| ChatGPT | the URL: `chatgpt.com/c/<id>` |\n| claude.ai | the URL: `claude.ai/chat/<id>` |\n| Anywhere | `chatbraid list [-s source] [-q words] [--here]` |\n\n**The pickers:**\n- **Claude Code `/braid`**: a multi-select question. Type extra ids under \"Other\".\n- **Codex**: a numbered table. Answer `1 3` or `2-4`.\n- **Terminal `chatbraid pick`**: fzf multi-select (TAB to tick, ENTER to merge) with a live preview, or a numbered prompt without fzf.\n- **Extension**: a searchable checklist across both sites.\n- **Web skill**: a numbered list from your past chats or uploaded files. Reply with numbers.\n\n---\n\n## 5. Reference\n\n### Slash commands & skills\n\n| Where | Command | Does |\n|---|---|---|\n| Claude Code | `/braid [refs…] [focus: …]` | Merge into this thread (no args → pick) |\n| Claude Code | `/threads [source] [words]` | List threads + this thread's id |\n| Claude Code / Codex | skill `merge-threads` (`$merge-threads` in Codex) | Triggered by \"merge my other thread\", etc. |\n| Codex | `/prompts:braid [refs…] \\| last` | Merge, or adopt the latest saved merge |\n| claude.ai / ChatGPT | skill `chatbraid` | \"braid my chats about X\", \"braid these\" (uploads) |\n\n### CLI\n\n```text\nchatbraid list   [-s SRC] [-q WORDS] [--here] [-n N] [--json]     list threads\nchatbraid pick   [filters] [merge options] [--no-fzf]              interactive multi-select → merge\nchatbraid merge  REF... [merge options]                            merge specific threads\nchatbraid show   REF [--max-chars N] [--detail low|normal|high]    one thread, compacted\nchatbraid files  FILE... [--select 1,3|all|words] [-q] [-s] [merge options]\n                                                                   list / merge straight from files (exports, bundles, .jsonl)\nchatbraid export REF... [-o threads.chatbraid.json]                bundle local threads for upload to the web skill\nchatbraid import FILE...                                           import ChatGPT / claude.ai data exports or bundles\nchatbraid tag    REF NAME                                          friendly alias\nchatbraid last | merges                                            latest / all saved merges\nchatbraid install [--codex] [--claude] [--link]                    wire into Codex / Claude Code\nchatbraid mcp                                                      run the MCP server (stdio)\n\nmerge options:  -f/--focus TEXT   --llm   --max-chars N (default 100000)   --detail low|normal|high\n                -c/--copy   -l/--launch claude|codex   -o/--output FILE\nSRC:            all | claude | codex | web | chatgpt | claude.ai | local\n```\n\nWithout `--copy`, `--launch` or `-o`, the merge prompt goes to stdout, so it pipes: `chatbraid merge last-codex | pbcopy`.\n\n### MCP tools\n\n| Tool | Arguments | Purpose |\n|---|---|---|\n| `list_threads` | `source, query, cwd, limit, exclude` | Browse threads, newest first |\n| `merge_threads` | `refs, focus, mode (handoff\\|llm), max_chars, detail` | Build the merge. `handoff`: the agent writes it. `llm`: an API model writes it and it's saved. |\n| `save_merge` | `content, title, refs` | Persist a merged context |\n| `load_merge` | `name` (`latest` / `list` / part of a name) | Reuse a merged context |\n| `read_thread` | `ref, max_chars, detail` | Inspect one thread in detail |\n| `tag_thread` | `ref, name` | Create an alias |\n\n### Detail levels\n\n| `--detail` | Includes |\n|---|---|\n| `low` | user + assistant text |\n| `normal` (default) | plus one-line tool calls (commands, files edited) |\n| `high` | plus tool output |\n\nErrors from tools are always included.\n\n---\n\n## 6. Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `CHATBRAID_HOME` | `~/.chatbraid` | Saved merges, tags, imported web chats, index cache |\n| `CLAUDE_CONFIG_DIR` | `~/.claude` | Where Claude Code transcripts live |\n| `CODEX_HOME` | `~/.codex` | Where Codex sessions live |\n| `CHATBRAID_WEB_DIRS` | `~/Downloads/chatbraid` | `:`-separated extra folders scanned for web chats (replaces the default) |\n| `CHATBRAID_PROVIDER` | auto | `anthropic` or `openai` for `--llm` / `mode=llm` |\n| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | none | Only needed for `--llm` |\n| `CHATBRAID_ANTHROPIC_MODEL` / `CHATBRAID_OPENAI_MODEL` | `claude-sonnet-5-5` / `gpt-5` | Models for `--llm` |\n| `CHATBRAID_TAB_TITLE=0` | on | Don't retitle the terminal tab at session start |\n\n---\n\n## 7. How it works\n\n```\n Claude Code  ~/.claude/projects/*/<id>.jsonl ─┐\n Codex        ~/.codex/sessions/**/rollout-*  ─┤               ┌─ MCP server ─→ Claude Code · Codex · Claude Desktop · Cursor…\n ChatGPT  ┐  extension / data export / bundle ├─ adapters ─→ digest ─┼─ CLI ────────→ pick · merge · --copy · --launch\n claude.ai┘                                   ┘  (one model)   │      └─ web skill ──→ same engine in claude.ai / ChatGPT sandbox\n                                                               └─ extension: JS port of digest (kept byte-identical by tests)\n```\n\n1. **Collect.** Per-tool adapters turn each transcript format into one thread model. They drop the noise:\n   - thinking blocks, injected system and environment text, sidechains;\n   - abandoned edit/retry branches on the web;\n   - Codex's encrypted reasoning.\n2. **Compact.** Each thread is fitted into a character budget:\n   - always kept: the original ask, the latest `/compact` summary, and the latest user and assistant turns;\n   - filled newest-first from what's left;\n   - long messages keep their head and tail;\n   - tool calls become one-liners, and files modified and recent commands go in a header.\n\n   The budget is split across threads by water-filling, so a short thread doesn't waste its share.\n3. **Merge.** The digests are wrapped in the six-section merge prompt.\n   - **handoff** (default): the agent you're talking to writes the merged context. No API key, and it's that agent's own understanding.\n   - **llm**: an Anthropic or OpenAI model writes it ahead of time, with map-reduce for very large inputs.\n4. **Persist.** `save_merge` writes `~/.chatbraid/merges/<time>-<title>.md` and `latest.md`.\n\n---\n\n## 8. Privacy\n\n- **Local by default.** The plugin, CLI and MCP server only read files on your machine. Nothing leaves it unless you use `--llm`, which sends the digest to the provider you configured.\n- **Extension.** It talks to chatgpt.com / claude.ai only from inside your own logged-in tabs. No tokens or data go anywhere else. Downloads go to your Downloads folder.\n- **Web skill.** It runs inside your chat's sandbox, on files you uploaded to that chat.\n- **Think before merging.** Transcripts can contain secrets you pasted, such as API keys or `.env` contents. Merged contexts include verbatim snippets, so review before sharing a merge.\n\n---\n\n## 9. Troubleshooting\n\n| Symptom | Fix |\n|---|---|\n| `chatbraid: command not found` | Add `~/.local/bin` to `PATH`, or use `python3 /path/to/ChatBraid/bin/chatbraid` |\n| `chatbraid list` is empty | Check that `~/.claude/projects` / `~/.codex/sessions` exist. If you use custom locations, set `CLAUDE_CONFIG_DIR` / `CODEX_HOME`. |\n| Claude Code: no `/braid` | Run `/plugin` to check that it's installed and enabled, then restart Claude Code |\n| Codex doesn't see the tools | Quit Codex completely (⌘Q for the app) and reopen. Check `tail ~/.codex/config.toml` and `codex mcp list`. |\n| MCP server fails to start | Run the configured command by hand: `python3 …/bin/chatbraid mcp`, then type `{}` + Enter. It should print a JSON error, not a traceback. |\n| A thread merges itself | Claude Code passes its own id automatically. In Codex, give the id from `/status` and ask it to exclude it. |\n| `ref is ambiguous` | Use more characters of the id, or `source:id` |\n| Chat URL doesn't resolve | Web chats must be exported first (extension **Send to terminal** or `chatbraid import`) |\n| Extension: \"API 401/403/404\" | Sign in again / reload the tab. If it persists, the site changed its internal API: open an issue with the message. |\n| Extension: text didn't appear in the box | It's on your clipboard: click the box and press ⌘V / Ctrl+V |\n| claude.ai skill can't list chats | Enable **Search and reference chats** (paid plans), or upload an export instead |\n| ChatGPT: no Skills page | Depends on plan / workspace. Use the extension or `--copy` instead. |\n| Merge is too long / too short | `--max-chars 40000` / `150000`, or `--detail low` / `high` |\n\n---\n\n## 10. Limitations\n\n- **Merging is lossy by design.** It's a compact. If a detail matters, the agent can `read_thread` the original.\n- **The extension relies on internal endpoints.** It uses the same internal endpoints the ChatGPT and claude.ai web apps use. They aren't public APIs and can change without notice. Data exports + `chatbraid import` / the web skill always work as a fallback.\n- **claude.ai past-chat search is retrieval-based.** For long chats, upload an export or use the extension when you need everything.\n- **ChatGPT web can't fetch past chats on demand.** Its skill works on uploaded files.\n- **Codex cloud tasks** can't see local history.\n- **Codex's encrypted compaction summaries** are skipped. The plaintext messages and tool calls around them are kept.\n\n---\n\n## 11. Development\n\n```bash\npython3 -m unittest discover tests -v   # all 4 parsers, file mode, export round-trip, MCP protocol, hook, budget, Python↔JS parity\nscripts/build-web-skill.sh              # rebuild dist/chatbraid-web-skill.zip after changing chatbraid/ or skills-web/\n```\n\n```\nchatbraid/            core engine (stdlib only): sources/, digest, index, files (file mode), mcp_server, cli, llm\nbin/chatbraid         entry point (CLI + `mcp`)\n.claude-plugin/ .mcp.json commands/ hooks/ skills/    Claude Code plugin (+ Codex skill)\ncodex/prompts/        Codex custom prompt\nskills-web/chatbraid/ web skill source (SKILL.md + scripts/braid.py)\ndist/                 built web skill zip\nextension/            browser extension (MV3)\ntests/                unit + integration tests\n```\n\nMIT licensed.\n"}