tandem-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{tandem_cli-0.2.0 → tandem_cli-0.3.0}/.claude/settings.local.json

@@ -7,7 +7,12 @@
       "Bash(curl -sL --max-time 30 -o bl_books_full.csv \"https://raw.githubusercontent.com/realpython/python-data-cleaning/master/Datasets/BL-Flickr-Images-Book.csv\")",
       "Bash(curl -sL --max-time 30 -o chipotle.tsv \"https://raw.githubusercontent.com/justmarkham/DAT8/master/data/chipotle.tsv\")",
       "Bash(git reset *)",
-      "Bash(/Users/bhavya/.claude/plugins/cache/claude-plugins-official/superpowers/6.2.0/skills/subagent-driven-development/scripts/task-brief *)"
+      "Bash(/Users/bhavya/.claude/plugins/cache/claude-plugins-official/superpowers/6.2.0/skills/subagent-driven-development/scripts/task-brief *)",
+      "WebFetch(domain:subreddittraffic.live)",
+      "Bash(grep -n *)",
+      "Read(//Users/bhavya/.tandem/**)",
+      "Read(//Users/bhavya/.config/**)",
+      "Bash(uv run *)"
     ]
   }
 }

{tandem_cli-0.2.0 → tandem_cli-0.3.0}/.gitignore

@@ -5,3 +5,6 @@ __pycache__/
 dist/
 build/
 .pytest_cache/
+
+# superpowers brainstorm mockups
+.superpowers/

tandem_cli-0.3.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: tandem-cli
+Version: 0.3.0
+Summary: Meta-harness that runs Claude Code and Codex CLI with live trace sync.
+Project-URL: Homepage, https://github.com/Bhavya6187/tandem
+Project-URL: Repository, https://github.com/Bhavya6187/tandem
+Project-URL: Issues, https://github.com/Bhavya6187/tandem/issues
+Author-email: Bhavya Agarwal <bhavya.6187@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,cli,codex,session-sync
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: pexpect>=4.9
+Requires-Dist: pydantic>=2.7
+Requires-Dist: watchdog>=4.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🤝 tandem
+
+**One coding session. Two AI agents. Zero lost context.**
+
+Run [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and
+[OpenAI Codex CLI](https://github.com/openai/codex) as a single paired
+session — each model in its own native harness. Work in either one,
+flip to the other with **Ctrl-]**, and pick up exactly where you left
+off. Only one model runs per turn; the other stays in sync through pure
+local file translation.
+
+[![CI](https://github.com/Bhavya6187/tandem/actions/workflows/ci.yml/badge.svg)](https://github.com/Bhavya6187/tandem/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tandem-cli)](https://pypi.org/project/tandem-cli/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/Bhavya6187/tandem/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/Bhavya6187/tandem/blob/main/LICENSE)
+
+```bash
+uv tool install tandem-cli
+```
+
+![tandem demo — one session moving between Claude Code and Codex](https://raw.githubusercontent.com/Bhavya6187/tandem/main/docs/demo.gif)
+
+</div>
+
+---
+
+## Quick start
+
+You'll need Python 3.11+ and the `claude` and `codex` CLIs on your PATH.
+
+```bash
+uv tool install tandem-cli   # or: pip install tandem-cli
+cd your-project
+tandem                       # fresh paired session; drops you into claude
+```
+
+Work normally — that's the real Claude Code TUI. When you want the other
+model, press **Ctrl-]**: tandem closes out the harness at the turn
+boundary and reopens the same conversation in Codex a couple of seconds
+later. Press it again to come back. The bottom row tracks who you're
+facing:
+
+```
+claude ● │ codex ○   ^] flips
+```
+
+Pressed mid-turn, the flip arms and fires the moment the model finishes
+(the bar says so; press again to cancel).
+
+Exit the harness the usual way and you're back at your shell, with the
+session saved and a hint for picking it up again:
+
+```
+to continue this session: tandem resume a1b2c3d4e5f6
+```
+
+Come back anytime:
+
+```bash
+tandem resume                # most recent session in this directory
+tandem resume a1b2c3d4e5f6   # a specific one (id from the exit hint)
+```
+
+## Why tandem?
+
+### 🖥️ One CLI, two harnesses, zero ceremony.
+
+`tandem` is the terminal you live in. It fronts the real Claude Code or
+Codex TUI — pixel-for-pixel native — and **Ctrl-]** flips to the other
+one in a couple of seconds, same conversation, same files, same history.
+A one-line tab bar on the bottom row shows which model you're facing;
+everything above it is the untouched native UI.
+
+### 🆕 0.2 — GPT subagents inside Claude Code
+
+Type "get the code reviewed by gpt" and tandem's plugin hands the task
+to a local codex worker; the verdict lands back in your Claude session,
+and your Claude quota stays on the main thread. Pin any model your
+codex account offers ("ask sol to review it") or set a cheap default
+once. Setup and routing:
+[GPT subagents guide](https://github.com/Bhavya6187/tandem/blob/main/docs/subagents.md).
+
+![gpt subagent demo — ask for a GPT review in Claude Code, tandem dispatches a codex worker, the verdict comes back, fixes get committed](https://raw.githubusercontent.com/Bhavya6187/tandem/main/docs/gpt-subagent.gif)
+
+### ⏳ Hit a usage limit? Just keep going.
+
+Claude runs out of its usage window mid-refactor? Press **Ctrl-]** and
+Codex continues the **same conversation** a second later — same files,
+same history, same plan. Two subscriptions become one long runway.
+
+### 🌩️ Immune to outages.
+
+An Anthropic or OpenAI outage doesn't stop your work: **Ctrl-]**, keep
+going in the other harness, and flip back whenever it clears.
+
+Five more reasons — subscriptions not API bills, two model families on
+one problem, native harnesses, instant switching, privacy:
+[Why tandem?](https://github.com/Bhavya6187/tandem/blob/main/docs/why.md)
+
+## How it works
+
+- Only one model runs per turn — the other side is never invoked to
+  "catch up".
+- As you work, tandem translates the growing transcript into the other
+  CLI's native session format — pure local file I/O, no model calls —
+  so the other side is always resume-ready.
+- Each CLI is the real thing running on a PTY: your keybindings, slash
+  commands, and MCP servers all work exactly as they do today — tandem
+  reserves exactly one key (Ctrl-]) and one terminal row (the tab bar).
+- A flip waits for the turn boundary, exits the fronted CLI gracefully,
+  lets the sync settle, and resumes the other side — no stop in
+  between.
+- Everything stays local: the CLIs' own session files plus a small
+  SQLite database in `~/.tandem`. No cloud sync, no telemetry.
+- Uninstall tandem tomorrow and both sessions still resume natively
+  with `claude --resume` and `codex resume`.
+
+Full mechanics — sync engine, crash safety, compatibility ranges:
+[How tandem works](https://github.com/Bhavya6187/tandem/blob/main/docs/how-it-works.md).
+
+## Command cheat sheet
+
+| Command | What it does |
+| --- | --- |
+| `tandem` | Start a fresh paired session (Claude active; `--active codex` to flip) |
+| `Ctrl-]` | Flip to the other harness from inside a running session (rebindable in `[frame]`) |
+| `tandem resume [id]` | Continue the most recent (or a specific) session |
+| `tandem run --on codex "…"` | One-off prompt to the *other* agent, with full context |
+| `tandem sub "…"` | Run one delegated task on a codex model (what GPT subagents use under the hood) |
+| `tandem status` | Show pairing, roles, and sync position |
+| `tandem plugin install` | Install the Claude Code plugin (also offered on first `tandem` launch) |
+
+Three maintenance commands round it out: `tandem doctor` (health
+check), `tandem sync` (manual catch-up translation), and `tandem
+sync-mcp` (share MCP server configs between the tools).
+
+## Docs
+
+- [GPT subagents](https://github.com/Bhavya6187/tandem/blob/main/docs/subagents.md) —
+  plugin install, worker model, routing modes, sandbox & trust boundary
+- [Why tandem?](https://github.com/Bhavya6187/tandem/blob/main/docs/why.md) —
+  the full pitch, all eight reasons
+- [Configuration](https://github.com/Bhavya6187/tandem/blob/main/docs/configuration.md) —
+  the optional `~/.tandem/config.toml`: subagent workers, per-harness
+  startup args, the flip key and tab bar
+- [How tandem works](https://github.com/Bhavya6187/tandem/blob/main/docs/how-it-works.md) —
+  sync engine, PTY passthrough, compatibility, where your data lives
+- [Developing tandem](https://github.com/Bhavya6187/tandem/blob/main/docs/development.md) —
+  dev setup and the converter adapter interface
+- [Observed session formats](https://github.com/Bhavya6187/tandem/blob/main/docs/formats.md) —
+  the claude/codex transcript details tandem is pinned against
+
+## License
+
+[MIT](https://github.com/Bhavya6187/tandem/blob/main/LICENSE)

tandem_cli-0.3.0/README.md

@@ -0,0 +1,157 @@
+<div align="center">
+
+# 🤝 tandem
+
+**One coding session. Two AI agents. Zero lost context.**
+
+Run [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and
+[OpenAI Codex CLI](https://github.com/openai/codex) as a single paired
+session — each model in its own native harness. Work in either one,
+flip to the other with **Ctrl-]**, and pick up exactly where you left
+off. Only one model runs per turn; the other stays in sync through pure
+local file translation.
+
+[![CI](https://github.com/Bhavya6187/tandem/actions/workflows/ci.yml/badge.svg)](https://github.com/Bhavya6187/tandem/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tandem-cli)](https://pypi.org/project/tandem-cli/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/Bhavya6187/tandem/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/Bhavya6187/tandem/blob/main/LICENSE)
+
+```bash
+uv tool install tandem-cli
+```
+
+![tandem demo — one session moving between Claude Code and Codex](https://raw.githubusercontent.com/Bhavya6187/tandem/main/docs/demo.gif)
+
+</div>
+
+---
+
+## Quick start
+
+You'll need Python 3.11+ and the `claude` and `codex` CLIs on your PATH.
+
+```bash
+uv tool install tandem-cli   # or: pip install tandem-cli
+cd your-project
+tandem                       # fresh paired session; drops you into claude
+```
+
+Work normally — that's the real Claude Code TUI. When you want the other
+model, press **Ctrl-]**: tandem closes out the harness at the turn
+boundary and reopens the same conversation in Codex a couple of seconds
+later. Press it again to come back. The bottom row tracks who you're
+facing:
+
+```
+claude ● │ codex ○   ^] flips
+```
+
+Pressed mid-turn, the flip arms and fires the moment the model finishes
+(the bar says so; press again to cancel).
+
+Exit the harness the usual way and you're back at your shell, with the
+session saved and a hint for picking it up again:
+
+```
+to continue this session: tandem resume a1b2c3d4e5f6
+```
+
+Come back anytime:
+
+```bash
+tandem resume                # most recent session in this directory
+tandem resume a1b2c3d4e5f6   # a specific one (id from the exit hint)
+```
+
+## Why tandem?
+
+### 🖥️ One CLI, two harnesses, zero ceremony.
+
+`tandem` is the terminal you live in. It fronts the real Claude Code or
+Codex TUI — pixel-for-pixel native — and **Ctrl-]** flips to the other
+one in a couple of seconds, same conversation, same files, same history.
+A one-line tab bar on the bottom row shows which model you're facing;
+everything above it is the untouched native UI.
+
+### 🆕 0.2 — GPT subagents inside Claude Code
+
+Type "get the code reviewed by gpt" and tandem's plugin hands the task
+to a local codex worker; the verdict lands back in your Claude session,
+and your Claude quota stays on the main thread. Pin any model your
+codex account offers ("ask sol to review it") or set a cheap default
+once. Setup and routing:
+[GPT subagents guide](https://github.com/Bhavya6187/tandem/blob/main/docs/subagents.md).
+
+![gpt subagent demo — ask for a GPT review in Claude Code, tandem dispatches a codex worker, the verdict comes back, fixes get committed](https://raw.githubusercontent.com/Bhavya6187/tandem/main/docs/gpt-subagent.gif)
+
+### ⏳ Hit a usage limit? Just keep going.
+
+Claude runs out of its usage window mid-refactor? Press **Ctrl-]** and
+Codex continues the **same conversation** a second later — same files,
+same history, same plan. Two subscriptions become one long runway.
+
+### 🌩️ Immune to outages.
+
+An Anthropic or OpenAI outage doesn't stop your work: **Ctrl-]**, keep
+going in the other harness, and flip back whenever it clears.
+
+Five more reasons — subscriptions not API bills, two model families on
+one problem, native harnesses, instant switching, privacy:
+[Why tandem?](https://github.com/Bhavya6187/tandem/blob/main/docs/why.md)
+
+## How it works
+
+- Only one model runs per turn — the other side is never invoked to
+  "catch up".
+- As you work, tandem translates the growing transcript into the other
+  CLI's native session format — pure local file I/O, no model calls —
+  so the other side is always resume-ready.
+- Each CLI is the real thing running on a PTY: your keybindings, slash
+  commands, and MCP servers all work exactly as they do today — tandem
+  reserves exactly one key (Ctrl-]) and one terminal row (the tab bar).
+- A flip waits for the turn boundary, exits the fronted CLI gracefully,
+  lets the sync settle, and resumes the other side — no stop in
+  between.
+- Everything stays local: the CLIs' own session files plus a small
+  SQLite database in `~/.tandem`. No cloud sync, no telemetry.
+- Uninstall tandem tomorrow and both sessions still resume natively
+  with `claude --resume` and `codex resume`.
+
+Full mechanics — sync engine, crash safety, compatibility ranges:
+[How tandem works](https://github.com/Bhavya6187/tandem/blob/main/docs/how-it-works.md).
+
+## Command cheat sheet
+
+| Command | What it does |
+| --- | --- |
+| `tandem` | Start a fresh paired session (Claude active; `--active codex` to flip) |
+| `Ctrl-]` | Flip to the other harness from inside a running session (rebindable in `[frame]`) |
+| `tandem resume [id]` | Continue the most recent (or a specific) session |
+| `tandem run --on codex "…"` | One-off prompt to the *other* agent, with full context |
+| `tandem sub "…"` | Run one delegated task on a codex model (what GPT subagents use under the hood) |
+| `tandem status` | Show pairing, roles, and sync position |
+| `tandem plugin install` | Install the Claude Code plugin (also offered on first `tandem` launch) |
+
+Three maintenance commands round it out: `tandem doctor` (health
+check), `tandem sync` (manual catch-up translation), and `tandem
+sync-mcp` (share MCP server configs between the tools).
+
+## Docs
+
+- [GPT subagents](https://github.com/Bhavya6187/tandem/blob/main/docs/subagents.md) —
+  plugin install, worker model, routing modes, sandbox & trust boundary
+- [Why tandem?](https://github.com/Bhavya6187/tandem/blob/main/docs/why.md) —
+  the full pitch, all eight reasons
+- [Configuration](https://github.com/Bhavya6187/tandem/blob/main/docs/configuration.md) —
+  the optional `~/.tandem/config.toml`: subagent workers, per-harness
+  startup args, the flip key and tab bar
+- [How tandem works](https://github.com/Bhavya6187/tandem/blob/main/docs/how-it-works.md) —
+  sync engine, PTY passthrough, compatibility, where your data lives
+- [Developing tandem](https://github.com/Bhavya6187/tandem/blob/main/docs/development.md) —
+  dev setup and the converter adapter interface
+- [Observed session formats](https://github.com/Bhavya6187/tandem/blob/main/docs/formats.md) —
+  the claude/codex transcript details tandem is pinned against
+
+## License
+
+[MIT](https://github.com/Bhavya6187/tandem/blob/main/LICENSE)

tandem_cli-0.3.0/docs/configuration.md

@@ -0,0 +1,77 @@
+# Configuration
+
+tandem reads one optional file: `~/.tandem/config.toml`. No file is
+required; every key has a working default. (Back to the
+[README](../README.md).)
+
+## [subagents] — GPT subagent workers
+
+Worker model, routing mode, and context handling for GPT subagent
+dispatches. Key semantics and the full routing story live in the
+[GPT subagents guide](subagents.md):
+
+```toml
+[subagents]
+model = "gpt-5.6-luna"  # worker default; unset = your codex account's default
+route = "manual"        # manual | all | off
+context = "match"       # match | task | full
+keep_forks = false      # keep each worker's rollout for debugging
+```
+
+## [claude] / [codex] — per-harness startup args
+
+Optional per-harness tables add flags to every interactive session tandem
+opens (`tandem`, `tandem resume`) — one-off relays (`tandem run`),
+subagent dispatch, and doctor probes are unaffected:
+
+```toml
+[claude]
+args = ["--dangerously-skip-permissions"]
+
+[codex]
+args = ["--dangerously-bypass-approvals-and-sandbox"]
+```
+
+The flags shown disable the harnesses' own permission prompts for
+sessions tandem launches — set them only if that is what you want.
+The list is passed to the harness raw: a flag that expects a value can
+swallow the settings tandem appends after it and break turn tracking.
+Malformed values (a non-list, empty or non-string elements) are
+silently ignored rather than failing the launch.
+
+## [frame] — the flip key, the tab bar, and warm flips
+
+The frame is tandem's own surface inside a running session: one reserved
+keybind that flips to the other harness, the one-line tab bar on the
+bottom terminal row, and the pipelined boot behind the flip.
+
+```toml
+[frame]
+flip_key = "ctrl-]"
+bar = true
+warm = true   # boot the incoming harness while the outgoing one shuts down
+```
+
+| key | default | meaning |
+| --- | --- | --- |
+| `flip_key` | `"ctrl-]"` | The flip keybind, consumed by tandem (never forwarded). Accepts `ctrl-<char>` or a hex byte like `"0x1d"`; printable keys are rejected (they would swallow typing). The bar relabels itself to match (`ctrl-t` shows `^T flips`). |
+| `bar` | `true` | The one-line tab bar on the bottom terminal row. `false` hides it; the flip still works. |
+| `warm` | `true` | Overlap the two halves of a flip: the incoming harness starts booting the moment the flip fires (a mid-turn press waits for the turn boundary first), while the outgoing one is still shutting down. `false` gives fully serial flips — the boot only begins once the old harness is gone. |
+
+An unparseable value falls back to the default rather than failing the
+launch. If a terminal can't sustain the bar, tandem drops it for the rest
+of that session — the flip is unaffected — and `tandem doctor` warns
+about it until you delete the marker file it names; set `bar = false` if
+you'd rather keep the bar off for good. Shrinking the window below the
+bar's row floor also drops it for the session, but that is tandem's own
+policy rather than a conflict, so nothing is recorded and `doctor` stays
+quiet.
+
+Warming is pipelining, not a background service: the moment the flip
+fires — a mid-turn `Ctrl-]` waits for the turn boundary first — the
+incoming harness starts and the outgoing one is torn down at the same
+time, so the flip lands at about the incoming harness's own start-up
+speed instead of that plus the shutdown. Nothing exists before you press
+the key and nothing survives the flip — between flips a tandem session is
+exactly one harness process. `warm = false` restores the fully serial
+flip, which is slower but does the same thing.

tandem_cli-0.3.0/docs/development.md

@@ -0,0 +1,29 @@
+# Developing tandem
+
+Dev setup and the extension surface. (Back to the
+[README](../README.md).)
+
+## Extending tandem
+
+The sync engine talks to a small adapter interface
+(`tandem.converter.TraceConverter`):
+
+```python
+class TraceConverter(Protocol):
+    def translate_entry(entry, direction, ctx) -> list[TargetEntry] | TranslationError
+```
+
+`ReferenceConverter` implements it via a normalized event model
+(`tandem/events.py`) derived from the observed formats. Pass your own
+converter to `SyncEngine(store, session, source, converter=...)`.
+
+## Development
+
+```bash
+uv sync && uv run pytest
+pipx install .        # or: uv tool install .
+```
+
+Dependencies are deliberately small: `click` (CLI), `pydantic` v2 (event
+schema), `watchdog` (transcript tailing), `pexpect`/ptyprocess (PTY
+passthrough); state is stdlib `sqlite3`.

tandem_cli-0.3.0/docs/how-it-works.md

@@ -0,0 +1,106 @@
+# How tandem works
+
+The mechanics behind the pairing: sync engine, PTY passthrough,
+compatibility ranges, and where your data lives. (Back to the
+[README](../README.md).)
+
+- **One model per command — always.** Only the active harness's model is
+  ever invoked (or, for `run --on`, the target's). The shadow side is pure
+  local file I/O: tandem tails the active transcript, translates each
+  entry, and appends it to the shadow's session file. The shadow's model
+  is never called to "catch up".
+- **Exit means exit.** Leaving the harness — as opposed to flipping out
+  of it — prints the resume hint and returns you to your OS shell; the
+  paired session is saved and `tandem resume` re-enters it.
+  `status` / `sync` / `doctor` / `run --on` / `sync-mcp` run one-shot
+  from your shell, targeting the directory's most recently used session.
+- **The frame: flip without leaving.** Ctrl-] (configurable, consumed at
+  the PTY layer, ignored inside bracketed paste) flips the screen to the
+  other harness: pressed mid-turn it arms and fires at the turn boundary
+  (press again to cancel — the bar shows the armed state), then
+  tandem exits the fronted CLI gracefully (quit keystrokes, then SIGTERM,
+  then a bounded SIGKILL), lets the incremental sync settle, flips roles,
+  and resumes the other side — with no stop in between.
+  With claude fronted, the boundary comes from claude's own session
+  registry (`~/.claude/sessions/<pid>.json`, the data `claude agents
+  --json` prints): `busy` holds the flip, anything else fires it — so an
+  idle prompt flips instantly even though claude keeps appending
+  housekeeping to its transcript between turns.
+  (The registry appeared in claude 2.1.226; on older claudes the probe
+  finds nothing and every armed flip fires at once, mid-turn included —
+  the deliberate single-tier trade: no silent valve, breakage is loud.)
+  With codex fronted the
+  transcript-marker rules stand: where no marker could be wired (codex
+  with a `notify` handler of your own, which tandem won't clobber) ~2s of
+  transcript quiescence stands in; where one was wired, a 120s valve
+  covers a marker that never arrives — far above any plausible tool-call
+  silence, because firing early kills a live turn while firing late only
+  costs a wait (and Ctrl-] cancels). The
+  bottom terminal row is tandem's one drawn pixel: the child is told the
+  terminal is a row shorter, a scroll region keeps output above the bar,
+  and a targeted watcher reasserts it after child screen resets. If a
+  terminal can't sustain the bar it drops for the session (the flip keeps
+  working) and `tandem doctor` says so until you delete the marker file it
+  names; shrinking the window below the bar's row floor drops it just as
+  permanently, but silently — that one isn't a conflict to fix.
+- **PTY passthrough.** tandem launches the real CLI on a pty (raw mode,
+  resize forwarding, signals through the line discipline) and never
+  scrapes terminal output — the transcript files are the source of truth.
+  Turn-complete hooks (`claude --settings` Stop hook, `codex -c
+  notify=[…]`) are wired per-invocation as wake-up signals, with
+  fs-watching as the data path and fallback. If your codex config already
+  sets `notify`, tandem leaves it alone.
+- **Append-only, crash-safe sync.** Each transcript entry is translated as
+  it lands — no bulk re-export at switch time. Appends are whole-line +
+  fsync, and a write-ahead intent in the sync cursor makes translation
+  exactly-once across crashes; on restart, sync resumes from the last
+  confirmed entry.
+- **Tool calls translate natively.** The harnesses speak different tool
+  vocabularies, so each completed call+result pair is re-expressed in the
+  shadow's own terms — `Bash` ↔ `exec_command`, `Edit`/`Write` ↔
+  `apply_patch`, `TodoWrite` ↔ `update_plan` — and lands as a real
+  tool-call record, so shadow history reads as the shadow's own work.
+  Anything that wouldn't map truthfully passes through verbatim; a call
+  whose result never arrived is closed with a `(tool result not recorded)`
+  placeholder at handoff, since both replay APIs reject dangling calls.
+- **Attribution stays legible.** Every synced *text* message is tagged
+  `[via claude-code]` / `[via codex]` (tandem's own notes use `[tandem]`),
+  so interleaved histories make sense to you and to the models. Tool
+  activity is untagged — it's mirrored as native records, not prose.
+- **Errors are contained.** An entry that fails translation becomes a
+  single per-turn placeholder in the shadow, with the raw entry
+  quarantined under `~/.tandem/quarantine/…` — and sync continues. The
+  shadow is never corrupted or truncated.
+- **Memory files stay in step.** Fresh launches and every switch sync
+  CLAUDE.md ↔ AGENTS.md: shared content lives in a
+  `<!-- tandem:shared:begin/end -->` block (newer file wins),
+  tool-specific text outside the block is preserved, and a file without
+  markers is read from but never rewritten. Git state is never touched.
+
+## Compatibility
+
+Session formats are internal to the CLIs and drift between releases.
+tandem pins what it was built against (observed formats documented in
+[docs/formats.md](https://github.com/Bhavya6187/tandem/blob/main/docs/formats.md)):
+
+| CLI | Tested | Accepted range |
+| --- | --- | --- |
+| Claude Code | 2.1.220 | ≥ 2.0, < 3 |
+| Codex CLI | 0.145.0 | ≥ 0.140, < 0.150 |
+
+Outside the range, tandem warns and asks you to run `tandem doctor`.
+Format knowledge is isolated per tool in
+`src/tandem/harness/claude_code.py` and `src/tandem/harness/codex.py`.
+
+## Where your data lives
+
+- `~/.tandem/state.db` — SQLite: session pairing + per-source sync cursors
+  (override the directory with `TANDEM_HOME`)
+- `~/.tandem/quarantine/<session>/` — raw entries that failed translation
+- `~/.claude/projects/<munged-cwd>/<session-id>.jsonl` — claude transcript
+- `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<session-id>.jsonl` — codex
+  rollout (`CLAUDE_CONFIG_DIR` / `CODEX_HOME` honored)
+
+Claude session ids are minted by tandem (`claude --session-id`); codex
+mints its own on first run and tandem captures it from the new rollout
+file.