panagent 0.3.0__tar.gz

panagent-0.3.0/LICENSE

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

panagent-0.3.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: panagent
+Version: 0.3.0
+Summary: Move AI conversations between Claude Code, Codex, ChatGPT, Claude and tavya, and resume them natively
+Author: Abhimanyu Pallavi Sudhir
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/abhimanyupallavisudhir/panagent
+Project-URL: Source, https://github.com/abhimanyupallavisudhir/panagent
+Project-URL: Issues, https://github.com/abhimanyupallavisudhir/panagent/issues
+Project-URL: Changelog, https://github.com/abhimanyupallavisudhir/panagent/blob/master/CHANGELOG.md
+Keywords: agents,claude-code,codex,chatgpt,claude,tavya,conversation,transcript,export
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: browser
+Requires-Dist: playwright>=1.50; extra == "browser"
+Dynamic: license-file
+
+# panagent
+
+**Take an AI conversation anywhere.** Turn a ChatGPT, Claude or tavya share link, a ChatGPT or Claude data export, or a Claude Code or Codex session into a session that Claude Code or Codex can resume. One command does it:
+
+```console
+$ panagent convert https://chatgpt.com/share/6a781aea-… --to claude --install
+cd /home/me/project && claude --resume 0b6d1c1e-5f0e-4d43-9a8e-2f8f5e0c7a11
+```
+
+panagent converts through a small provider-neutral format. It keeps source provenance and tool-call IDs where the source has them. When something cannot be carried across, panagent reports it instead of pretending the conversion is exact. It has no dependencies beyond the Python standard library.
+
+| From ↓ / to → | Claude Code | Codex | Neutral JSON | Markdown |
+| --- | :---: | :---: | :---: | :---: |
+| Claude Code session (`~/.claude/projects/…/*.jsonl`) | ✓ | ✓ | ✓ | ✓ |
+| Codex session (`~/.codex/sessions/…/rollout-*.jsonl`) | ✓ | ✓ | ✓ | ✓ |
+| ChatGPT share link or data export (`conversations.json`) | ✓ | ✓ | ✓ | ✓ |
+| Claude share link or data export (`conversations.json`) | ✓ | ✓ | ✓ | ✓ |
+| tavya share link (`tavya.io/share/conversations/…`, or any karmax server) | ✓ | ✓ | ✓ | ✓ |
+
+## Install
+
+```bash
+pipx install panagent        # or: uv tool install panagent, or: pip install panagent
+```
+
+Python 3.10 or later is required. ChatGPT and tavya links need nothing else. Claude share pages sometimes need a real browser (see [Claude share links](#claude-share-links)):
+
+```bash
+pipx install 'panagent[browser]' && playwright install chromium
+```
+
+## Use
+
+### Continue a conversation in Claude Code or Codex
+
+`--install` writes the converted session into the CLI's own history and prints the command that resumes it:
+
+```bash
+panagent convert 'https://claude.ai/share/…' --to claude --install      # resume in Claude Code
+panagent convert 'https://tavya.io/share/conversations/…' --to codex --install
+panagent convert ~/.claude/projects/-home-me-app/1f0c….jsonl --to codex --install
+```
+
+Claude Code keeps sessions per project directory. `--install` uses the current directory; pass `--cwd DIR` to choose another one. Each install creates a new session ID, and an existing session file is never overwritten. `$CLAUDE_CONFIG_DIR` and `$CODEX_HOME` are honored.
+
+### Convert to a file
+
+The source format is detected from the URL or the file's contents. Output goes to stdout unless you pass `-o`.
+
+```bash
+panagent convert codex-session.jsonl --to claude-code -o claude-session.jsonl
+panagent convert 'https://chatgpt.com/share/…' --to markdown -o chat.md
+panagent convert session.jsonl --to ir -o conversation.agent.json        # neutral JSON
+```
+
+### Data exports
+
+ChatGPT (*Settings → Data controls → Export*) and Claude (*Settings → Privacy → Export data*) both email you a `conversations.json` with every conversation. List the conversations, then pick one by ID or exact title:
+
+```bash
+panagent list conversations.json
+panagent convert conversations.json --conversation 'Plot the data' --to claude --install
+```
+
+Claude exports keep text extracted from uploaded files, so attachments are carried across as text. ChatGPT exports refer to images that the export does not contain; these become named attachment placeholders.
+
+### From Python
+
+```python
+import panagent
+
+conversation = panagent.load("https://tavya.io/share/conversations/…")    # or a path
+print(panagent.render(conversation, "markdown").text)
+session = panagent.install(conversation, "codex")
+print(session.command)                                                    # codex resume …
+```
+
+`panagent.parse(text)` reads a string you already have. Each function raises a `panagent.PanagentError` with an actionable message. Library calls never start a browser unless you pass `browser="auto"`, `"headed"` or `"headless"`.
+
+## How web chats arrive
+
+A web chat was never an agent session. It has no tool state, sandbox or hidden instructions to resume. By default (`--mode auto`), Claude Code and Codex therefore receive a share or an export as **one guarded context message**. That message says the imported text is prior discussion and does not override the agent's current instructions. Agent sessions keep their turn-by-turn structure, including tool calls and results.
+
+Pass `--mode transcript` to rebuild a web chat turn by turn, or `--mode context` to flatten an agent session. Markdown and neutral JSON always keep every message.
+
+## Provenance and warnings
+
+The neutral format ([reference](https://github.com/abhimanyupallavisudhir/panagent/blob/master/docs/ir.md)) records:
+
+- where the conversation came from: format, provider, source kind, URL or file name, conversation ID and acquisition time;
+- the source ID and record index of every message;
+- ordered, typed blocks: text, code, visible reasoning, tool calls and results, images and attachments;
+- what the source could represent and what it could not;
+- warnings with stable codes.
+
+Generated Claude Code and Codex files embed the same provenance under a `panagent` field, so a session converted twice still remembers its original source. Warnings go to stderr. `--report FILE` writes them as JSON, and `--fail-on-warning` exits with status 3 for strict automation. Use `panagent validate FILE` to check that a file parses without converting it.
+
+## Claude share links
+
+Claude share pages may show a Cloudflare challenge, or an app shell that only renders in a browser. panagent never treats either one as an empty conversation. Plain HTTPS is tried first. With the `browser` extra, `--browser auto` falls back to a Chrome window where you complete the challenge yourself. Two alternatives:
+
+- `--browser headed` opens a browser window straight away;
+- `--cdp-url http://127.0.0.1:9222` reuses a Chrome you already have open.
+
+Non-interactive runs fail with the command to run instead of hanging, and `--browser never` forbids the fallback. panagent never asks for cookies or tokens and never automates a challenge. If browser extraction stops recognizing Claude's page, the [manual export recipe](https://github.com/abhimanyupallavisudhir/panagent/blob/master/docs/browser-export.md) still works.
+
+## Limits
+
+The native Claude Code and Codex formats are undocumented and change over time. Opt-in compatibility tests check the output against the real CLIs (see [Development](#development)): Codex must read and resume a session written by `--install`, and Claude Code must resume one and send its history to a local stand-in for the API, so the test spends nothing. Provider-only state cannot be recreated: sandboxes, approvals, file snapshots, encrypted reasoning, token accounting and compaction state.
+
+panagent converts conversations only. It does not migrate credentials, MCP servers, hooks, plugins, repositories or running processes, and it does not bypass access controls. Anything it cannot carry over is reported as a warning.
+
+## Development
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v
+```
+
+The fixtures are redacted, synthetic copies of each source format. The tavya fixture is the output of tavya's own share renderer. Optional suites:
+
+```bash
+PANAGENT_LIVE_TESTS=1 PYTHONPATH=src python -m unittest tests.test_live_samples -v         # public sample links
+PANAGENT_NATIVE_TESTS=1 PYTHONPATH=src python -m unittest tests.test_native_cli -v         # installed codex
+PANAGENT_CLAUDE_TESTS=1 PANAGENT_CLAUDE_COMMAND=claude \
+  PYTHONPATH=src python -m unittest tests.test_native_cli.ClaudeNativeCompatibilityTests -v
+```
+
+When a sibling `../karmax` checkout has its dependencies installed, the default suite also runs the Codex release that checkout pins. Point `PANAGENT_PINNED_CODEX` at another binary to use that one instead.
+
+To make a release, bump `__version__` in `src/panagent/__init__.py` and add a `CHANGELOG.md` entry. Merging that to master is the release. GitHub Actions tests and builds it, publishes it to PyPI through trusted publishing (no token is stored), and tags it with a GitHub release.
+
+## License
+
+MIT

panagent-0.3.0/README.md

@@ -0,0 +1,134 @@
+# panagent
+
+**Take an AI conversation anywhere.** Turn a ChatGPT, Claude or tavya share link, a ChatGPT or Claude data export, or a Claude Code or Codex session into a session that Claude Code or Codex can resume. One command does it:
+
+```console
+$ panagent convert https://chatgpt.com/share/6a781aea-… --to claude --install
+cd /home/me/project && claude --resume 0b6d1c1e-5f0e-4d43-9a8e-2f8f5e0c7a11
+```
+
+panagent converts through a small provider-neutral format. It keeps source provenance and tool-call IDs where the source has them. When something cannot be carried across, panagent reports it instead of pretending the conversion is exact. It has no dependencies beyond the Python standard library.
+
+| From ↓ / to → | Claude Code | Codex | Neutral JSON | Markdown |
+| --- | :---: | :---: | :---: | :---: |
+| Claude Code session (`~/.claude/projects/…/*.jsonl`) | ✓ | ✓ | ✓ | ✓ |
+| Codex session (`~/.codex/sessions/…/rollout-*.jsonl`) | ✓ | ✓ | ✓ | ✓ |
+| ChatGPT share link or data export (`conversations.json`) | ✓ | ✓ | ✓ | ✓ |
+| Claude share link or data export (`conversations.json`) | ✓ | ✓ | ✓ | ✓ |
+| tavya share link (`tavya.io/share/conversations/…`, or any karmax server) | ✓ | ✓ | ✓ | ✓ |
+
+## Install
+
+```bash
+pipx install panagent        # or: uv tool install panagent, or: pip install panagent
+```
+
+Python 3.10 or later is required. ChatGPT and tavya links need nothing else. Claude share pages sometimes need a real browser (see [Claude share links](#claude-share-links)):
+
+```bash
+pipx install 'panagent[browser]' && playwright install chromium
+```
+
+## Use
+
+### Continue a conversation in Claude Code or Codex
+
+`--install` writes the converted session into the CLI's own history and prints the command that resumes it:
+
+```bash
+panagent convert 'https://claude.ai/share/…' --to claude --install      # resume in Claude Code
+panagent convert 'https://tavya.io/share/conversations/…' --to codex --install
+panagent convert ~/.claude/projects/-home-me-app/1f0c….jsonl --to codex --install
+```
+
+Claude Code keeps sessions per project directory. `--install` uses the current directory; pass `--cwd DIR` to choose another one. Each install creates a new session ID, and an existing session file is never overwritten. `$CLAUDE_CONFIG_DIR` and `$CODEX_HOME` are honored.
+
+### Convert to a file
+
+The source format is detected from the URL or the file's contents. Output goes to stdout unless you pass `-o`.
+
+```bash
+panagent convert codex-session.jsonl --to claude-code -o claude-session.jsonl
+panagent convert 'https://chatgpt.com/share/…' --to markdown -o chat.md
+panagent convert session.jsonl --to ir -o conversation.agent.json        # neutral JSON
+```
+
+### Data exports
+
+ChatGPT (*Settings → Data controls → Export*) and Claude (*Settings → Privacy → Export data*) both email you a `conversations.json` with every conversation. List the conversations, then pick one by ID or exact title:
+
+```bash
+panagent list conversations.json
+panagent convert conversations.json --conversation 'Plot the data' --to claude --install
+```
+
+Claude exports keep text extracted from uploaded files, so attachments are carried across as text. ChatGPT exports refer to images that the export does not contain; these become named attachment placeholders.
+
+### From Python
+
+```python
+import panagent
+
+conversation = panagent.load("https://tavya.io/share/conversations/…")    # or a path
+print(panagent.render(conversation, "markdown").text)
+session = panagent.install(conversation, "codex")
+print(session.command)                                                    # codex resume …
+```
+
+`panagent.parse(text)` reads a string you already have. Each function raises a `panagent.PanagentError` with an actionable message. Library calls never start a browser unless you pass `browser="auto"`, `"headed"` or `"headless"`.
+
+## How web chats arrive
+
+A web chat was never an agent session. It has no tool state, sandbox or hidden instructions to resume. By default (`--mode auto`), Claude Code and Codex therefore receive a share or an export as **one guarded context message**. That message says the imported text is prior discussion and does not override the agent's current instructions. Agent sessions keep their turn-by-turn structure, including tool calls and results.
+
+Pass `--mode transcript` to rebuild a web chat turn by turn, or `--mode context` to flatten an agent session. Markdown and neutral JSON always keep every message.
+
+## Provenance and warnings
+
+The neutral format ([reference](https://github.com/abhimanyupallavisudhir/panagent/blob/master/docs/ir.md)) records:
+
+- where the conversation came from: format, provider, source kind, URL or file name, conversation ID and acquisition time;
+- the source ID and record index of every message;
+- ordered, typed blocks: text, code, visible reasoning, tool calls and results, images and attachments;
+- what the source could represent and what it could not;
+- warnings with stable codes.
+
+Generated Claude Code and Codex files embed the same provenance under a `panagent` field, so a session converted twice still remembers its original source. Warnings go to stderr. `--report FILE` writes them as JSON, and `--fail-on-warning` exits with status 3 for strict automation. Use `panagent validate FILE` to check that a file parses without converting it.
+
+## Claude share links
+
+Claude share pages may show a Cloudflare challenge, or an app shell that only renders in a browser. panagent never treats either one as an empty conversation. Plain HTTPS is tried first. With the `browser` extra, `--browser auto` falls back to a Chrome window where you complete the challenge yourself. Two alternatives:
+
+- `--browser headed` opens a browser window straight away;
+- `--cdp-url http://127.0.0.1:9222` reuses a Chrome you already have open.
+
+Non-interactive runs fail with the command to run instead of hanging, and `--browser never` forbids the fallback. panagent never asks for cookies or tokens and never automates a challenge. If browser extraction stops recognizing Claude's page, the [manual export recipe](https://github.com/abhimanyupallavisudhir/panagent/blob/master/docs/browser-export.md) still works.
+
+## Limits
+
+The native Claude Code and Codex formats are undocumented and change over time. Opt-in compatibility tests check the output against the real CLIs (see [Development](#development)): Codex must read and resume a session written by `--install`, and Claude Code must resume one and send its history to a local stand-in for the API, so the test spends nothing. Provider-only state cannot be recreated: sandboxes, approvals, file snapshots, encrypted reasoning, token accounting and compaction state.
+
+panagent converts conversations only. It does not migrate credentials, MCP servers, hooks, plugins, repositories or running processes, and it does not bypass access controls. Anything it cannot carry over is reported as a warning.
+
+## Development
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v
+```
+
+The fixtures are redacted, synthetic copies of each source format. The tavya fixture is the output of tavya's own share renderer. Optional suites:
+
+```bash
+PANAGENT_LIVE_TESTS=1 PYTHONPATH=src python -m unittest tests.test_live_samples -v         # public sample links
+PANAGENT_NATIVE_TESTS=1 PYTHONPATH=src python -m unittest tests.test_native_cli -v         # installed codex
+PANAGENT_CLAUDE_TESTS=1 PANAGENT_CLAUDE_COMMAND=claude \
+  PYTHONPATH=src python -m unittest tests.test_native_cli.ClaudeNativeCompatibilityTests -v
+```
+
+When a sibling `../karmax` checkout has its dependencies installed, the default suite also runs the Codex release that checkout pins. Point `PANAGENT_PINNED_CODEX` at another binary to use that one instead.
+
+To make a release, bump `__version__` in `src/panagent/__init__.py` and add a `CHANGELOG.md` entry. Merging that to master is the release. GitHub Actions tests and builds it, publishes it to PyPI through trusted publishing (no token is stored), and tags it with a GitHub release.
+
+## License
+
+MIT

panagent-0.3.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "panagent"
+dynamic = ["version"]
+description = "Move AI conversations between Claude Code, Codex, ChatGPT, Claude and tavya, and resume them natively"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Abhimanyu Pallavi Sudhir" }]
+keywords = ["agents", "claude-code", "codex", "chatgpt", "claude", "tavya", "conversation", "transcript", "export"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Communications :: Chat",
+  "Topic :: Software Development",
+  "Topic :: Utilities",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+browser = ["playwright>=1.50"]
+
+[project.urls]
+Homepage = "https://github.com/abhimanyupallavisudhir/panagent"
+Source = "https://github.com/abhimanyupallavisudhir/panagent"
+Issues = "https://github.com/abhimanyupallavisudhir/panagent/issues"
+Changelog = "https://github.com/abhimanyupallavisudhir/panagent/blob/master/CHANGELOG.md"
+
+[project.scripts]
+panagent = "panagent.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+panagent = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = {attr = "panagent.__version__"}

panagent-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

panagent-0.3.0/src/panagent/__init__.py

@@ -0,0 +1,30 @@
+"""Move agent conversations between Claude Code, Codex, ChatGPT, Claude and tavya.
+
+    import panagent
+    conversation = panagent.load("https://chatgpt.com/share/...")
+    print(panagent.render(conversation, "markdown").text)
+    panagent.install(conversation, "claude-code").command  # 'cd ... && claude --resume ...'
+"""
+
+__version__ = "0.3.0"
+
+from .api import Installed, install, load, parse, render
+from .errors import AcquisitionError, BrowserRequired, FormatError, PanagentError
+from .model import SCHEMA, new_conversation, validate_conversation
+from .writers import Rendered
+
+__all__ = [
+    "SCHEMA",
+    "AcquisitionError",
+    "BrowserRequired",
+    "FormatError",
+    "Installed",
+    "PanagentError",
+    "Rendered",
+    "install",
+    "load",
+    "new_conversation",
+    "parse",
+    "render",
+    "validate_conversation",
+]

panagent-0.3.0/src/panagent/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

panagent-0.3.0/src/panagent/api.py

@@ -0,0 +1,171 @@
+"""The library interface: load any supported source, render or install it as any target."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from shlex import quote
+from typing import Any
+from uuid import uuid4
+
+from .browser import fetch_share_browser
+from .detect import canonical_format, detect_text, url_format
+from .errors import AcquisitionError, BrowserRequired, PanagentError
+from .model import default_mode, validate_conversation
+from .readers import READERS, read_file
+from .web import WEB_READERS, fetch_share
+from .writers import WRITERS, Rendered
+
+# Shares whose pages may need a real browser (a challenge or a client-rendered app).
+BROWSER_FORMATS = {"chatgpt-share", "claude-share"}
+NATIVE_TARGETS = {"claude-code", "codex"}
+
+
+def parse(
+    text: str,
+    source_format: str | None = None,
+    *,
+    source_uri: str | None = None,
+    conversation: str | None = None,
+) -> dict[str, Any]:
+    """Read a conversation from text in any supported input format (detected when omitted)."""
+    fmt = canonical_format(source_format) if source_format else detect_text(text)
+    reader = READERS.get(fmt) or WEB_READERS.get(fmt)
+    if reader is None:
+        raise PanagentError(f"{fmt} is output-only")
+    return validate_conversation(reader(text, source_uri=source_uri, conversation=conversation))
+
+
+def load(
+    source: str | os.PathLike[str],
+    source_format: str | None = None,
+    *,
+    conversation: str | None = None,
+    timeout: float = 30.0,
+    browser: str = "never",
+    browser_timeout: float = 120.0,
+    cdp_url: str | None = None,
+    browser_profile: str | None = None,
+) -> dict[str, Any]:
+    """Read a conversation from a file or a public share URL.
+
+    browser is "never" (the library default), "auto", "headless" or "headed";
+    it only applies to ChatGPT and Claude shares that plain HTTPS cannot read.
+    """
+    source = os.fspath(source)
+    share = url_format(source) if "://" in source else None
+    if not share:
+        return parse(read_file(Path(source)), source_format, source_uri=source, conversation=conversation)
+    fmt = canonical_format(source_format) if source_format else share
+    if fmt != share:
+        raise PanagentError(f"URL does not match source format {fmt}")
+    reader = WEB_READERS[fmt]
+
+    def through_browser() -> dict[str, Any]:
+        text = fetch_share_browser(source, timeout=browser_timeout, mode=browser, cdp_url=cdp_url, profile=browser_profile)
+        return validate_conversation(reader(text, source_uri=source))
+
+    if fmt in BROWSER_FORMATS and (browser in {"headless", "headed"} or cdp_url):
+        return through_browser()
+    try:
+        return validate_conversation(reader(fetch_share(source, timeout=timeout), source_uri=source))
+    except AcquisitionError as exc:
+        retryable = isinstance(exc, BrowserRequired) or exc.status in {403, 429}
+        if fmt not in BROWSER_FORMATS or browser == "never" or not retryable:
+            raise
+        return through_browser()
+
+
+def render(
+    conv: dict[str, Any],
+    target: str,
+    *,
+    mode: str = "auto",
+    cwd: str | None = None,
+    session_id: str | None = None,
+) -> Rendered:
+    """Write a conversation as target ("ir", "markdown", "claude-code" or "codex").
+
+    mode "auto" gives native targets a guarded context message for web snapshots
+    and a turn-by-turn transcript for agent sessions; IR and Markdown ignore it.
+    """
+    fmt = canonical_format(target)
+    writer = WRITERS.get(fmt)
+    if writer is None:
+        raise PanagentError(f"{fmt} is input-only")
+    validate_conversation(conv)
+    if mode == "auto":
+        mode = default_mode(conv) if fmt in NATIVE_TARGETS else "transcript"
+    if mode not in {"context", "transcript"}:
+        raise PanagentError(f"unknown mode: {mode}")
+    rendered = writer(conv, mode=mode, cwd=cwd, session_id=session_id)
+    rendered.format, rendered.mode = fmt, mode
+    return rendered
+
+
+@dataclass
+class Installed:
+    path: Path
+    session_id: str
+    command: str
+    rendered: Rendered
+
+
+def install(
+    conv: dict[str, Any],
+    target: str,
+    *,
+    cwd: str | os.PathLike[str] | None = None,
+    session_id: str | None = None,
+    mode: str = "auto",
+    home: str | os.PathLike[str] | None = None,
+) -> Installed:
+    """Add a conversation to Claude Code's or Codex's own history as a new session.
+
+    Claude Code finds sessions per project, so cwd (default: the current
+    directory) is where `claude --resume` must run. home overrides the CLI's
+    data directory ($CLAUDE_CONFIG_DIR or ~/.claude; $CODEX_HOME or ~/.codex).
+    An existing session file is never overwritten.
+    """
+    fmt = canonical_format(target)
+    if fmt not in NATIVE_TARGETS:
+        raise PanagentError("only claude-code and codex sessions can be installed")
+    directory = str(Path(cwd or os.getcwd()).expanduser().resolve())
+    # The installed copy is a new session of the target CLI, never the source's identity.
+    session_id = session_id or str(uuid4())
+    rendered = render(conv, fmt, mode=mode, cwd=directory, session_id=session_id)
+    if fmt == "claude-code":
+        root = Path(home or os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude").expanduser()
+        path = root / "projects" / re.sub(r"[^A-Za-z0-9]", "-", directory) / f"{session_id}.jsonl"
+        command = f"cd {quote(directory)} && claude --resume {session_id}"
+    else:
+        root = Path(home or os.environ.get("CODEX_HOME") or Path.home() / ".codex").expanduser()
+        started = _utc(rendered.text.split("\n", 1)[0])
+        path = (root / "sessions" / started.strftime("%Y/%m/%d")
+                / f"rollout-{started.strftime('%Y-%m-%dT%H-%M-%S')}-{session_id}.jsonl")
+        command = f"codex resume {session_id}"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError as exc:
+        raise PanagentError(f"session {session_id} already exists at {path}") from exc
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as handle:
+            handle.write(rendered.text)
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+    return Installed(path, session_id, command, rendered)
+
+
+def _utc(first_record: str) -> datetime:
+    """The session start of a Codex rollout (from its session_meta record), else now."""
+    try:
+        value = json.loads(first_record)["timestamp"]
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
+    except (ValueError, KeyError, TypeError, AttributeError):
+        return datetime.now(timezone.utc)