Metadata-Version: 2.4
Name: coding-agent-session-manager
Version: 0.1.0
Summary: Move visible conversation history between local AI coding agents.
Author: session-manager contributors
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/yhf98/agent-session-manager
Project-URL: Repository, https://github.com/yhf98/agent-session-manager
Project-URL: Issues, https://github.com/yhf98/agent-session-manager/issues
Keywords: agent,chat-history,session-migration,codex,claude,opencode
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: gui
Requires-Dist: PyQt-Fluent-Widgets[full]; extra == "gui"
Dynamic: license-file

# Session Manager

[![Build and Release](https://github.com/yhf98/agent-session-manager/actions/workflows/release.yml/badge.svg)](https://github.com/yhf98/agent-session-manager/actions/workflows/release.yml)
[![PyPI](https://img.shields.io/pypi/v/coding-agent-session-manager)](https://pypi.org/project/coding-agent-session-manager/)

在本机的 Codex、Claude Code、OpenCode 之间迁移可见对话历史。适配器把来源会话解析成统一的 user/assistant 消息序列，再生成目标工具能读取的会话格式，因此三个工具之间的六种转换方向都可用同一套命令。

## 支持范围

| 工具 | 读取 | 写入 |
|---|---|---|
| Codex | 本地 rollout JSONL | Codex rollout JSONL；更新 `session_index.jsonl`，存在兼容的 `state_5.sqlite` 时注册桌面历史 |
| Claude Code | `~/.claude/projects` 下的会话 JSONL | 写入目标项目的会话 JSONL，可用 `claude --resume <id>` 恢复 |
| OpenCode | 只读读取本地 SQLite 数据库 | 调用 OpenCode 官方 `import` 命令写入原生会话库；CLI 不可用或数据目录不匹配时保留导出 JSON 和导入命令 |

默认迁移用户/助手可见文本、消息顺序、时间、标题和工作目录。内部 thinking、工具调用与工具结果、审批/沙箱状态和多媒体附件不跨工具伪装成目标端原生记录。

## 平台和默认目录

支持 macOS、Windows、Linux。可以自动发现默认目录，也可以通过 `--source-home`、`--target-home` 或对应环境变量指定其他位置。

| 工具 | macOS | Windows | Linux |
|---|---|---|---|
| Codex | `~/.codex` | `%USERPROFILE%\.codex` | `~/.codex` |
| Claude Code | `~/.claude` | `%USERPROFILE%\.claude` | `~/.claude` |
| OpenCode | `$XDG_DATA_HOME/opencode`，默认 `~/.local/share/opencode` | `%APPDATA%\opencode` | `$XDG_DATA_HOME/opencode`，默认 `~/.local/share/opencode` |

可用环境变量：Codex `CODEX_HOME`、Claude `CLAUDE_CONFIG_DIR`；OpenCode 在 macOS/Linux 遵循 `XDG_DATA_HOME`。`OPENCODE_GLOBAL_DATA_DIR` 可覆盖 Session Manager 的 OpenCode 数据目录；导入时会核对 OpenCode CLI 实际使用的数据库，避免导入到另一个数据目录。

## 安装

需要 Python 3.11 或更高版本。命令行只使用 Python 标准库；桌面界面使用 PyQt-Fluent-Widgets。

PyPI 包名是 `coding-agent-session-manager`，安装后的命令为 `session-manager`：

```bash
# CLI
python -m pip install coding-agent-session-manager

# CLI + 桌面 GUI
python -m pip install "coding-agent-session-manager[gui]"
```

从源码开发时使用可编辑安装：

```bash
python -m pip install -e .
```

安装桌面 GUI 依赖：

```bash
python -m pip install -e ".[gui]"
```

也可以不安装，直接从项目目录运行：

```bash
python -m coding_agent_session_manager --help
```

## 桌面 GUI

```bash
session-manager gui
```

GUI 可以浏览来源会话、查看 user/assistant 消息、用 Ctrl/Shift 多选会话并选择目标 Agent。迁移可以直接执行；“预览迁移”是可选的。批量直迁会逐条加载和写入，不会先把整批对话全部读入内存。GUI 也支持备份选中会话或当前来源工具的全部会话。OpenCode 目标会自动调用官方导入命令并注册到原项目；无法自动导入时会提供命令。GUI 默认使用 macOS、Windows、Linux 的工具数据目录；也可通过 `--codex-home`、`--claude-home`、`--opencode-home` 覆盖。

## 使用

```bash
# 列出所有工具最近的会话
session-manager list all

# 列出某个工具的会话（JSON 输出）
session-manager list codex --json

# 先预览转换计划；默认不会写入
session-manager convert codex claude <codex-session-id>

# 确认后执行
session-manager convert codex claude <codex-session-id> --write

# 批量预览 / 批量执行（执行时逐条迁移）
session-manager convert codex claude <session-id-1> <session-id-2>
session-manager convert codex claude <session-id-1> <session-id-2> --write

# 其他方向
session-manager convert claude codex <claude-session-id> --write
session-manager convert opencode claude <opencode-session-id> --write
session-manager convert claude opencode <claude-session-id> --write

# 备份一条会话 / 某个工具的全部会话
session-manager backup codex <codex-session-id> --output ~/SessionBackups
session-manager backup opencode --all --output ~/SessionBackups
```

GUI 不需要先点预览才能迁移。CLI 也不需要预先单独运行一次预览命令；需要直接执行时，在同一条命令加 `--write`。批量执行逐条读取和写入，并汇报每条的写入、跳过或错误状态。

OpenCode 目标会生成标准导入文件并尝试自动导入。CLI 找不到或使用的数据目录与 Session Manager 不一致时，会输出导入命令：

```bash
opencode import "<生成的 JSON 文件路径>"
```

OpenCode 来源数据库始终只读；导入目标时由 OpenCode 官方 CLI 写入其原生数据库，并按会话原工作目录注册。

### 自定义数据目录

```bash
session-manager list claude --home "/custom/claude-config"
session-manager convert opencode codex <session-id> \
  --source-home "/custom/opencode/opencode.db" \
  --target-home "/custom/codex" \
  --write
```

`--source-home` / `--target-home` 指向工具数据目录；读取 OpenCode 时也可以直接把 `--source-home` 指向数据库文件。`--output <path>` 可把生成结果写到指定路径。

## 备份

GUI 支持备份选中的会话或当前来源工具的全部会话。命令行示例：

```bash
session-manager backup claude <session-id>
session-manager backup codex --all --output ~/SessionBackups
```

每次备份都会创建带时间戳的新目录和 `manifest.json`。Codex、Claude Code 备份原生 JSONL 文件；OpenCode 备份该会话关联的 SQLite 原始行（含消息与 parts），并保持来源数据库只读。

### 冲突策略

默认 `--on-conflict skip`：相同来源重复迁移时使用稳定目标 ID，若目标已存在就跳过。也可以显式指定：

```bash
--on-conflict overwrite   # 覆盖同 ID 的目标会话
--on-conflict fork        # 生成新的目标会话 ID
```

## 开发和测试

```bash
python -m unittest discover -s tests -v
```

适配器遵循 `AgentAdapter` 接口。新增工具时实现会话发现、加载、目标格式计划、冲突检测和写入，再注册到 `coding_agent_session_manager/registry.py`，即可接入统一转换流程。

## GitHub Actions 构建与发布

`.github/workflows/release.yml` 在推送到 `main` 时运行测试、构建四个平台安装包，并发布一个按 commit SHA 命名的 GitHub 预发布版；PR 只运行测试和构建，不发布 Release。

推送与 `pyproject.toml` 版本一致的标签（例如 `v0.1.0`）时，工作流会发布正式 GitHub Release 和 PyPI wheel/sdist：

```bash
git tag v0.1.0
git push origin v0.1.0
```

平台资产包括 Windows x86_64 ZIP、macOS Intel 与 Apple Silicon `.app` ZIP、Linux x86_64 tar.gz，以及 `SHA256SUMS`。macOS/Windows 构建目前未做代码签名/公证，首次打开时系统可能显示安全提示。

下载后：Windows 解压运行 `SessionManager.exe`；macOS 解压并打开 `SessionManager.app`；Linux 解压后运行 `SessionManager/SessionManager`。

PyPI 通过 GitHub OIDC Trusted Publishing 发布。首次发布前，在 PyPI 账户的 Publishing 设置添加 pending publisher：distribution `coding-agent-session-manager`、owner `yhf98`、repository `agent-session-manager`、workflow `release.yml`（environment 留空）；如果项目已存在，则在项目 Publishing 设置中添加。工作流已配置 `id-token: write`，不需要保存 PyPI API token。

macOS、Windows、Linux 的桌面包会作为 [GitHub Release Assets](https://github.com/yhf98/agent-session-manager/releases) 发布；Python/CLI 用户可安装 `coding-agent-session-manager`，桌面 GUI 可安装 `[gui]` extra。

## License

Session Manager 按 [GNU GPL v3.0 only](LICENSE) 发布，与 PyQt-Fluent-Widgets 的 GPLv3 许可保持一致。
