01 · 你的仓库
一个仓库
- main 主检出
- 共享 .git 对象
- 其余不共享
Go 命令行工具 · MIT 协议 · 无守护进程
给每个 Agent 一个专属泊位
为并行编程 Agent 准备隔离的本地工作区：每个任务拥有独立的 Git worktree、私有数据目录、预留端口与受管进程——毫秒级完成，不需要虚拟机。
动画演示 · init → new → run → done
go install github.com/Mrjwj34/berth/cmd/berth@latest
- Linux · macOS · Windows
- 原生 + 容器
- 毫秒级操作
- 无后台守护进程
工作方式
两个 Agent，两个泊位，互不共享
每个工作区独占自己的 checkout、数据、端口与进程。下列数值仅作示意，实际分配按工作区进行。
02 · Agent A
berth new auth --up
- worktree berth/auth
- 数据 .berth/data
- BERTH_PORT_WEB=20001
- web、pg 受管
03 · Agent B
berth new payments --up
- worktree berth/payments
- 数据 .berth/data
- BERTH_PORT_WEB=20003
- web、pg 受管
04 · 推送之后
berth done auth
- 提交已保存
- 运行时已停止
- checkout 已释放
- 端口已归还
berth init && berth hook install all
berth new feature-a --up
berth run -- npm test
berth done feature-a四条命令，从空仓库到正在运行的隔离工作区。完整上手文档 →
隔离边界
隔离工作区，而不是隔离整台机器
纯 worktree 只管文件树；系统容器什么都能管，代价是每个环境都要启动一次。berth 把边界画在工作区上。
| 设计维度 | berth | 纯 git worktree | devcontainer / Docker |
|---|---|---|---|
| 隔离边界 | 工作区：worktree、私有数据、预留端口与一套进程图 | 仅文件树与分支 | 整个操作系统，按会话划分 |
| 启动开销 | 毫秒级注册表操作；原生模式直接启动宿主机进程 | 一次 git worktree add |
构建或拉取镜像、创建容器、挂载目录 |
| 端口分配 | 命名端口与工作区记录原子预留，以 BERTH_PORT_* 注入 |
手工逐个 checkout 改端口，极易误提交 | 显式映射到宿主端口，需自行保证不重复 |
| 数据隔离 | 每个工作区独立的 .berth/data；依赖目录以写时复制克隆 |
被 gitignore 的文件、数据库与缓存共享 | 容器文件系统独立，bind mount 的源码仍共享 |
| 进程管理 | up、down、logs、status 管理声明式进程图，带就绪探针 |
后台 shell 和记在脑子里的 PID | 容器生命周期可用，服务编排仍需自己实现 |
| 宿主文件系统速度 | 默认即宿主速度；容器模式 checkout 走 bind mount | 宿主速度 | macOS 与 Windows 上有 bind mount 性能损耗 |
对比纯 git worktree →
Git 已经给了你什么，以及它留给你的四件事。
对比 devcontainer / Docker →
什么时候系统边界是对的，以及每个环境的代价。
对比编排工具 →
会话编排层下面仍然需要一个运行时。berth 就是这一层。
一个工作区拥有什么
六件事，声明一次
全部写在 berth.yaml 中，随仓库提交，按工作区逐一应用。
每个任务独立 worktree
berth new <slug> 在 <repo>.berths/<slug> 创建分支 berth/<slug>，两个 Agent 永远不会编辑同一个 checkout。
原子端口预留
端口与工作区记录在同一次跨进程事务中预留，并在工作区生命周期内保持稳定。
私有数据目录
$BERTH_DATA_DIR 存放数据库、缓存与测试数据；copy_dirs 以写时复制克隆依赖目录。
受管进程
声明的进程图在工作区运行时中受管；up 等待就绪探针，status --json 直接给出真实状态。
不需要守护进程
只有文件锁和一份注册表。不同工作区可以并发推进，同一工作区内的命令串行执行。
原生为主，容器可选
原生模式直接运行宿主机进程，零虚拟化开销；容器模式为每个工作区复用一个预先构建的镜像，绝不按命令重建。
适配你的 Agent
一份技能，适配所有 harness
berth 就是普通命令行工具：任何能执行 shell 命令的 Agent 都能驱动它，一份技能安装到共享的 .agents/skills 约定目录即可。
Cursor
Codex
GitHub Copilot
Gemini CLI
opencode
Windsurf
Kilo Code
Zed
JetBrains Junie
Antigravity
pi
任意命令行 Agent
Claude Code 与 Cline 只读各自的技能目录，因此可用 berth skill install --agent claude,cline 额外写入一份副本。运行 berth agents 查看当前仓库已安装的内容。Agent 集成说明 →
常见问题
简短回答
运行细节都在文档中；这里是最先会被问到的几个问题。
两个 Claude Code 会话能同时修改同一个仓库吗？
可以，这正是 berth 要解决的场景。每个会话拥有自己的工作区：独立分支上的链接工作树、私有数据目录、独立预留的端口，以及自己的一套受管进程；它们只共享 Git 对象。
用 berth new <slug> --up 为每个 Agent 准备一个工作区，让它直接在命令输出的路径里工作。
怎么给每个 Agent 分配独立的端口？
只需在 berth.yaml 中声明一次，例如 ports: [web, pg]，每个工作区都会为这些名字预留唯一宿主端口。服务绑定 BERTH_PORT_WEB，浏览器与宿主工具使用 BERTH_HOST_PORT_WEB；没有任何硬编码，也就不会误提交。
为什么不直接使用 devcontainer？
如果你需要系统级隔离、统一的 Linux 工具链或与 CI 一致的环境，请使用容器——berth 不替代它，其容器模式也不打算成为它。
berth 隔离的是工作区：默认原生运行，端口、数据与环境变量由构造隔离。只有当程序硬编码监听端口或工具链仅限 Linux 时，才需要启用容器后端。
berth 需要常驻守护进程吗？
不需要。没有后台服务，也没有需要维持的套接字：只有文件锁和一份注册表文件（~/.berth/state.json，可用 BERTH_HOME 改址）。长时间操作只持有自身工作区的锁，进程监管交给 process-compose 或容器引擎。
清理工作区时我的数据会怎样？
berth down 保留全部内容，只停止进程；berth reset 按明确意图清空私有数据目录；berth done 要求分支提交已保存且工作树干净，然后移除 checkout——--force 无法绕过归属、身份与停机校验，被 adopt 的 checkout 永远保留。
支持 Windows 和 macOS 吗？
支持：为 Linux、macOS、Windows 提供预编译二进制，三个系统的原生命令行验收都在 CI 覆盖范围内。原生钩子在 Unix 上使用 sh、在 Windows 上使用 cmd，脚本并不通用；容器模式需要本机已安装 Docker 或 Podman。