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

{tandem_cli-0.2.0 → tandem_cli-0.4.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.4.0}/.gitignore

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

tandem_cli-0.4.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: tandem-cli
+Version: 0.4.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. Multiple AI agents. Shared context.**
+
+Use [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
+[OpenAI Codex CLI](https://github.com/openai/codex), and
+[opencode](https://opencode.ai) in one continuous coding session. Work in
+their native interfaces, press **Ctrl-]** to move to the next CLI, and
+continue without copying prompts or rebuilding context by hand.
+
+[![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)
+
+![tandem demo — one session relayed across Claude Code, Codex and opencode](https://raw.githubusercontent.com/Bhavya6187/tandem/main/docs/demo.gif)
+
+</div>
+
+## Quick start
+
+You need Python 3.11+ and at least two supported CLIs installed and signed
+in: [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
+[Codex CLI](https://github.com/openai/codex), or
+[opencode](https://opencode.ai).
+
+```bash
+uv tool install tandem-cli   # or: pip install tandem-cli
+cd your-project
+tandem
+```
+
+Work normally in the CLI that opens. Press **Ctrl-]** to continue the same
+session in the next CLI. If you press it while the model is working, tandem
+waits until the response finishes; press it again to cancel the switch.
+
+Exit normally when you're done. Come back later with:
+
+```bash
+tandem resume      # resume the latest session in this directory
+tandem sessions    # find recent sessions across directories
+```
+
+By default, tandem opens the first usable CLI in your configured order. Use
+`tandem --active codex` or `tandem --active opencode` to choose another.
+
+## Why tandem?
+
+- **Keep going when a model hits its limit.** Move to another CLI and
+  continue with the same files and conversation history.
+- **Bring different models to the same problem.** Ask another CLI for a
+  second opinion without copying a wall of context between terminals.
+- **Keep the native tools you already use.** Claude Code, Codex, and
+  opencode retain their own interfaces, commands, keybindings, and MCP
+  servers.
+- **Work through a single-provider outage.** If another configured CLI is
+  available, switch and continue until the affected provider recovers.
+
+Want GPT subagents inside Claude Code too? See the
+[GPT subagents guide](https://github.com/Bhavya6187/tandem/blob/main/docs/subagents.md).
+For more use cases, see
+[Why tandem?](https://github.com/Bhavya6187/tandem/blob/main/docs/why.md).
+
+## How it works
+
+```text
+┌──────────────────────────────────────────────┐
+│ Work normally in a native coding CLI         │
+└──────────────────────┬───────────────────────┘
+                       ▼
+┌──────────────────────────────────────────────┐
+│ tandem keeps the other sessions in sync      │
+│ locally — without calling another model      │
+└──────────────────────┬───────────────────────┘
+                       ▼
+┌──────────────────────────────────────────────┐
+│ Press Ctrl-] and continue in the next CLI    │
+└──────────────────────────────────────────────┘
+```
+
+Only the active model runs. tandem translates its growing conversation into
+the other CLIs' native session formats using local file access, so they are
+ready when you switch. Your session stays in the CLIs' own storage plus a
+small local database in `~/.tandem`; tandem adds no cloud sync or telemetry.
+
+See [How tandem works](https://github.com/Bhavya6187/tandem/blob/main/docs/how-it-works.md)
+for transcript translation, switching, crash safety, compatibility, and data
+locations.
+
+## Everyday commands
+
+| Command | What it does |
+| --- | --- |
+| `tandem` | Start a new session |
+| `Ctrl-]` | Continue in the next CLI |
+| `tandem resume [id]` | Resume the latest or a specific session in this directory |
+| `tandem sessions [-n N]` | List recent sessions across directories |
+| `tandem run --on codex "…"` | Send one contextual prompt to another CLI (`claude`, `codex`, or `opencode`) |
+
+## Learn more
+
+- [Why tandem?](https://github.com/Bhavya6187/tandem/blob/main/docs/why.md) —
+  use cases, subscriptions, native tools, token visibility, and privacy
+- [GPT subagents](https://github.com/Bhavya6187/tandem/blob/main/docs/subagents.md) —
+  plugin setup, worker models, routing, and sandboxing
+- [Configuration](https://github.com/Bhavya6187/tandem/blob/main/docs/configuration.md) —
+  participants, startup arguments, the switch key, and the status bar
+- [How tandem works](https://github.com/Bhavya6187/tandem/blob/main/docs/how-it-works.md) —
+  synchronization, switching, compatibility, and local data
+- [Developing tandem](https://github.com/Bhavya6187/tandem/blob/main/docs/development.md) —
+  development setup and the harness adapter interface
+- [Observed session formats](https://github.com/Bhavya6187/tandem/blob/main/docs/formats.md) —
+  Claude Code, Codex, and opencode storage formats
+
+## License
+
+[MIT](https://github.com/Bhavya6187/tandem/blob/main/LICENSE)

tandem_cli-0.4.0/README.md

@@ -0,0 +1,119 @@
+<div align="center">
+
+# 🤝 tandem
+
+**One coding session. Multiple AI agents. Shared context.**
+
+Use [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
+[OpenAI Codex CLI](https://github.com/openai/codex), and
+[opencode](https://opencode.ai) in one continuous coding session. Work in
+their native interfaces, press **Ctrl-]** to move to the next CLI, and
+continue without copying prompts or rebuilding context by hand.
+
+[![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)
+
+![tandem demo — one session relayed across Claude Code, Codex and opencode](https://raw.githubusercontent.com/Bhavya6187/tandem/main/docs/demo.gif)
+
+</div>
+
+## Quick start
+
+You need Python 3.11+ and at least two supported CLIs installed and signed
+in: [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
+[Codex CLI](https://github.com/openai/codex), or
+[opencode](https://opencode.ai).
+
+```bash
+uv tool install tandem-cli   # or: pip install tandem-cli
+cd your-project
+tandem
+```
+
+Work normally in the CLI that opens. Press **Ctrl-]** to continue the same
+session in the next CLI. If you press it while the model is working, tandem
+waits until the response finishes; press it again to cancel the switch.
+
+Exit normally when you're done. Come back later with:
+
+```bash
+tandem resume      # resume the latest session in this directory
+tandem sessions    # find recent sessions across directories
+```
+
+By default, tandem opens the first usable CLI in your configured order. Use
+`tandem --active codex` or `tandem --active opencode` to choose another.
+
+## Why tandem?
+
+- **Keep going when a model hits its limit.** Move to another CLI and
+  continue with the same files and conversation history.
+- **Bring different models to the same problem.** Ask another CLI for a
+  second opinion without copying a wall of context between terminals.
+- **Keep the native tools you already use.** Claude Code, Codex, and
+  opencode retain their own interfaces, commands, keybindings, and MCP
+  servers.
+- **Work through a single-provider outage.** If another configured CLI is
+  available, switch and continue until the affected provider recovers.
+
+Want GPT subagents inside Claude Code too? See the
+[GPT subagents guide](https://github.com/Bhavya6187/tandem/blob/main/docs/subagents.md).
+For more use cases, see
+[Why tandem?](https://github.com/Bhavya6187/tandem/blob/main/docs/why.md).
+
+## How it works
+
+```text
+┌──────────────────────────────────────────────┐
+│ Work normally in a native coding CLI         │
+└──────────────────────┬───────────────────────┘
+                       ▼
+┌──────────────────────────────────────────────┐
+│ tandem keeps the other sessions in sync      │
+│ locally — without calling another model      │
+└──────────────────────┬───────────────────────┘
+                       ▼
+┌──────────────────────────────────────────────┐
+│ Press Ctrl-] and continue in the next CLI    │
+└──────────────────────────────────────────────┘
+```
+
+Only the active model runs. tandem translates its growing conversation into
+the other CLIs' native session formats using local file access, so they are
+ready when you switch. Your session stays in the CLIs' own storage plus a
+small local database in `~/.tandem`; tandem adds no cloud sync or telemetry.
+
+See [How tandem works](https://github.com/Bhavya6187/tandem/blob/main/docs/how-it-works.md)
+for transcript translation, switching, crash safety, compatibility, and data
+locations.
+
+## Everyday commands
+
+| Command | What it does |
+| --- | --- |
+| `tandem` | Start a new session |
+| `Ctrl-]` | Continue in the next CLI |
+| `tandem resume [id]` | Resume the latest or a specific session in this directory |
+| `tandem sessions [-n N]` | List recent sessions across directories |
+| `tandem run --on codex "…"` | Send one contextual prompt to another CLI (`claude`, `codex`, or `opencode`) |
+
+## Learn more
+
+- [Why tandem?](https://github.com/Bhavya6187/tandem/blob/main/docs/why.md) —
+  use cases, subscriptions, native tools, token visibility, and privacy
+- [GPT subagents](https://github.com/Bhavya6187/tandem/blob/main/docs/subagents.md) —
+  plugin setup, worker models, routing, and sandboxing
+- [Configuration](https://github.com/Bhavya6187/tandem/blob/main/docs/configuration.md) —
+  participants, startup arguments, the switch key, and the status bar
+- [How tandem works](https://github.com/Bhavya6187/tandem/blob/main/docs/how-it-works.md) —
+  synchronization, switching, compatibility, and local data
+- [Developing tandem](https://github.com/Bhavya6187/tandem/blob/main/docs/development.md) —
+  development setup and the harness adapter interface
+- [Observed session formats](https://github.com/Bhavya6187/tandem/blob/main/docs/formats.md) —
+  Claude Code, Codex, and opencode storage formats
+
+## License
+
+[MIT](https://github.com/Bhavya6187/tandem/blob/main/LICENSE)

tandem_cli-0.4.0/docs/configuration.md

@@ -0,0 +1,114 @@
+# Configuration
+
+tandem reads one optional file: `~/.tandem/config.toml`. No file is
+required; every key has a working default, and a malformed value falls
+back to it rather than failing a launch. (Back to the
+[README](../README.md).)
+
+## harnesses — who participates, and in what order
+
+A top-level list naming the harnesses a fresh session may include, in
+flip-cycle order. Default: all three, claude first.
+
+```toml
+harnesses = ["claude", "codex", "opencode"]
+```
+
+Naming a harness here is an *intent*, not a requirement: a fresh
+`tandem` session pairs the listed harnesses that are actually installed
+and usable — not-installed ones are skipped silently, ones that are
+installed but unusable warn and drop out, and fewer than two usable is
+an error that prints the install command for each missing CLI. The
+order sets both the **Ctrl-]** cycle and the default starting harness
+(`tandem` enters the first usable one; `--active` overrides that per
+launch).
+Leave a harness off the list to keep it out of new sessions even though
+it's installed — `harnesses = ["claude", "codex"]` gives two-way
+sessions on a machine that also has opencode. Unknown names are
+dropped, duplicates deduped, and anything else malformed falls back to
+all three. Sessions already paired keep their own participant list.
+
+## [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] / [opencode] — per-harness startup args
+
+Optional per-harness tables add flags to every interactive session tandem
+opens (`tandem`, `tandem resume`, and each flip) — 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"]
+
+[opencode]
+args = []   # same mechanism; opencode's own flags go here
+```
+
+The claude/codex 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 next harness in the cycle, the one-line tab
+bar on the bottom terminal row (participants, flip key, and the active
+model's live token stats), 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, including the active slot's token stats. `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. Flips *into* opencode are always serial (its TUI must open after the last turn has landed in its database). |
+
+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.
+
+## Environment variables
+
+Not config keys, but honored everywhere: `TANDEM_HOME` relocates
+tandem's own state (`state.db`, config, quarantine, subagent logs) from
+`~/.tandem`; the harnesses' own overrides — `CLAUDE_CONFIG_DIR`,
+`CODEX_HOME`, `OPENCODE_DB` — are respected when tandem looks for their
+session stores.

tandem_cli-0.4.0/docs/development.md

@@ -0,0 +1,98 @@
+# Developing tandem
+
+Dev setup and the extension surface. (Back to the
+[README](../README.md).)
+
+## Development
+
+```bash
+uv sync && uv run pytest
+uv tool install .     # or: pipx install .
+```
+
+Dependencies are deliberately small: `click` (CLI), `pydantic` v2 (event
+schema), `watchdog` (transcript tailing), `pexpect`/ptyprocess (PTY
+passthrough); state is stdlib `sqlite3`.
+
+The suite is hermetic — no harness binaries needed — except
+`tests/test_opencode_oracle.py`, which round-trips through a real
+`opencode` binary against a throwaway database (`OPENCODE_DB`) and skips
+itself when the binary is absent. Two guards worth knowing about:
+`plugin/.claude-plugin/plugin.json`'s `version` must match
+`pyproject.toml` (a drift test fails otherwise — see the
+[plugin README](../plugin/README.md) for why), and CI installs with
+`uv sync --locked`, so a version bump needs `uv lock` in the same
+commit.
+
+## Layout
+
+- `src/tandem/cli.py` — every subcommand; `_resolve_participants` is the
+  one place that decides which harnesses a session gets.
+- `src/tandem/harness/` — one adapter module per CLI (`claude_code.py`,
+  `codex.py`, `opencode.py`) behind `base.HarnessAdapter`; **all**
+  session-format knowledge lives here, so a format change in one tool
+  touches one file. `docs/formats.md` records what each adapter was
+  built against.
+- `src/tandem/sync.py`, `runner.py`, `tailer.py` — the sync engine: one
+  tail loop per (source → target) direction, append-only with a
+  write-ahead intent in the cursor.
+- `src/tandem/events.py`, `converter.py`, `toolmap.py` — the normalized
+  event model, the reference converter, and native tool-call mapping.
+- `src/tandem/flip.py`, `frame.py`, `ptyrun.py`, `warm.py` — the frame:
+  PTY passthrough, the flip key and ladder, the tab bar, pipelined boots.
+- `src/tandem/hookroute.py`, `modelcat.py`, `pinstash.py`,
+  `plugin_setup.py` — GPT subagents: the Claude Code hook, model-name
+  resolution, and plugin install.
+- `src/tandem/state.py`, `compat.py`, `config.py`, `doctor.py` — the
+  SQLite state store, pinned version ranges, `config.toml`, health checks.
+
+## Extending tandem
+
+### Adding a harness
+
+Every CLI tandem fronts is one `HarnessAdapter` subclass in
+`src/tandem/harness/`, registered in `harness/__init__.py`'s `ADAPTERS`
+and named in `config.SUPPORTED_HARNESSES` and `compat.COMPAT`. The base
+class in `harness/base.py` is the contract; the pieces an adapter
+provides:
+
+- **Detection and readiness** — `detect_version`, `version_supported`
+  (against its `compat.COMPAT` range), `runtime_ready` (fail closed:
+  installed but unusable drops out of the session with a reason), and
+  an `install_hint` for the "fewer than two harnesses" error.
+- **Session identity and storage** — `mint_session_id`,
+  `transcript_path`, `create_shadow_transcript` (how a resume-ready
+  shadow is born), plus the storage-capability hooks that default to
+  file-backed JSONL and that opencode overrides for SQLite:
+  `make_source_reader`, `watch_paths`, `shadow_append` /
+  `shadow_intent` / `intent_landed`, `fast_forward_cursor`,
+  `pending_units`, `prepare_shadow`.
+- **Launch** — `interactive_argv`, `oneoff_argv`, `hook_argv_extra`
+  (the per-invocation turn-complete signal, if the CLI has one),
+  `quit_keystrokes` (the graceful half of the exit ladder), and
+  `session_status` when the CLI can answer "is a turn running?" — that
+  is what lets a mid-turn flip fire at the boundary.
+- **Translation** — `parse_entry` (native record → normalized events)
+  and `render_events` / `render_placeholder` (normalized events → native
+  records), with `toolmap` optionally given a Tier-1 table so common tool
+  calls read as the harness's own; without one, calls pass through
+  verbatim.
+- **Cosmetics** — `make_usage_meter` for the tab bar's token stats.
+
+`tests/` has per-adapter fixtures; an oracle test against the real binary
+(like the opencode one) is the strongest check that shadow sessions
+actually resume.
+
+### Swapping the 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, target, converter=...)`.

{tandem_cli-0.2.0 → tandem_cli-0.4.0}/docs/formats.md

@@ -1,16 +1,17 @@
 # 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:
+Everything tandem knows about the three native session formats was observed
+on this machine by creating throwaway sessions and reading the files (or
+database) 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` |
+| opencode (`opencode`) | 1.18.15 | one SQLite database, the path `opencode db path` prints (see below) |
 
 Env overrides honored: `CLAUDE_CONFIG_DIR` (claude home), `CODEX_HOME` (codex
-home), `TANDEM_HOME` (tandem state).
+home), `OPENCODE_DB` (opencode database), `TANDEM_HOME` (tandem state).
 
 ## Claude Code transcript (claude 2.1.220)
 
@@ -110,3 +111,38 @@ home), `TANDEM_HOME` (tandem state).
    raw entry quarantined at {path}]`
    with the raw source entry written to
    `~/.tandem/quarantine/<tandem-id>/<source>-line-<n>.json`.
+
+## opencode session storage (opencode 1.18.15)
+
+- Storage: one WAL-mode SQLite DB for everything — `opencode db path`
+  (channel-suffixed filename; `$OPENCODE_DB` overrides). No per-session
+  files. Tables: `session`, `message`, `part`; JSON payloads in `data`
+  minus the id/fk columns. FKs cascade part -> message -> session -> project.
+- Ordering: messages by `(time_created, id)`; parts by part id ONLY.
+- IDs: `<prefix>_` + 12 hex chars (48-bit `ms*4096+counter`) + 14 random
+  base62. `ses_` NOTs the value (descending); `msg_`/`prt_` ascending.
+  Live-verified: msg @ ms=1786577389138 ctr=1 -> `ff84f8652001`.
+- Threading is flat: assistant `parentID` = the turn's user message id.
+- Spelling trap: session-row `model` JSON uses `{id, providerID}`; message
+  payloads use `{modelID, providerID}`. Session-level `agent`/`model` are
+  optional; MESSAGE-level are required on user messages. Session-level
+  `slug` is REQUIRED by import's decoder (oracle-verified: the payload is
+  rejected `at ["slug"]` without it) but carries no uniqueness constraint —
+  opencode mints adjective-noun pairs; tandem seeds `tandem-pair`.
+- Tool parts mutate in place (pending -> running -> completed): tandem reads
+  whole completed turns only (last assistant has `time.completed` + terminal
+  `finish`).
+- External writes: the `opencode import` recipe (plain INSERT, conflict-
+  ignore). Tandem's shadow birth delegates to `opencode import`; incremental
+  sync writes rows directly with pre-minted ids (idempotent replay).
+- Tandem attribution: `providerID: "tandem"`, `modelID: "<synced>"` — marks
+  echoes for the parser and makes opencode degrade replay metadata instead
+  of re-sending forged provider signatures.
+- Hazards: a running TUI never sees external rows for an already-synced
+  session (writes land while opencode is closed; flips relaunch it); a
+  session whose last message is not a completed assistant renders as
+  perpetually "working"; the session list window is 30 days by
+  `time_updated`; always open the DB read-write (WAL).
+- Resume: `opencode -s <id>` (id must exist; no directory match);
+  one-off: `opencode run -s <id> "<prompt>"`. No per-invocation
+  turn-complete hook — tandem fs-watches the `-wal` file.