@theharshitsingh/hc 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harshit Singh Bhandari
+
+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.

package/README.md

@@ -0,0 +1,66 @@
+# harness-convert (`hc`)
+
+Relocate a coding-agent session across harnesses and resume it natively.
+
+**The escape hatch:** you're 80% through a fix, your harness hits a rate limit /
+outage mid-task, and you can't even ask it for a handoff. `hc` reads the session
+transcript off disk (the dead harness doesn't need to be running or your quota
+intact), rewrites it into the target harness's format, and you keep going there.
+
+```bash
+hc --from claude --to codex                 # move the latest Claude session here -> Codex
+hc --from codex  --to claude <session-id>   # a specific session
+hc --from claude --to codex --dest-cwd DIR  # land it in a different folder
+hc list --from codex                        # what's the latest convertible session here
+```
+
+By default it's a dry run; pass `--write` to create the file, then it prints the
+exact `codex resume` / `claude --resume` command.
+
+## How it works
+
+A session is **(a)** a model-context stream, **(b)** a UI-render stream, and
+**(c)** identity metadata. Conversion maps all three.
+
+- **Common interface** (`hconv/common.py`): every harness maps to four records:
+  `UserMessage`, `AssistantMessage`, `ToolCall`, `ToolResult`. This universal floor
+  guarantees any pair converts and resumes. Private reasoning is dropped (each
+  harness encrypts/owns its own; unrecoverable).
+- **N² enrichment** (`hconv/enrich.py`): surplus the floor can't hold (session
+  titles, ...) rides a sparse `(source, dest)` map, layered on top. A pair with no
+  entry is simply common-only. The map never re-encodes the common records.
+- **Adapters** (`hconv/adapters/`): one per harness, `locate / read / dest_path /
+  write`. Codex's writer emits BOTH streams (`response_item` for the model,
+  `event_msg` for scrollback incl. `exec_command_end` / `patch_apply_end` tool
+  cards); Claude's single row set serves both. OpenCode is SQLite, not JSONL: it
+  reads the `session`/`message`/`part` tables read-only, and writes the canonical
+  `{info, messages}` file that `opencode import` validates and ingests (safer than
+  poking a live WAL DB), so `opencode -s <id>` resumes it.
+- **Ragged-tail close** (`synthesize_missing_results`): the source usually died
+  mid-tool-call, so every orphan `ToolCall` gets a synthetic result, else the
+  resumed API call rejects the history.
+
+## Install
+
+```bash
+pipx install harness-convert                            # PyPI
+npm i -g @theharshitsingh/hc                            # npm (needs python3 on PATH)
+brew install harshitsinghbhandari/tap/harness-convert   # Homebrew
+```
+
+Stdlib only, no dependencies. From a checkout, `pipx install .` or plain
+`python3 hc.py ...` also work.
+
+## Supported
+
+Codex (`~/.codex`), Claude Code (`~/.claude`), and OpenCode
+(`~/.local/share/opencode`): any direction between them. Converting *into*
+OpenCode writes an import file; resume with `opencode import <file> && opencode -s
+<id>` (the command `hc` prints). Within a harness, sessions are also freely
+relocatable across working directories (pure metadata rewrite, lossless).
+
+## Test
+
+```bash
+python3 tests/test_hconv.py
+```

package/bin/hc.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..");
+const existing = process.env.PYTHONPATH;
+const env = {
+  ...process.env,
+  PYTHONPATH: existing ? `${root}${path.delimiter}${existing}` : root,
+};
+
+function run(python) {
+  return spawnSync(python, ["-m", "hconv.cli", ...process.argv.slice(2)], {
+    stdio: "inherit",
+    env,
+  });
+}
+
+let result = run("python3");
+if (result.error && result.error.code === "ENOENT") {
+  result = run("python");
+}
+
+if (result.error) {
+  console.error(`hc: failed to launch Python: ${result.error.message}`);
+  process.exit(127);
+}
+
+process.exit(result.status ?? 1);

package/hc.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Dev shim so `python3 hc.py ...` works without installing. The real entry
+point is `hc` (see pyproject.toml -> hconv.cli:main)."""
+from hconv.cli import main
+
+if __name__ == "__main__":
+    main()

package/hconv/__init__.py

@@ -0,0 +1,13 @@
+"""harness-convert: relocate a coding-agent session across harnesses.
+
+Common interface (common.py) every harness maps to + an N^2 enrichment map
+(enrich.py) for the surplus. Adapters (adapters/) read/write each harness.
+"""
+from .common import (AssistantMessage, Session, ToolCall, ToolResult,
+                     UserMessage, synthesize_missing_results)
+from .adapter import Adapter, convert, get, known, register
+from . import adapters  # noqa: F401  (registers claude + codex)
+
+__all__ = ["Session", "UserMessage", "AssistantMessage", "ToolCall",
+           "ToolResult", "synthesize_missing_results", "Adapter",
+           "convert", "get", "known", "register"]

package/hconv/adapter.py

@@ -0,0 +1,82 @@
+"""Adapter contract + registry. One adapter per harness.
+
+The whole conversion pipeline is:
+
+    src.locate(cwd, id?)  ->  path
+    src.read(path)        ->  Session            (transcript -> common interface)
+    normalize(session)    ->  Session            (close ragged tails, shared)
+    enrich(src, dst, s)   ->  Session            (N^2 surplus, optional)
+    dst.write(session)    ->  path               (common interface -> transcript)
+
+The common path (locate/read/write over the four records) guarantees any pair
+works. Enrichment only adds surplus and is allowed to be missing.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from .common import Session, synthesize_missing_results
+
+
+class Adapter(ABC):
+    """A harness's reader/writer/locator. Subclasses set `name` and register()."""
+
+    name: str
+
+    @abstractmethod
+    def locate(self, cwd: str, session_id: str | None = None) -> Path:
+        """Resolve a transcript file. With session_id: that session. Without:
+        the most recent session for `cwd` in this harness's store (the fast-path
+        default that makes `hc --from X --to Y` need no id)."""
+
+    @abstractmethod
+    def read(self, path: Path) -> Session:
+        """Parse a transcript file into the common Session. Drops private
+        reasoning; stashes harness surplus into Session.extra for enrichment."""
+
+    @abstractmethod
+    def dest_path(self, session: Session, dest_cwd: str) -> Path:
+        """Where a converted Session WOULD be written under dest_cwd. Pure; no IO.
+        Used for dry-run and so write() and the dry-run path never disagree."""
+
+    @abstractmethod
+    def write(self, session: Session, dest_cwd: str) -> Path:
+        """Materialize a Session as this harness's transcript at dest_path(),
+        rewriting identity (id/cwd) so the result is self-consistent and natively
+        resumable. Returns the written path."""
+
+
+_REGISTRY: dict[str, Adapter] = {}
+
+
+def register(adapter: Adapter) -> Adapter:
+    _REGISTRY[adapter.name] = adapter
+    return adapter
+
+
+def get(name: str) -> Adapter:
+    try:
+        return _REGISTRY[name]
+    except KeyError:
+        known = ", ".join(sorted(_REGISTRY)) or "(none registered)"
+        raise SystemExit(f"unknown harness '{name}'. known: {known}")
+
+
+def known() -> list[str]:
+    return sorted(_REGISTRY)
+
+
+def convert(src_name: str, dst_name: str, cwd: str, dest_cwd: str,
+            session_id: str | None = None, write: bool = False):
+    """Run the full pipeline. Returns (session, dest_path). Writes only if asked."""
+    from .enrich import enrich
+
+    src, dst = get(src_name), get(dst_name)
+    path = src.locate(cwd, session_id)
+    session = src.read(path)
+    session.records = synthesize_missing_results(session.records)
+    enrich(src_name, dst_name, session)
+    if not write:
+        return session, dst.dest_path(session, dest_cwd)
+    return session, dst.write(session, dest_cwd)

package/hconv/adapters/__init__.py

@@ -0,0 +1,2 @@
+"""Importing this package registers every adapter."""
+from . import claude, codex, opencode  # noqa: F401

package/hconv/adapters/claude.py

@@ -0,0 +1,164 @@
+"""Claude Code adapter.
+
+Transcript: ~/.claude/projects/<enc(cwd)>/<sessionId>.jsonl, a parentUuid tree.
+One row set both renders and feeds the model (no dual stream). Resume keys off
+(launch cwd -> project dir) + (filename stem == sessionId) + the tree.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import uuid
+from pathlib import Path
+
+from ..adapter import Adapter, register
+from ..common import (AssistantMessage, Session, ToolCall, ToolResult,
+                      UserMessage)
+
+PROJECTS = Path(os.path.expanduser("~/.claude/projects"))
+VERSION = "2.1.153"
+
+# Codex tool vocabulary -> Claude's, so converted calls render as native cards.
+INBOUND_NAMES = {"exec_command": "Bash", "shell": "Bash",
+                 "apply_patch": "Edit", "read_file": "Read", "view_image": "Read"}
+
+
+def enc(cwd: str) -> str:
+    """Claude's project-dir encoding: every non-alphanumeric char -> '-'."""
+    return re.sub(r"[^A-Za-z0-9]", "-", cwd)
+
+
+def _toolu(call_id: str) -> str:
+    return "toolu_" + hashlib.sha1(call_id.encode()).hexdigest()[:24]
+
+
+class ClaudeAdapter(Adapter):
+    name = "claude"
+
+    def locate(self, cwd: str, session_id: str | None = None) -> Path:
+        d = PROJECTS / enc(cwd)
+        if session_id:
+            p = d / f"{session_id}.jsonl"
+            if not p.exists():
+                raise SystemExit(f"no Claude session {session_id} under {d}")
+            return p
+        files = sorted(d.glob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True)
+        if not files:
+            raise SystemExit(f"no Claude sessions found for cwd {cwd} (looked in {d})")
+        return files[0]
+
+    def read(self, path: Path) -> Session:
+        sid = path.stem
+        cwd = git = started = title = ""
+        records = []
+        for line in path.read_text().splitlines():
+            if not line.strip():
+                continue
+            try:
+                d = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if d.get("aiTitle"):
+                title = d["aiTitle"]
+            if d.get("type") not in ("user", "assistant") or not d.get("uuid"):
+                continue
+            if d.get("isSidechain"):
+                continue
+            cwd = d.get("cwd", cwd) or cwd
+            git = d.get("gitBranch", git) or git
+            started = started or d.get("timestamp", "")
+            ts = d.get("timestamp", "")
+            msg = d.get("message", {})
+            role = msg.get("role")
+            content = msg.get("content")
+            if isinstance(content, str):
+                records.append((UserMessage if role == "user" else AssistantMessage)(content, ts))
+                continue
+            if not isinstance(content, list):
+                continue
+            text = []
+            for b in content:
+                if not isinstance(b, dict):
+                    continue
+                bt = b.get("type")
+                if bt == "text":
+                    text.append(b.get("text", ""))
+                elif bt == "tool_use":
+                    if text:
+                        records.append(AssistantMessage("\n".join(text), ts)); text = []
+                    records.append(ToolCall(b["id"], b.get("name", "tool"),
+                                            b.get("input", {}) or {}, ts))
+                elif bt == "tool_result":
+                    c = b.get("content", "")
+                    if isinstance(c, list):
+                        c = "".join(x.get("text", "") if isinstance(x, dict) else str(x) for x in c)
+                    records.append(ToolResult(b["tool_use_id"],
+                                              c if isinstance(c, str) else json.dumps(c),
+                                              ts, bool(b.get("is_error"))))
+                # thinking / redacted_thinking -> dropped
+            if text:
+                records.append((UserMessage if role == "user" else AssistantMessage)("\n".join(text), ts))
+        s = Session("claude", sid, cwd, records, git, started)
+        if title:
+            s.extra["title"] = title
+        return s
+
+    def dest_path(self, session: Session, dest_cwd: str) -> Path:
+        return PROJECTS / enc(dest_cwd) / f"{session.session_id}.jsonl"
+
+    def write(self, session: Session, dest_cwd: str) -> Path:
+        # records -> Claude rows, merging consecutive same-side blocks into one
+        # message (Anthropic tool-ordering), chaining parentUuid into a tree.
+        merged, side, blocks = [], None, []
+
+        def block_of(r):
+            if isinstance(r, UserMessage):
+                return "user", {"type": "text", "text": r.text}
+            if isinstance(r, AssistantMessage):
+                return "assistant", {"type": "text", "text": r.text}
+            if isinstance(r, ToolCall):
+                return "assistant", {"type": "tool_use", "id": _toolu(r.call_id),
+                                     "name": INBOUND_NAMES.get(r.name, r.name), "input": r.input}
+            return "user", {"type": "tool_result", "tool_use_id": _toolu(r.call_id),
+                            "content": r.output, **({"is_error": True} if r.is_error else {})}
+
+        ts = session.started_at
+        for r in session.records:
+            s, b = block_of(r)
+            if s != side and blocks:
+                merged.append((side, blocks, ts)); blocks = []
+            side, ts = s, getattr(r, "ts", "") or session.started_at
+            blocks.append(b)
+        if blocks:
+            merged.append((side, blocks, ts))
+
+        rows, prev = [], None
+        for s, blks, ts in merged:
+            u = str(uuid.uuid4())
+            content = (blks[0]["text"] if s == "user" and len(blks) == 1
+                       and blks[0]["type"] == "text" else blks)
+            msg = {"role": s, "content": content}
+            if s == "assistant":
+                msg["model"] = "claude-opus-4-7"
+            rows.append({"parentUuid": prev, "isSidechain": False, "userType": "external",
+                         "cwd": dest_cwd, "sessionId": session.session_id, "version": VERSION,
+                         "gitBranch": session.git_branch, "type": s, "message": msg,
+                         "uuid": u, "timestamp": ts})
+            prev = u
+
+        # N^2 surplus: a session title rides as an ai-title row.
+        ai_title = session.extra.get("out", {}).get("ai_title")
+        if ai_title:
+            rows.append({"type": "ai-title", "aiTitle": ai_title,
+                         "sessionId": session.session_id, "uuid": str(uuid.uuid4()),
+                         "timestamp": session.started_at})
+
+        dest = self.dest_path(session, dest_cwd)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text("".join(json.dumps(r) + "\n" for r in rows))
+        return dest
+
+
+register(ClaudeAdapter())

package/hconv/adapters/codex.py

@@ -0,0 +1,204 @@
+"""Codex adapter.
+
+Transcript: ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<id>.jsonl, a flat log with
+TWO parallel streams: response_item (model context, replayed on resume) and
+event_msg (UI scrollback, replayed to paint history). BOTH are required, else
+resume works but the conversation is invisible. Sessions are stored by date, so
+locating "latest for cwd" means scanning rollouts and filtering session_meta.cwd.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from ..adapter import Adapter, register
+from ..common import (AssistantMessage, Session, ToolCall, ToolResult,
+                      UserMessage)
+
+SESSIONS = Path(os.path.expanduser("~/.codex/sessions"))
+INDEX = Path(os.path.expanduser("~/.codex/session_index.jsonl"))
+CLI_VERSION = "0.142.2"
+
+# Claude tool vocabulary -> Codex's. (Cosmetic: history is context, not re-run.)
+INBOUND_NAMES = {"Bash": "shell", "Edit": "apply_patch", "Write": "apply_patch",
+                 "Read": "read_file"}
+# Which destination tool names render as a shell card vs a patch card.
+SHELL_NAMES = {"shell", "exec_command", "Bash", "local_shell"}
+PATCH_NAMES = {"apply_patch", "Edit", "Write"}
+
+
+def _call(call_id: str) -> str:
+    return "call_" + hashlib.sha1(call_id.encode()).hexdigest()[:22]
+
+
+class CodexAdapter(Adapter):
+    name = "codex"
+
+    def _meta(self, path: Path) -> dict:
+        with path.open() as fh:
+            first = fh.readline()
+        try:
+            d = json.loads(first)
+            return d["payload"] if d.get("type") == "session_meta" else {}
+        except (json.JSONDecodeError, KeyError):
+            return {}
+
+    def locate(self, cwd: str, session_id: str | None = None) -> Path:
+        if session_id:
+            hits = list(SESSIONS.glob(f"**/rollout-*{session_id}*.jsonl"))
+            if not hits:
+                raise SystemExit(f"no Codex session {session_id} under {SESSIONS}")
+            return hits[0]
+        best = None  # newest rollout whose session_meta.cwd matches
+        for p in SESSIONS.glob("**/rollout-*.jsonl"):
+            m = self._meta(p)
+            if m.get("cwd") == cwd:
+                ts = m.get("timestamp", "")
+                if best is None or ts > best[0]:
+                    best = (ts, p)
+        if best is None:
+            raise SystemExit(f"no Codex sessions found for cwd {cwd}")
+        return best[1]
+
+    def _title(self, sid: str) -> str:
+        if not INDEX.exists():
+            return ""
+        for line in INDEX.read_text().splitlines():
+            try:
+                d = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if d.get("id") == sid:
+                return d.get("thread_name", "")
+        return ""
+
+    def read(self, path: Path) -> Session:
+        meta = self._meta(path)
+        sid = meta.get("id", path.stem)
+        cwd = meta.get("cwd", "")
+        git = (meta.get("git") or {}).get("branch", "")
+        started = meta.get("timestamp", "")
+        records = []
+        for line in path.read_text().splitlines():
+            if not line.strip():
+                continue
+            try:
+                d = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if d.get("type") != "response_item":
+                continue
+            p = d["payload"]
+            pt = p.get("type")
+            ts = d.get("timestamp", "")
+            if pt == "reasoning":
+                continue
+            if pt == "message":
+                role = p.get("role")
+                if role == "developer":
+                    continue
+                text = "".join(c.get("text", "") for c in p.get("content", [])
+                               if c.get("type") in ("input_text", "output_text", "text"))
+                if not text.strip():
+                    continue
+                records.append((AssistantMessage if role == "assistant" else UserMessage)(text, ts))
+            elif pt in ("function_call", "custom_tool_call"):
+                raw = p.get("arguments", p.get("input", ""))
+                try:
+                    inp = json.loads(raw) if isinstance(raw, str) else (raw or {})
+                except json.JSONDecodeError:
+                    inp = {"raw": raw}
+                records.append(ToolCall(p["call_id"], p.get("name", "tool"),
+                                        inp if isinstance(inp, dict) else {"input": inp}, ts))
+            elif pt in ("function_call_output", "custom_tool_call_output"):
+                o = p.get("output", "")
+                records.append(ToolResult(p["call_id"],
+                                          o if isinstance(o, str) else json.dumps(o), ts))
+        s = Session("codex", sid, cwd, records, git, started)
+        title = self._title(sid)
+        if title:
+            s.extra["title"] = title
+        return s
+
+    def dest_path(self, session: Session, dest_cwd: str) -> Path:
+        ts = session.started_at or "1970-01-01T00:00:00Z"
+        date, _, rest = ts.partition("T")
+        hms = rest.split(".")[0].replace(":", "-") or "00-00-00"
+        y, m, d = date.split("-")
+        return SESSIONS / y / m / d / f"rollout-{date}T{hms}-{session.session_id}.jsonl"
+
+    def write(self, session: Session, dest_cwd: str) -> Path:
+        out = []
+        calls = {r.call_id: r for r in session.records if isinstance(r, ToolCall)}
+
+        def ri(payload, ts):
+            out.append({"timestamp": ts, "type": "response_item", "payload": payload})
+
+        def ev(payload, ts):
+            out.append({"timestamp": ts, "type": "event_msg", "payload": payload})
+
+        def tool_card(call: ToolCall, result: ToolResult, ts):
+            """The event_msg the TUI renders a tool card from (only _end exists)."""
+            name = INBOUND_NAMES.get(call.name, call.name)
+            cid = _call(call.call_id)
+            if name in PATCH_NAMES:
+                ev({"type": "patch_apply_end", "call_id": cid, "stdout": result.output,
+                    "stderr": "", "success": not result.is_error}, ts)
+            elif name in SHELL_NAMES:
+                cmd = call.input.get("command") or call.input.get("cmd") or ""
+                ev({"type": "exec_command_end", "call_id": cid,
+                    "command": ["/bin/zsh", "-lc", cmd] if isinstance(cmd, str) else cmd,
+                    "cwd": dest_cwd, "stdout": result.output, "stderr": "",
+                    "aggregated_output": result.output,
+                    "exit_code": 1 if result.is_error else 0,
+                    "status": "failed" if result.is_error else "completed"}, ts)
+            # other tools (Read, MCP, ...) -> function_call_output carries them; no card
+
+        for r in session.records:
+            ts = getattr(r, "ts", "") or session.started_at
+            if isinstance(r, UserMessage):
+                ri({"type": "message", "role": "user",
+                    "content": [{"type": "input_text", "text": r.text}]}, ts)
+                ev({"type": "user_message", "message": r.text}, ts)
+            elif isinstance(r, AssistantMessage):
+                ri({"type": "message", "role": "assistant",
+                    "content": [{"type": "output_text", "text": r.text}]}, ts)
+                ev({"type": "agent_message", "message": r.text}, ts)
+            elif isinstance(r, ToolCall):
+                ri({"type": "function_call", "name": INBOUND_NAMES.get(r.name, r.name),
+                    "arguments": json.dumps(r.input), "call_id": _call(r.call_id)}, ts)
+            elif isinstance(r, ToolResult):
+                ri({"type": "function_call_output", "call_id": _call(r.call_id),
+                    "output": r.output}, ts)
+                if r.call_id in calls:
+                    tool_card(calls[r.call_id], r, ts)
+
+        meta = {"timestamp": session.started_at, "type": "session_meta",
+                "payload": {"id": session.session_id, "timestamp": session.started_at,
+                            "cwd": dest_cwd, "originator": "codex-cli",
+                            "cli_version": CLI_VERSION, "instructions": None,
+                            **({"git": {"branch": session.git_branch}} if session.git_branch else {})}}
+        dest = self.dest_path(session, dest_cwd)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text("".join(json.dumps(l) + "\n" for l in [meta] + out))
+
+        # N^2 surplus: a session title goes in the index the picker reads.
+        name = session.extra.get("out", {}).get("thread_name")
+        if name:
+            self._index_put(session.session_id, name, session.started_at)
+        return dest
+
+    def _index_put(self, sid: str, thread_name: str, updated_at: str) -> None:
+        rows = []
+        if INDEX.exists():
+            rows = [l for l in INDEX.read_text().splitlines()
+                    if l.strip() and json.loads(l).get("id") != sid]
+        rows.append(json.dumps({"id": sid, "thread_name": thread_name,
+                                "updated_at": updated_at}))
+        INDEX.parent.mkdir(parents=True, exist_ok=True)
+        INDEX.write_text("\n".join(rows) + "\n")
+
+
+register(CodexAdapter())

package/hconv/adapters/opencode.py

@@ -0,0 +1,258 @@
+"""OpenCode adapter.
+
+Storage is SQLite, not JSONL: $XDG_DATA_HOME/opencode/opencode.db, with three
+tables (session, message, part) whose `data` columns hold JSON. A `tool` part
+bundles the call AND its result together (state.input / state.output /
+state.status), where Codex/Claude keep them as two separate records; read()
+splits it back into our ToolCall + ToolResult, write() fuses them.
+
+Read is direct + read-only (the dead source harness never has to run). Write does
+NOT poke the live DB (FK to project, WAL, drizzle schema drift = corruption risk);
+it emits the canonical `{info, messages}` interchange file that `opencode import`
+validates and ingests, preserving the id so `opencode -s <id>` resumes it.
+
+Times on disk are epoch-milliseconds ints; the common records carry ISO strings
+(what Codex/Claude use), so we convert on the boundary in both directions.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..adapter import Adapter, register
+from ..common import (AssistantMessage, Session, ToolCall, ToolResult,
+                      UserMessage)
+
+DATA = (Path(os.environ.get("XDG_DATA_HOME") or "~/.local/share").expanduser()
+        / "opencode")
+DB = DATA / "opencode.db"
+IMPORTS = DATA / "imports"                       # where write() drops import files
+STATE = (Path(os.environ.get("XDG_STATE_HOME") or "~/.local/state").expanduser()
+         / "opencode")
+VERSION = "1.14.46"
+
+# Claude/Codex tool vocab -> OpenCode's (cosmetic: history is context, not re-run).
+INBOUND_NAMES = {"Bash": "bash", "shell": "bash", "exec_command": "bash",
+                 "local_shell": "bash", "Edit": "edit", "apply_patch": "edit",
+                 "Write": "write", "Read": "read", "read_file": "read",
+                 "view_image": "read"}
+
+
+def _iso(ms) -> str:
+    try:
+        return (datetime.fromtimestamp(int(ms) / 1000, tz=timezone.utc)
+                .isoformat().replace("+00:00", "Z"))
+    except (TypeError, ValueError, OSError):
+        return ""
+
+
+def _ms(iso: str) -> int:
+    if not iso:
+        return 0
+    try:
+        return int(datetime.fromisoformat(iso.replace("Z", "+00:00"))
+                   .timestamp() * 1000)
+    except ValueError:
+        return 0
+
+
+def _id(prefix: str, *seed) -> str:
+    """Deterministic opencode-style id, so re-importing upserts instead of piling
+    up duplicates (import keys off the id)."""
+    return prefix + hashlib.sha1(":".join(map(str, seed)).encode()).hexdigest()[:24]
+
+
+def _default_model() -> dict:
+    """The model the resumed scrollback attributes to past assistant turns. Read
+    the user's own recent choice so it renders native; fall back to a generic id.
+    ponytail: cosmetic metadata on already-happened turns, never re-run."""
+    try:
+        recent = json.loads((STATE / "model.json").read_text()).get("recent") or []
+        if recent:
+            return {"providerID": recent[0]["providerID"],
+                    "modelID": recent[0]["modelID"]}
+    except (OSError, ValueError, KeyError):
+        pass
+    return {"providerID": "anthropic", "modelID": "claude-sonnet-4-6"}
+
+
+class OpenCodeAdapter(Adapter):
+    name = "opencode"
+
+    # locate() returns "<db>#<session_id>": one db holds every session, so a bare
+    # path can't address one. read() splits the id back off.
+    def _open(self) -> sqlite3.Connection:
+        return sqlite3.connect(f"file:{DB}?mode=ro", uri=True)
+
+    def locate(self, cwd: str, session_id: str | None = None) -> Path:
+        if not DB.exists():
+            raise SystemExit(f"no OpenCode database at {DB}")
+        con = self._open()
+        try:
+            if session_id:
+                row = con.execute(
+                    "SELECT id FROM session WHERE id = ? OR id LIKE ? "
+                    "ORDER BY time_created DESC LIMIT 1",
+                    (session_id, f"%{session_id}%")).fetchone()
+                if not row:
+                    raise SystemExit(f"no OpenCode session {session_id} in {DB}")
+                return Path(f"{DB}#{row[0]}")
+            row = con.execute(
+                "SELECT id FROM session WHERE directory = ? "
+                "ORDER BY time_created DESC LIMIT 1", (cwd,)).fetchone()
+            if not row:
+                raise SystemExit(f"no OpenCode sessions found for cwd {cwd}")
+            return Path(f"{DB}#{row[0]}")
+        finally:
+            con.close()
+
+    def read(self, path: Path) -> Session:
+        _, _, sid = str(path).rpartition("#")
+        con = self._open()
+        try:
+            srow = con.execute(
+                "SELECT directory, title, time_created FROM session WHERE id = ?",
+                (sid,)).fetchone()
+            if not srow:
+                raise SystemExit(f"no OpenCode session {sid} in {DB}")
+            cwd, title, started_ms = srow
+            records = []
+            msgs = con.execute(
+                "SELECT id, data FROM message WHERE session_id = ? "
+                "ORDER BY time_created, id", (sid,)).fetchall()
+            for mid, mdata in msgs:
+                role = json.loads(mdata).get("role")
+                Msg = AssistantMessage if role == "assistant" else UserMessage
+                parts = con.execute(
+                    "SELECT data FROM part WHERE message_id = ? "
+                    "ORDER BY time_created, id", (mid,)).fetchall()
+                for (pdata,) in parts:
+                    p = json.loads(pdata)
+                    pt = p.get("type")
+                    ts = _iso(p.get("time", {}).get("start") if pt == "tool"
+                              else started_ms)
+                    if pt == "text":
+                        t = p.get("text", "")
+                        if t.strip():
+                            records.append(Msg(t, _iso(started_ms)))
+                    elif pt == "tool":
+                        st = p.get("state", {}) or {}
+                        cid = p.get("callID", p.get("id", ""))
+                        records.append(ToolCall(cid, p.get("tool", "tool"),
+                                                st.get("input") or {}, ts))
+                        status = st.get("status")
+                        if status in ("completed", "error"):
+                            records.append(ToolResult(
+                                cid, st.get("output", ""), ts,
+                                is_error=(status == "error")))
+                        # running/pending -> no result; synthesize closes it
+                    # reasoning / step-* / file / patch / compaction -> dropped
+            s = Session("opencode", sid, cwd or "", records,
+                        started_at=_iso(started_ms))
+            if title and not title.startswith("New session"):
+                s.extra["title"] = title
+            return s
+        finally:
+            con.close()
+
+    def dest_path(self, session: Session, dest_cwd: str) -> Path:
+        return IMPORTS / f"{session.session_id}.json"
+
+    def write(self, session: Session, dest_cwd: str) -> Path:
+        sid = session.session_id
+        model = _default_model()
+        results = {r.call_id: r for r in session.records
+                   if isinstance(r, ToolResult)}
+        consumed: set[str] = set()
+
+        def text_part(mid, i, text):
+            return {"type": "text", "text": text, "id": _id("prt_", sid, mid, i),
+                    "sessionID": sid, "messageID": mid}
+
+        def tool_part(mid, i, call: ToolCall):
+            res = results.get(call.call_id)
+            consumed.add(call.call_id)
+            name = INBOUND_NAMES.get(call.name, call.name.lower())
+            ms = _ms(call.ts) or _ms(session.started_at)
+            time = {"start": ms, "end": _ms(res.ts) if res else ms}
+            # error tool parts carry state.error (a string); completed carry output.
+            if res and res.is_error:
+                state = {"status": "error", "input": call.input,
+                         "error": res.output, "time": time}
+            else:
+                state = {"status": "completed", "input": call.input,
+                         "output": res.output if res else "",
+                         "metadata": {}, "title": name, "time": time}
+            return {"type": "tool", "tool": name,
+                    "callID": _id("call_", call.call_id), "state": state,
+                    "id": _id("prt_", sid, mid, i), "sessionID": sid, "messageID": mid}
+
+        # Group records into role-runs; a message is one role's contiguous parts.
+        runs: list[tuple[str, list]] = []
+        side = None
+        for r in session.records:
+            s = "user" if isinstance(r, UserMessage) else "assistant"
+            if isinstance(r, ToolResult) and r.call_id in consumed:
+                continue  # already fused into its ToolCall's tool part
+            if s != side:
+                runs.append((s, [])); side = s
+            runs[-1][1].append(r)
+
+        messages, prev_mid = [], None
+        for run_i, (s, recs) in enumerate(runs):
+            mid = _id("msg_", sid, run_i)
+            parts = []
+            for i, r in enumerate(recs):
+                if isinstance(r, (UserMessage, AssistantMessage)):
+                    parts.append(text_part(mid, i, r.text))
+                elif isinstance(r, ToolCall):
+                    parts.append(tool_part(mid, i, r))
+                elif isinstance(r, ToolResult):  # orphan result (no matching call)
+                    parts.append(text_part(mid, i, r.output))
+            if not parts:
+                continue
+            created = _ms(getattr(recs[0], "ts", "")) or _ms(session.started_at)
+            if s == "user":
+                info = {"role": "user", "time": {"created": created},
+                        "agent": "build", "model": model,
+                        "summary": {"diffs": []}, "id": mid, "sessionID": sid}
+            else:
+                info = {"parentID": prev_mid or mid, "role": "assistant",
+                        "mode": "build", "agent": "build",
+                        "path": {"cwd": dest_cwd, "root": dest_cwd}, "cost": 0,
+                        "tokens": {"total": 0, "input": 0, "output": 0,
+                                   "reasoning": 0, "cache": {"write": 0, "read": 0}},
+                        "modelID": model["modelID"], "providerID": model["providerID"],
+                        "time": {"created": created, "completed": created},
+                        "finish": "stop", "id": mid, "sessionID": sid}
+            messages.append({"info": info, "parts": parts})
+            prev_mid = mid
+
+        title = (session.extra.get("out", {}).get("opencode_title")
+                 or "Relocated session")
+        created = _ms(session.started_at)
+        last = _ms(getattr(session.records[-1], "ts", "")) if session.records else created
+        doc = {"info": {"id": sid, "slug": _slug(title), "directory": dest_cwd,
+                        "projectID": hashlib.sha1(dest_cwd.encode()).hexdigest()[:40],
+                        "title": title, "version": VERSION,
+                        "summary": {"additions": 0, "deletions": 0, "files": 0},
+                        "time": {"created": created, "updated": max(last, created)}},
+               "messages": messages}
+
+        dest = self.dest_path(session, dest_cwd)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(json.dumps(doc))
+        return dest
+
+
+def _slug(title: str) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
+    return s[:40] or "relocated"
+
+
+register(OpenCodeAdapter())

package/hconv/cli.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""hc: relocate a coding-agent session across harnesses.
+
+Escape hatch: your harness hit a wall (rate limit, outage) mid-task. Move the
+session to a live harness and keep going. Reads transcripts off disk; the source
+harness does NOT need to be running or your quota intact.
+
+    hc --from claude --to codex            # move latest Claude session here -> Codex
+    hc --from codex  --to claude <id>      # a specific session
+    hc --from claude --to codex --cwd DIR  # source/dest folder (default: pwd)
+    hc list --from codex                   # what's convertible for this cwd
+
+By default prints what it WOULD do; pass --write to actually create the file.
+"""
+import argparse
+import os
+import sys
+
+from hconv import convert, get, known
+
+
+def cmd_convert(a):
+    session, dest = convert(a.from_harness, a.to, a.cwd, a.dest_cwd or a.cwd,
+                            session_id=a.session_id, write=a.write)
+    n_tool = sum(1 for r in session.records if type(r).__name__ == "ToolCall")
+    print(f"from   : {a.from_harness}  ({session.session_id})")
+    print(f"to     : {a.to}")
+    print(f"cwd    : {a.dest_cwd or a.cwd}")
+    print(f"records: {len(session.records)}  ({n_tool} tool calls)")
+    print(f"dest   : {dest}")
+    if a.write:
+        sid, cwd = session.session_id, a.dest_cwd or a.cwd
+        resume = {"codex": f"codex resume {sid}",
+                  "claude": f"claude --resume {sid}",
+                  "opencode": f"opencode import {dest} && opencode -s {sid}"}[a.to]
+        print(f"\nWROTE. resume with:\n  cd {cwd} && {resume}")
+    else:
+        print("\n(dry run; pass --write to create it)")
+
+
+def cmd_list(a):
+    adapter = get(a.from_harness)
+    try:
+        p = adapter.locate(a.cwd)
+        print(f"latest {a.from_harness} session for {a.cwd}:\n  {p}")
+    except SystemExit as e:
+        print(e)
+
+
+def main():
+    ap = argparse.ArgumentParser(prog="hc", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd")
+
+    def add_common(p):
+        p.add_argument("--from", dest="from_harness", required=True,
+                       choices=known(), help="source harness")
+        p.add_argument("--cwd", default=os.getcwd(), help="source folder (default: pwd)")
+
+    c = sub.add_parser("convert", help="move a session to another harness")
+    add_common(c)
+    c.add_argument("--to", required=True, choices=known(), help="destination harness")
+    c.add_argument("session_id", nargs="?", help="session id (default: latest for cwd)")
+    c.add_argument("--dest-cwd", help="destination folder (default: same as --cwd)")
+    c.add_argument("--write", action="store_true", help="actually write the file")
+    c.set_defaults(func=cmd_convert)
+
+    l = sub.add_parser("list", help="show the latest convertible session for a cwd")
+    add_common(l)
+    l.set_defaults(func=cmd_list)
+
+    # bare `hc --from X --to Y` == `hc convert ...`
+    if len(sys.argv) > 1 and sys.argv[1] not in ("convert", "list", "-h", "--help"):
+        sys.argv.insert(1, "convert")
+
+    args = ap.parse_args()
+    if not getattr(args, "func", None):
+        ap.print_help(); sys.exit(1)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

package/hconv/common.py

@@ -0,0 +1,90 @@
+"""The common interface every harness must satisfy.
+
+A session is structural metadata + an ordered list of records. The four record
+kinds below are the universal floor: EVERY adapter reads its transcript into
+these and writes these back out, no exceptions. This is what guarantees that any
+harness pair converts at all.
+
+Anything richer than the four records (session titles, permission modes, model
+settings, ...) is deliberately NOT here. That surplus rides the N^2 enrichment
+map (see enrich.py) and is parked in Session.extra. The common interface never
+encodes the surplus; the surplus never re-encodes the common conversation.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class UserMessage:
+    """Something the human typed."""
+    text: str
+    ts: str = ""
+
+
+@dataclass
+class AssistantMessage:
+    """Agent's visible text reply (not its private reasoning, which is dropped)."""
+    text: str
+    ts: str = ""
+
+
+@dataclass
+class ToolCall:
+    """An agent tool invocation. `name`/`input` are the source harness's; adapters
+    translate to the destination's tool vocabulary on write."""
+    call_id: str
+    name: str
+    input: dict
+    ts: str = ""
+
+
+@dataclass
+class ToolResult:
+    """The output that came back for a ToolCall, paired by call_id."""
+    call_id: str
+    output: str
+    ts: str = ""
+    is_error: bool = False
+
+
+# The closed set of common records. A harness that needs more uses enrich.py.
+Record = UserMessage | AssistantMessage | ToolCall | ToolResult
+
+
+@dataclass
+class Session:
+    """Harness-neutral session: identity + the common record stream + a parking
+    lot for enrichment payloads.
+
+    Identity fields (id/cwd/branch/started_at) are structural: every adapter needs
+    them to materialize a transcript. They are not "features"; they're addressing.
+    """
+    harness: str                                  # source harness name, e.g. "claude"
+    session_id: str
+    cwd: str
+    records: list[Record] = field(default_factory=list)
+    git_branch: str = ""
+    started_at: str = ""                          # ISO timestamp of first record
+    extra: dict = field(default_factory=dict)     # surplus, populated by enrich.py
+
+
+def synthesize_missing_results(records: list[Record]) -> list[Record]:
+    """Close every open ToolCall.
+
+    Escape-hatch reality: the source harness usually died MID-TURN (rate limit hit
+    while a tool was running), so the last ToolCall often has no ToolResult. Every
+    destination needs the pairing closed or the resumed API call rejects the
+    history. Inject a synthetic error result immediately after each orphan.
+
+    This is the common case for this tool, not an edge case.
+    """
+    have = {r.call_id for r in records if isinstance(r, ToolResult)}
+    out: list[Record] = []
+    for r in records:
+        out.append(r)
+        if isinstance(r, ToolCall) and r.call_id not in have:
+            out.append(ToolResult(r.call_id,
+                                  "[no output; source session ended here]",
+                                  ts=r.ts, is_error=True))
+    return out

package/hconv/enrich.py

@@ -0,0 +1,81 @@
+"""N^2 enrichment map. Keyed by (source_harness, dest_harness).
+
+Carries ONLY the surplus fields the common interface drops, and only for pairs
+where both harnesses can represent the feature. An enricher reads what the source
+adapter stashed in Session.extra and translates it into a form the destination
+adapter's write() will pick up (also via Session.extra).
+
+By design this is optional and sparse: a missing (src, dst) entry just means
+"common-only conversion", which always works. The map never re-encodes the four
+common records, only the extras.
+
+Example (not yet wired): carry the session title both ways.
+
+    @register("claude", "codex")
+    def _(s: Session) -> None:
+        if "title" in s.extra:
+            s.extra["codex_thread_name"] = s.extra["title"]
+"""
+from __future__ import annotations
+
+from typing import Callable
+
+from .common import Session
+
+# Mutates Session.extra in place so the destination adapter's write() can consume.
+Enricher = Callable[[Session], None]
+
+_MAP: dict[tuple[str, str], Enricher] = {}
+
+
+def register(src: str, dst: str):
+    def deco(fn: Enricher) -> Enricher:
+        _MAP[(src, dst)] = fn
+        return fn
+    return deco
+
+
+def enrich(src: str, dst: str, session: Session) -> None:
+    fn = _MAP.get((src, dst))
+    if fn:
+        fn(session)
+
+
+# --- the surplus map -------------------------------------------------------
+# Both harnesses support a human-facing session title. The common interface
+# drops it; these carry it for the two pairs that can represent it. Writers
+# consume only Session.extra["out"], so a pair with no enricher stays common-only.
+
+@register("claude", "codex")
+def _claude_to_codex(s: Session) -> None:
+    if s.extra.get("title"):
+        s.extra.setdefault("out", {})["thread_name"] = s.extra["title"]
+
+
+@register("codex", "claude")
+def _codex_to_claude(s: Session) -> None:
+    if s.extra.get("title"):
+        s.extra.setdefault("out", {})["ai_title"] = s.extra["title"]
+
+
+# OpenCode carries the title as a first-class session column. Into opencode the
+# writer reads out["opencode_title"]; out of opencode we reuse the keys the
+# claude/codex writers already consume (ai_title / thread_name).
+
+@register("claude", "opencode")
+@register("codex", "opencode")
+def _to_opencode(s: Session) -> None:
+    if s.extra.get("title"):
+        s.extra.setdefault("out", {})["opencode_title"] = s.extra["title"]
+
+
+@register("opencode", "claude")
+def _opencode_to_claude(s: Session) -> None:
+    if s.extra.get("title"):
+        s.extra.setdefault("out", {})["ai_title"] = s.extra["title"]
+
+
+@register("opencode", "codex")
+def _opencode_to_codex(s: Session) -> None:
+    if s.extra.get("title"):
+        s.extra.setdefault("out", {})["thread_name"] = s.extra["title"]

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@theharshitsingh/hc",
+  "version": "0.2.0",
+  "description": "Relocate a coding-agent session across harnesses (Codex <-> Claude Code) and resume it natively.",
+  "license": "MIT",
+  "homepage": "https://hc.theharshitsingh.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harshitsinghbhandari/harness-convert.git"
+  },
+  "bugs": {
+    "url": "https://github.com/harshitsinghbhandari/harness-convert/issues"
+  },
+  "bin": {
+    "hc": "bin/hc.js"
+  },
+  "files": [
+    "bin/",
+    "hconv/",
+    "!hconv/**/__pycache__/**",
+    "!hconv/**/*.pyc",
+    "hc.py",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "codex",
+    "claude",
+    "claude-code",
+    "opencode",
+    "agents",
+    "cli",
+    "transcript",
+    "session",
+    "harness"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}