📦
Usync
sync claudecode opencode codex gemini-cli settings skills
0 installs
Trust: 34 — Low
Blockchain
Ask AI about Usync
Powered by Claude · Grounded in docs
I know everything about Usync. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Loading tools...
Reviews
Documentation
usync
同步 Claude / OpenCode / Codex / Gemini / Kiro / Qoder / Cursor 的配置与 skills 到 GitHub Gist。
功能
- 同步多工具配置到同一个 Gist。
- 增量上传:只上传变化文件,不全量覆盖。
- 支持下载恢复到真实路径,或下载到指定测试目录。
- CLI 显示进度、上传列表、下载列表、跳过列表。
- 内置
init:验证 PAT,或通过 GitHub OAuth 设备验证码登录并校验/创建 Gist。 - 默认过滤明显敏感文件(
.env*、.pem、.key、.p12)和系统噪音(.DS_Store)。 - 支持可选自动同步:
upload --watch轮询本地变化并增量上传。 - 跨工具迁移:自动格式转换、冲突处理、
mcp-remote桥接检测。
自动发现路径
- Claude:
~/.claude.json(全局 MCP)、~/.claude/settings.json、~/.claude/skills,以及项目内.mcp.json、.claude/* - OpenCode:
~/.config/opencode/opencode.json(.jsonc)、~/.config/opencode/skill,以及项目内opencode.json(.jsonc)、.opencode/skill - Codex:
~/.codex/config.toml、~/.codex/skills,以及项目内.codex/* - Gemini:
~/.gemini/settings.json、~/.gemini/extensions、~/.gemini/skills,以及项目内.gemini/* - Kiro:
~/.kiro/settings/mcp.json、~/.kiro/skills,以及项目内.kiro/settings/mcp.json、.kiro/steering - Qoder:
~/.qoder/mcp.json、~/.qoder/skills,以及项目内.qoder/mcp.json、.qoder/skills - Cursor:
~/.cursor/mcp.json、~/.cursor/rules,以及项目内.cursor/mcp.json、.cursor/rules
安装与构建
npm install
npm run build
Token / OAuth / Gist 准备
- 创建 PAT:https://github.com/settings/tokens/new
- 最低权限:
gist - 也可以使用 GitHub OAuth 设备验证码流程:
init --oauth会打开 GitHub 设备授权页面并显示验证码。- 官方 release 构建会在 CI/CD 中从 secrets 注入
USYNC_GITHUB_CLIENT_ID。 - 本地/fork 构建可通过环境变量或
.env设置USYNC_GITHUB_CLIENT_ID,也可以传--github-client-id <CLIENT_ID>。 init --oauth会创建私有/secret gist,并把 OAuth token 与 Gist ID 保存到本机 usync auth store。
- 创建/查看 Gist:https://gist.github.com/
命令示例
# 1) 扫描本地可同步文件
npx usync-cli scan
# 1.1) 验证 token 与 gist 访问
npx usync init --token <GITHUB_PAT> --gist-id <GIST_ID>
npx usync init -T <GITHUB_PAT> -g <GIST_ID>
# 1.2) OAuth 验证码登录,并自动创建/保存 gist
npx usync init --oauth
# 2) 上传到已有 gist
npx usync upload --token <GITHUB_PAT> --gist-id <GIST_ID>
npx usync upload -T <GITHUB_PAT> -g <GIST_ID>
# 3) 使用 PAT 创建新 gist 后上传
npx usync upload --token <GITHUB_PAT> --description cloudSettings --public
npx usync upload -T <GITHUB_PAT> -d cloudSettings -p
# 3.1) 使用 `init --oauth` 保存的 OAuth token / Gist ID 上传
npx usync upload
# 4) 下载并恢复到默认路径
npx usync download --token <GITHUB_PAT> --gist-id <GIST_ID>
npx usync download -T <GITHUB_PAT> -g <GIST_ID>
# 5) 下载到测试目录
npx usync download --token <GITHUB_PAT> --gist-id <GIST_ID> --output-root /path/to/settingsTest
npx usync download -T <GITHUB_PAT> -g <GIST_ID> -o /path/to/settingsTest
# 6) 本地有变化时自动上传
npx usync upload --token <GITHUB_PAT> --gist-id <GIST_ID> --watch --interval 15
npx usync upload -T <GITHUB_PAT> -g <GIST_ID> --watch -i 15
scan 不需要 PAT 和 Gist ID。
upload/download/init 可使用 PAT,也可使用 init --oauth 保存的 OAuth token / Gist ID。
scan 参数
| 参数 | 缩写 | 说明 |
|---|---|---|
--cwd | -C | 项目根目录 |
--providers | 逗号分隔的工具过滤 |
init 参数
| 参数 | 缩写 | 说明 |
|---|---|---|
--token | -T | GitHub PAT |
--oauth | 使用 GitHub OAuth 设备验证码认证 | |
--github-client-id | 覆盖 build/env/.env 中的 GitHub OAuth App client ID | |
--gist-id | -g | 已有 Gist ID(验证访问权限) |
--description | -d | 新 Gist 描述(默认:cloudSettings) |
--public | -p | PAT 流程可创建公开 Gist;OAuth 创建时始终保持私有 |
upload 参数
| 参数 | 缩写 | 说明 |
|---|---|---|
--token | -T | GitHub PAT(需要 gist 写权限) |
--oauth | 没有 token 时使用 GitHub OAuth 设备验证码认证 | |
--github-client-id | 覆盖 build/env/.env 中的 GitHub OAuth App client ID | |
--gist-id | -g | 已有 Gist ID |
--description | -d | Gist 描述 |
--public | -p | PAT 流程可创建公开 Gist;OAuth 创建时始终保持私有 |
--cwd | -C | 项目根目录 |
--interval | -i | 轮询间隔秒数(默认:15) |
download 参数
| 参数 | 缩写 | 说明 |
|---|---|---|
--gist-id | -g | Gist ID(若已由 init --oauth 保存则可省略) |
--token | -T | GitHub PAT |
--cwd | -C | 项目根目录 |
--output-root | -o | 自定义恢复目标路径 |
迁移(Migrate)
在 AI 编码工具之间迁移 MCP 配置和 skills。
# 从 Claude Code 迁移到 Kiro(默认全局范围)
npx usync migrate --from claude --to kiro
npx usync migrate -f claude -t kiro
# 从 Codex 迁移到 Claude Code
npx usync migrate --from codex --to claude
npx usync migrate -f codex -t claude
# 预览模式:只显示变更,不写入文件
npx usync migrate --from kiro --to claude --dry-run
npx usync migrate -f kiro -t claude -n
# 跳过确认提示(冲突默认跳过)
npx usync migrate --from claude --to kiro --yes
npx usync migrate -f claude -t kiro -y
# 强制覆盖已有文件
npx usync migrate --from codex --to kiro --yes --overwrite
npx usync migrate -f codex -t kiro -y -w
# 迁移项目级配置
npx usync migrate --from claude --to kiro --scope project
npx usync migrate -f claude -t kiro -s project
支持的工具:claude、opencode、codex、gemini、kiro、qoder、cursor
参数:
| 参数 | 缩写 | 说明 |
|---|---|---|
--from | -f | 源工具 |
--to | -t | 目标工具 |
--scope | -s | global(默认)或 project |
--dry-run | -n | 预览变更,不写入文件 |
--yes | -y | 跳过确认提示(冲突默认跳过,除非同时指定 --overwrite) |
--overwrite | -w | 强制覆盖目标已有文件(默认跳过冲突) |
--cwd | -C | 项目根目录(用于 project 范围) |
迁移特性
- 格式自动转换:MCP 配置在不同工具格式间自动转换(JSON
mcpServers、OpenCodemcp.<name>、Codex TOML[mcp_servers])。 - URL transport:远程 MCP 服务器(HTTP/SSE)按目标工具格式序列化 — Claude Code 用
type: "http",Gemini 用httpUrl,Cursor 用type: "sse",OpenCode 用type: "remote"。 - mcp-remote 检测:使用
mcp-remote做桥接的 stdio 服务器(如npx mcp-remote@latest https://...)会自动转换为原生 URL transport。--header参数会被提取并写入目标配置的headers字段。 - Skills 格式转换:结构化 skills(
SKILL.md+references/)会自动转换为扁平格式(适用于 Cursor、Gemini、Kiro 项目 steering),反之亦然。 - 系统 skills 过滤:工具内部目录(如 Codex
.system/)在迁移时自动排除。 - 冲突处理:目标已有文件默认跳过。使用
--overwrite强制覆盖,或交互模式下逐个选择。
说明:若目标 gist 还没有 usync 的 manifest,download 会回退到原始 gist 文件下载到 <output-root>/raw-gist/。可加 --strict-manifest 禁止回退。
当使用 --output-root 时,会写成可见目录映射(不再使用点前缀隐藏目录),例如:
.../home/claude/....../home/opencode/....../home/gemini/....../home/codex/...
PAT / OAuth 权限
- PAT 上传需要 Gist 写权限(
gist)。 - OAuth 设备验证码流程请求
gist read:user;OAuth 创建 gist 时 usync 会发送public: false。 - 可公开访问的 gist 可匿名下载;私有/secret gist 建议使用 token。
