claude-runtime-sync 0.1.0 → 0.1.2

package/README.md

@@ -1,94 +1,123 @@
 # claude-runtime-sync
 
-Use Claude config (`~/.claude` + `<repo>/.claude`) as the **single source of truth**, and sync reusable runtime capabilities into Codex.
+让你把 Claude 配置（`~/.claude` + 项目内 `.claude`）作为唯一真实源，并自动复用到 Codex。
 
-## Features
+适合不想记很多命令的用户：**装好后基本只用 `codex`。**
 
-- Sync skills from Claude to Codex
-- Sync MCP servers into managed block of `~/.codex/config.toml`
-- Mirror project `.mcp.json` into `~/.claude/mcp.json`
-- Sync Claude plugins and hooks metadata into Codex runtime area
-- Generate bridge manifest for Codex event -> Claude hooks mapping
-- Keep `agents.md` / `gemini.md` aligned with `CLAUDE.md` (symlink-first)
-- Install zsh startup hook for auto-check + auto-sync before each `codex` launch
-
-## Install
+## 30 秒上手（推荐）
 
 ```bash
+# 1) 全局安装（一次）
 npm i -g claude-runtime-sync
-```
 
-## CLI
+# 2) 接入 codex 启动流程（一次）
+crs hook install
 
-```bash
+# 3) 首次手动同步（一次）
 crs sync
-crs check
-crs bridge --watch
-crs hook install
-crs hook remove
-crs sync-base
 ```
 
-## Common flags
+之后日常直接：
 
 ```bash
---project-root=/path/to/repo
---claude-home=/path/to/.claude
---codex-home=/path/to/.codex
---no-home
---no-project
+codex
 ```
 
-## Recommended bootstrap
+`codex` 每次启动前会自动检查并在需要时同步。
+
+---
+
+## 它会帮你自动处理什么
+
+- 同步 skills（`~/.claude/skills` + `<repo>/.claude/skills`）
+- 同步 MCP 到 `~/.codex/config.toml` 托管区块
+- 镜像项目 `.mcp.json` 到 `~/.claude/mcp.json`（保持 `.claude` 为真源）
+- 同步 Claude plugins / hooks 元信息到 Codex 运行目录
+- 把 `CLAUDE.md` 复用到 `agents.md` / `gemini.md`（软链接优先）
+- 通过 bridge 将 Codex 事件映射到 Claude 风格 hooks
+
+---
+
+## 日常使用（你只需要记这些）
+
+### 1) 平时开发
 
 ```bash
-# 1) one-time hook install
-crs hook install
+codex
+```
 
-# 2) verify drift state
-crs check
+### 2) 改了 `.claude` / `.mcp.json` 后，想立即生效
 
-# 3) apply sync if needed
+```bash
 crs sync
 ```
 
-## Local development
+### 3) 想确认是否有漂移
 
 ```bash
-npm run check
-npm run smoke
-npm run pack:dry-run
+crs check
 ```
 
-## GitHub Actions
-
-This repo includes:
+---
 
-- `.github/workflows/ci.yml`: syntax check + CLI smoke + pack dry run
-- `.github/workflows/publish.yml`: publish to npm on `v*` tag or manual dispatch
+## 常用命令（精简版）
 
-Required repository secret:
+```bash
+crs sync             # 执行同步
+crs check            # 只检查差异（有差异返回码 1）
+crs hook install     # 安装 zsh 自动同步钩子
+crs hook remove      # 卸载钩子
+crs bridge --watch   # 手动运行事件桥接（一般不需要）
+crs sync-base        # 仅同步 skills + mcp
+```
 
-- `NPM_TOKEN`: npm automation token with publish permission
+---
 
-## Publish flow
+## 可选参数（按需）
 
 ```bash
-# bump version first
-npm version patch
+--project-root=/path/to/repo
+--claude-home=/path/to/.claude
+--codex-home=/path/to/.codex
+--no-home
+--no-project
+```
 
-# publish from local (optional)
-npm publish --access public
+---
 
-# or publish via CI
-# git push --follow-tags
-```
+## 排障（只在需要时看）
+
+- 临时关闭自动同步：
+  ```bash
+  CODEX_SYNC_DISABLE=1 codex
+  ```
+- 临时关闭插件桥接：
+  ```bash
+  CODEX_PLUGIN_BRIDGE_DISABLE=1 codex
+  ```
+- 重新安装钩子：
+  ```bash
+  crs hook remove
+  crs hook install
+  ```
+
+---
+
+## 使用前提
+
+- Node.js >= 18
+- 已安装 `codex` CLI
+- 当前自动 hook 入口为 **zsh**（`crs hook install`）
+
+---
 
-## Notes
+## 发布者本地检查（维护者）
 
-- Event bridge uses structured Codex session events and maps them to Claude-style hook events.
-- If you only need base sync (skills + mcp), run `crs sync-base`.
-- Example project config: `examples/.claude-codex-sync.example.json`.
+```bash
+npm run check
+npm run smoke
+npm run pack:dry-run
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-runtime-sync",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Use Claude config as the single source of truth and sync reusable capabilities into Codex runtime.",
   "license": "MIT",
   "type": "commonjs",