# codex-local-project-sync

**Repository Path**: yifeiyin/codex-local-project-sync

## Basic Information

- **Project Name**: codex-local-project-sync
- **Description**: macOS 本地工具：恢复切换 Codex 账号后消失的项目，并同步到已有账号状态。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-10
- **Last Updated**: 2026-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: codex, macOS, Python, Automation, developer-tools

## README

# Codex 本地项目同步

一个独立的 macOS 工具，用于恢复切换 ChatGPT/Codex 账号后从侧栏消失的本地项目登记。它根据本机 SQLite 数据库核对项目 ID、名称和路径，找回已有的项目，并将缺失的登记补到本机已有项目状态的账号中。

## 使用方法

需要 macOS、`/usr/bin/python3`（3.9 或更新）和受支持的 ChatGPT/Codex 桌面版。把 `codex-local-project-sync.command` 下载或克隆到本机。若下载的文件没有执行权限，在终端运行：

```sh
chmod +x codex-local-project-sync.command
```

双击脚本即可运行。应用仍打开时，按 **⌘Q** 完全退出并保持终端打开。等待终端提示「已写入并校验」，再打开应用。首次登录一个新账号或新增项目后，可再运行一次以补齐登记。

也可以在终端使用：

```sh
/usr/bin/python3 codex-local-project-sync.command --check
/usr/bin/python3 codex-local-project-sync.command --backup-dir "$HOME/Documents"
```

`--check` 只读预检，显示可恢复的项目和账号状态数量。`--backup-dir` 可以指定一个已存在的绝对路径，目录必须属于当前用户，并且不能通过符号链接访问或由其他用户写入。

## 数据范围和兼容性

- 恢复本地项目登记，以及新增登记对应的本地排序和置顶。已有项目、聊天、云端项目和账号认证各自保留。
- 脚本跳过数据库无法核验或有身份冲突的项目。已登记但目录当前不可用的项目会保留登记，源码文件需从原目录访问。
- 写入前仅备份会修改的项目字段，默认存放在 `~/Library/Application Support/Codex Local Project Sync/backups`。备份含本地路径和账号状态标识，请留在本机。
- 采用本地离线读写，无第三方依赖。写入已验证的应用版本是 `26.1103.41825`（build `25679`）和 `26.1103.60933`（build `25894`）。其他版本可用 `--check`；升级后的写入需要重新验证存储结构。
- 该项目是独立的社区工具。ChatGPT 和 Codex 是 OpenAI 的产品。

## 运行测试

```sh
/usr/bin/python3 -B -W error::ResourceWarning -m unittest discover -v
```

测试使用临时 JSON 和 SQLite 数据库。

## 许可证

[MIT](LICENSE)