tmux-worktree 提供两套工具，用于管理 AI 编程 session：
tw：Node.js CLI，创建独立 git worktree、启动 tmux session，并运行指定 AI 命令。tw-dashboard：macOS Tauri 桌面端，管理 tmux session、worktree、终端、文件、Git 状态和远程访问。
仓库代码结构、开发/发布边界见 ARCHITECTURE.md。
内部 bnpm 安装：
npx -y --registry=https://bnpm.byted.org -p @byted-codebase/tmux-worktree tw-dashboard-install
open -a tw-dashboard如果已经有 DMG，也可以手动拖入 /Applications 安装。
npm i -g @byted-codebase/tmux-worktree --registry=https://bnpm.byted.org
tw setupCLI 和 Dashboard 共用 ~/.tmux-worktree.json：
{
"projects": {
"myapp": "/path/to/myapp",
"backend": "/path/to/backend"
},
"worktreeBase": "/private/tmp/tmux-worktree/projects"
}projects：项目名到 git 仓库路径的映射，供 CLI 和 Dashboard 新建 worktree 使用。worktreeBase：自动创建 worktree 的父目录。
Dashboard 额外状态文件：
~/.tw-dashboard-layout.json：窗口、栏目、当前选择、文件树、编辑器/diff、侧边栏布局。~/.tw-dashboard-terminals.json：独立终端列表。~/.tw-dashboard-pending-worktree-cleanup.json：延迟清理的 worktree 记录。
创建 AI 开发环境：
tw claude myapp
tw claude myapp fix-auth
tw "claude --model opus" backend
tw claude ~/some/repo
tw子命令：
tw setup：检查系统依赖。tw status：tmux 内的 session 状态面板。tw serve：启动本地 WebSocket 终端服务。tw serve --remote：本地终端服务加 Cloudflare Quick Tunnel。
常用流程：
- 点击
+ worktree创建或恢复 worktree session。 - 在左侧选择 session，主区域会 attach 到对应 tmux。
- 左下角 Git 面板查看分支、文件变更和 commit 历史。
- 打开文件树后，可以浏览项目并打开编辑器或 diff 栏。
- 点击 remote access，通过 Cloudflare Quick Tunnel 在手机或其他设备访问 Web 终端。
布局行为：
- 首次打开是默认三栏：侧边栏、主终端、scratch。
- 如果关闭前打开了文件树、编辑器或 diff 栏，重启后会恢复这些栏目和宽度。
- Git 面板会跟随当前 tmux session 的 active pane cwd，因此 agent 在 tmux 中切换目录或分支后，面板分支也会刷新。
依赖：
- Node.js 20+
- Rust stable
- Xcode Command Line Tools
- tmux
- git
- cloudflared，可选，仅远程访问需要
CLI：
npm install
npm run build
node dist/cli.js status --onceDashboard：
cd app
npm install
npm run tauri dev如果本机已经安装正式版 tw-dashboard.app，建议用隔离 dev app：
cd app
npm run tauri:dev:isolated
npm run tauri:dev:install本地 dev 版本有两种常用方式：
npm run tauri:dev:isolated：启动热更新 dev app，使用临时TW_DASHBOARD_HOME，适合日常开发调试。npm run tauri:dev:install：构建一个唯一命名的 debug.app并安装到/Applications，适合 GUI smoke test 或需要从 Finder/open 启动的场景。
tauri:dev:install 会在输出中打印卸载和临时状态目录清理命令。验证结束后按输出清理，避免 /Applications 和 /tmp 堆积旧 dev app。
CLI 和 Dashboard installer 共用根目录 npm 包发布：
./app/scripts/release.sh --dry-run
./app/scripts/release.sh发布脚本会：
- 构建 Tauri Dashboard DMG。
- 构建根目录 CLI 到
dist/cli.js。 - 复制 DMG 到
app/installer/dmg/tw-dashboard-arm64.dmg。 - 发布根目录 npm 包到 bnpm。
npm 包只包含：
distapp/installer/installer.mjsapp/installer/dmg/
每次完成一个 feature 或 bugfix 后，按下面顺序推进。不要跳过构建测试，也不要在测试失败时 bump 或发布。
- 确认工作区和分支。
git status --short --branch
git diff --check- 构建和测试。
npm install
npm run build
cd app
npm install
npm run build
cd src-tauri
cargo fmt --check
cargo check
cargo test- 及时更新文档。
代码行为、发布步骤、配置、运行时状态或开发/发布边界发生变化时，必须同步更新：
README.md：用户使用、开发、发布和操作流程。ARCHITECTURE.md：代码结构、开发/发布边界、状态文件和关键 command 分组。
不要新增重复文档；优先维护这两份。
- Bump 版本号。
需要同步更新：
package.json：npm 包版本，决定 bnpm 发布版本。app/src-tauri/tauri.conf.json：Dashboard 构建版本，决定 DMG 文件名。app/src-tauri/Cargo.toml：Rust crate 版本，保持本地构建元数据一致。
app/package.json 是私有前端工程版本，默认不作为发布版本来源，除非明确需要一起维护。
- 提交并同步 feature/bugfix 分支到两个远端。
git add <changed-files>
git commit -m "fix: ..."
git push origin HEAD:<branch>
git push github HEAD:<branch>- 合入
origin/master。
在 Codebase 创建 MR：<branch> -> master。确认 diff、checks 和 mergeability 后再合入。
codebase mr create -R jiangyunong/tmux-worktree --source <branch> --target master --title "<title>" --body "<summary>"
codebase mr status -R jiangyunong/tmux-worktree -N <mr>
codebase mr checks list -R jiangyunong/tmux-worktree -N <mr>如果是自己负责的小改动且明确不需要人工 review，可以按仓库当前流程 skip review：
codebase mr bypass -R jiangyunong/tmux-worktree -N <mr> --review --reason no_need_for_review --yes
codebase mr merge -R jiangyunong/tmux-worktree -N <mr> --merge --no-delete-branch --yes- 同步
github/master。
git fetch origin master
git push github origin/master:master
git fetch github master确认两边主分支一致：
git rev-parse --short origin/master github/master
git log --oneline --left-right --cherry-pick origin/master...github/master- 构建本地 dev/debug app 做 smoke test。
如需热更新调试：
cd app
npm run tauri:dev:isolated如需安装一个独立 debug app 到 /Applications 验证真实启动行为：
cd app
npm run tauri:dev:install确认关键功能后，按命令输出中的 uninstall 和 cleanup state 清理本地 dev app。
- 构建安装包并发布 release。
先预览包内容：
./app/scripts/release.sh --dry-run确认无误后发布：
./app/scripts/release.sh- 更新本地验证仓库。
cd ~/Desktop/test/tmux-worktree
git fetch origin master
git fetch github master
git merge --ff-only origin/master
git status --short --branch- 更新本机已安装的 Dashboard App。
发布到 bnpm 后，用正式安装器更新 /Applications/tw-dashboard.app：
npx -y --registry=https://bnpm.byted.org -p @byted-codebase/tmux-worktree tw-dashboard-install
open -a tw-dashboardMIT