tandem-cli 0.1.0__tar.gz

tandem_cli-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/

tandem_cli-0.1.0/.superpowers/sdd/.gitignore

@@ -0,0 +1 @@
+*

tandem_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bhavya Agarwal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tandem_cli-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: tandem-cli
+Version: 0.1.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
+
+# tandem
+
+A meta-harness that runs **Claude Code** and **OpenAI Codex CLI** as one
+paired session. Work in either agent and switch between them at any time
+without losing context: while one harness is **active**, the other is a
+**shadow** whose native session file is kept continuously up to date by
+translating the active harness's transcript entries into the shadow's own
+format. Switching is instant — the shadow was always resume-ready via that
+tool's native `--resume`/`resume` mechanism.
+
+```
+$ tandem                  # fresh paired claude+codex session; enters claude
+$ tandem --active codex   # fresh session with codex active instead
+tandem (claude)> switch   # after exiting claude: continue instantly in codex
+tandem (codex)> exit
+to continue this session: tandem resume a1b2c3d4e5f6
+$ tandem resume           # continue the most recent session here
+$ tandem resume <id>      # continue a specific session (id from the exit hint,
+                          #   run from that session's own directory)
+$ tandem run --on codex "second opinion: why is this test flaky?"
+$ tandem status           # pairing, roles, sync position
+$ tandem switch           # one-shot flip; does not enter a harness
+$ tandem doctor [--live]  # verify both sessions are resumable
+$ tandem sync             # manual catch-up translation (local file I/O only)
+$ tandem sync-mcp         # opt-in: copy MCP server configs between the tools
+```
+
+## Install
+
+```
+uv tool install tandem-cli   # or: pip install tandem-cli
+```
+
+Requires Python 3.11+ and the `claude` and `codex` CLIs on your PATH.
+
+## How it works
+
+- **Per-command single-model invariant.** Only one model is ever invoked per
+  user command — the active harness's (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 to the shadow's session
+  file. The shadow's model is never called to "catch up".
+- **A persistent prompt, not the OS shell.** Leaving the harness lands you
+  at `tandem (claude)>` instead of back in your shell. There, `switch`
+  flips roles and drops you straight into the other tool (no re-launch
+  needed), Enter or `resume` re-enters the current one, and
+  `status`/`sync`/`doctor`/`run --on …`/`sync-mcp` run the same
+  implementations as their one-shot forms, always against this session.
+  `exit` (or Ctrl-D) returns to your shell and prints
+  `to continue this session: tandem resume <id>` — pass that id to
+  `tandem resume <id>` from the session's own directory. Every one-shot
+  command also works from the OS shell, targeting the directory's most
+  recently used session; one-shot `tandem switch` only flips, it does not
+  enter a harness.
+- **PTY passthrough.** `tandem` launches the real CLI on a pty (raw mode,
+  SIGWINCH resize forwarding, signals through the line discipline). Tandem
+  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 (watchdog, polling fallback) as the data path and fallback.
+  If the user's codex config already sets `notify`, tandem leaves it alone.
+- **Append-only sync.** Each new 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 are translated natively.** The harnesses have different tool
+  vocabularies (Read/Edit/Bash vs exec_command/apply_patch), so each
+  completed call+result pair is re-expressed in the shadow's own vocabulary
+  — `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 would not map truthfully
+  (and every unrecognized tool) passes through verbatim with its name and
+  arguments intact. A call whose result never arrived is closed with a
+  `(tool result not recorded)` placeholder when the source is handed off,
+  since both replay APIs reject a dangling call.
+- **Attribution.** Every synced *text* message is tagged `[via claude-code]`
+  / `[via codex]` (tandem's own notes use `[tandem]`), so interleaved
+  histories stay legible to both the user and the models. Tool activity is
+  untagged — it is mirrored as native records, not prose.
+- **Error localization.** An entry that fails translation becomes a
+  placeholder in the shadow —
+  `[tandem: turn N could not be translated from <tool> — <reason>; raw
+  entry quarantined at ~/.tandem/quarantine/...]` — at most one per turn,
+  and sync continues. The shadow is never corrupted or truncated.
+- **Memory files.** A fresh `tandem` launch 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](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`
+(`--live` performs a real one-word resume per harness — two small model
+calls). Format knowledge is isolated per tool in
+`src/tandem/harness/claude_code.py` and `src/tandem/harness/codex.py`.
+
+## Where things live
+
+- `~/.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.
+
+## Swapping in a different converter
+
+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=...)`.
+
+## Install & development
+
+Requires Python 3.11+ and both CLIs on PATH. No network calls of tandem's
+own; all model calls happen inside the wrapped CLIs under your existing
+auth.
+
+```bash
+pipx install .        # or: uv tool install .
+uv sync && uv run pytest   # development
+```
+
+Dependencies (deliberately small): `click` (CLI), `pydantic` v2 (event
+schema), `watchdog` (transcript tailing), `pexpect`/ptyprocess (PTY
+passthrough); state is stdlib `sqlite3`.
+
+## v1 non-goals
+
+One active harness at a time (no concurrent dual-active). No other agents
+yet (the adapter interface is generic). No cloud sync or telemetry.
+Compaction state is not translated — on switch, the newly active tool's own
+compaction handles an over-long context.

tandem_cli-0.1.0/README.md

@@ -0,0 +1,153 @@
+# tandem
+
+A meta-harness that runs **Claude Code** and **OpenAI Codex CLI** as one
+paired session. Work in either agent and switch between them at any time
+without losing context: while one harness is **active**, the other is a
+**shadow** whose native session file is kept continuously up to date by
+translating the active harness's transcript entries into the shadow's own
+format. Switching is instant — the shadow was always resume-ready via that
+tool's native `--resume`/`resume` mechanism.
+
+```
+$ tandem                  # fresh paired claude+codex session; enters claude
+$ tandem --active codex   # fresh session with codex active instead
+tandem (claude)> switch   # after exiting claude: continue instantly in codex
+tandem (codex)> exit
+to continue this session: tandem resume a1b2c3d4e5f6
+$ tandem resume           # continue the most recent session here
+$ tandem resume <id>      # continue a specific session (id from the exit hint,
+                          #   run from that session's own directory)
+$ tandem run --on codex "second opinion: why is this test flaky?"
+$ tandem status           # pairing, roles, sync position
+$ tandem switch           # one-shot flip; does not enter a harness
+$ tandem doctor [--live]  # verify both sessions are resumable
+$ tandem sync             # manual catch-up translation (local file I/O only)
+$ tandem sync-mcp         # opt-in: copy MCP server configs between the tools
+```
+
+## Install
+
+```
+uv tool install tandem-cli   # or: pip install tandem-cli
+```
+
+Requires Python 3.11+ and the `claude` and `codex` CLIs on your PATH.
+
+## How it works
+
+- **Per-command single-model invariant.** Only one model is ever invoked per
+  user command — the active harness's (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 to the shadow's session
+  file. The shadow's model is never called to "catch up".
+- **A persistent prompt, not the OS shell.** Leaving the harness lands you
+  at `tandem (claude)>` instead of back in your shell. There, `switch`
+  flips roles and drops you straight into the other tool (no re-launch
+  needed), Enter or `resume` re-enters the current one, and
+  `status`/`sync`/`doctor`/`run --on …`/`sync-mcp` run the same
+  implementations as their one-shot forms, always against this session.
+  `exit` (or Ctrl-D) returns to your shell and prints
+  `to continue this session: tandem resume <id>` — pass that id to
+  `tandem resume <id>` from the session's own directory. Every one-shot
+  command also works from the OS shell, targeting the directory's most
+  recently used session; one-shot `tandem switch` only flips, it does not
+  enter a harness.
+- **PTY passthrough.** `tandem` launches the real CLI on a pty (raw mode,
+  SIGWINCH resize forwarding, signals through the line discipline). Tandem
+  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 (watchdog, polling fallback) as the data path and fallback.
+  If the user's codex config already sets `notify`, tandem leaves it alone.
+- **Append-only sync.** Each new 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 are translated natively.** The harnesses have different tool
+  vocabularies (Read/Edit/Bash vs exec_command/apply_patch), so each
+  completed call+result pair is re-expressed in the shadow's own vocabulary
+  — `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 would not map truthfully
+  (and every unrecognized tool) passes through verbatim with its name and
+  arguments intact. A call whose result never arrived is closed with a
+  `(tool result not recorded)` placeholder when the source is handed off,
+  since both replay APIs reject a dangling call.
+- **Attribution.** Every synced *text* message is tagged `[via claude-code]`
+  / `[via codex]` (tandem's own notes use `[tandem]`), so interleaved
+  histories stay legible to both the user and the models. Tool activity is
+  untagged — it is mirrored as native records, not prose.
+- **Error localization.** An entry that fails translation becomes a
+  placeholder in the shadow —
+  `[tandem: turn N could not be translated from <tool> — <reason>; raw
+  entry quarantined at ~/.tandem/quarantine/...]` — at most one per turn,
+  and sync continues. The shadow is never corrupted or truncated.
+- **Memory files.** A fresh `tandem` launch 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](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`
+(`--live` performs a real one-word resume per harness — two small model
+calls). Format knowledge is isolated per tool in
+`src/tandem/harness/claude_code.py` and `src/tandem/harness/codex.py`.
+
+## Where things live
+
+- `~/.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.
+
+## Swapping in a different converter
+
+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=...)`.
+
+## Install & development
+
+Requires Python 3.11+ and both CLIs on PATH. No network calls of tandem's
+own; all model calls happen inside the wrapped CLIs under your existing
+auth.
+
+```bash
+pipx install .        # or: uv tool install .
+uv sync && uv run pytest   # development
+```
+
+Dependencies (deliberately small): `click` (CLI), `pydantic` v2 (event
+schema), `watchdog` (transcript tailing), `pexpect`/ptyprocess (PTY
+passthrough); state is stdlib `sqlite3`.
+
+## v1 non-goals
+
+One active harness at a time (no concurrent dual-active). No other agents
+yet (the adapter interface is generic). No cloud sync or telemetry.
+Compaction state is not translated — on switch, the newly active tool's own
+compaction handles an over-long context.

tandem_cli-0.1.0/docs/formats.md

@@ -0,0 +1,102 @@
+# Observed session formats
+
+Everything tandem knows about the two native session formats was observed on
+this machine by creating throwaway sessions and reading the files the CLIs
+wrote. Versions observed:
+
+| CLI | version | session storage |
+| --- | --- | --- |
+| Claude Code (`claude`) | 2.1.220 | `~/.claude/projects/<munged-cwd>/<sessionId>.jsonl` |
+| Codex CLI (`codex`) | 0.145.0 | `~/.codex/sessions/YYYY/MM/DD/rollout-<YYYY-MM-DDThh-mm-ss>-<uuidv7>.jsonl` |
+
+Env overrides honored: `CLAUDE_CONFIG_DIR` (claude home), `CODEX_HOME` (codex
+home), `TANDEM_HOME` (tandem state).
+
+## Claude Code transcript (claude 2.1.220)
+
+- One JSONL file per session, named `<sessionId>.jsonl` (sessionId is a
+  UUIDv4). Project directory name = cwd with every character outside
+  `[A-Za-z0-9]` replaced by `-` (observed: `/private/tmp/claude-501/x` →
+  `-private-tmp-claude-501-x`).
+- Conversation entries carry `uuid` + `parentUuid` forming a chain, plus
+  `sessionId`, `cwd`, `version`, `gitBranch`, `timestamp` (ISO-8601 ms UTC
+  `Z`), `isSidechain`, `userType`, `entrypoint`.
+- Entry `type`s observed:
+  - `user` — `message: {role: "user", content: <string | block list>}`.
+    A plain string content = a real user prompt. A block list with
+    `tool_result` blocks = a tool result; the sibling field `toolUseResult`
+    holds the structured result (e.g. `{type: "create", filePath, content,
+    structuredPatch}` for Write, `{stdout, stderr, interrupted}` for Bash),
+    and `sourceToolAssistantUUID` points at the entry with the `tool_use`.
+  - `assistant` — `message` is an API message; **one content block per JSONL
+    line**, consecutive lines share `message.id`. Block types: `thinking`
+    (signature-bound), `text`, `tool_use` (`id`, `name`, `input`).
+    `stop_reason` on each line (`tool_use` / `end_turn`).
+  - `attachment` — hook output, skill/agent listings, deferred tool deltas.
+    Not conversation content.
+  - `queue-operation` (enqueue/dequeue of the prompt), `last-prompt`
+    (`leafUuid` pointer), `summary`, `system` — bookkeeping.
+  - `permission-mode`, `ai-title`, `pr-link`, `relocated`, `worktree-state`,
+    `file-history-snapshot` + `file-history-delta` — uuid-less session
+    metadata (permission mode, AI-generated title, linked PR, worktree
+    moves, file-backup tracking). Not conversation content; claude resumes
+    transcripts containing them without complaint.
+- Resume: `claude --resume <sessionId>` (from the same cwd). A new session
+  can be pinned to a chosen id with `claude --session-id <uuid>`.
+- Turn boundary: a `user` entry with string content starts a turn; an
+  `assistant` line with `stop_reason: "end_turn"` ends it. The `Stop` hook
+  (injectable per-invocation via `--settings '<json>'`) fires at turn end.
+
+## Codex rollout (codex-cli 0.145.0)
+
+- One JSONL file per session under a date-sharded dir; the session id
+  (UUIDv7) is embedded in the filename. `~/.codex/session_index.jsonl` maps
+  `{id, thread_name, updated_at}`. `~/.codex/history.jsonl` is a global
+  prompt history.
+- Every line is `{timestamp, type, payload}`.
+- `type` values observed:
+  - `session_meta` — first line: `{session_id, id, timestamp, cwd,
+    originator, cli_version, source, thread_source, model_provider,
+    base_instructions, history_mode: "legacy", context_window}`.
+  - `response_item` — the **model-facing** history. `payload.type`:
+    - `message` — `role` developer/user/assistant; content blocks
+      `input_text` (developer/user) or `output_text` (assistant); assistant
+      messages carry `phase: "commentary" | "final_answer"`.
+      Note: role=user response_items include injected context (permissions,
+      plugins, environment) — the real user prompt is identified by the
+      matching `event_msg/user_message`.
+    - `reasoning` — `encrypted_content`, not portable.
+    - `function_call` — `{name, arguments: <json string>, call_id}` (e.g.
+      `exec_command`).
+    - `function_call_output` — `{call_id, output}` (chunked shell output with
+      exit code header).
+    - `custom_tool_call` / `custom_tool_call_output` — `apply_patch` with
+      `input` = patch text (`*** Begin Patch ...`).
+  - `event_msg` — the **UI-facing** stream. `payload.type`: `task_started`
+    (`turn_id`), `user_message`, `agent_message` (`phase`), `token_count`,
+    `patch_apply_end` (`{stdout, success, changes: {path: {type, content}}}`),
+    `task_complete` (`last_agent_message`).
+  - `turn_context` — per turn: cwd, approval_policy, sandbox_policy, model.
+  - `world_state` — environment snapshot.
+- Resume: `codex resume <session-id>` (interactive) and
+  `codex exec resume <session-id> "<prompt>"` (one-shot). Turn-complete
+  notification hook: `-c 'notify=["/bin/sh","-c","..."]'` per invocation.
+- Turn boundary: `event_msg/task_started` … `event_msg/task_complete`.
+
+## Decisions on the spec's open questions
+
+1. **File discovery** — as above; codex rollouts are found by globbing the
+   session id in the filename (no file reads needed); claude transcripts by
+   deterministic munged-cwd + session id path.
+2. **Hooks vs fs-watch** — both CLIs accept per-invocation hook wiring
+   (`claude --settings` Stop hook; `codex -c notify=[...]`), so tandem wires
+   a turn-complete hook that touches a sentinel file used to flush the sync
+   loop promptly. The transcript tailer (watchdog, polling fallback) remains
+   the source of truth and the fallback when hooks fail — hook output is
+   never parsed, only used as a wake-up signal.
+3. **Placeholder format** — untranslatable entries become, in the shadow's
+   native text form:
+   `[tandem: turn {turn} could not be translated from {source} — {reason};
+   raw entry quarantined at {path}]`
+   with the raw source entry written to
+   `~/.tandem/quarantine/<tandem-id>/<source>-line-<n>.json`.