setup-process

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The Setup Process

安装流程

Generate the right config so AI agents start in their isolated worktrees / environments with the same setup as the main repo: dependencies installed, env files in place, tool configs copied over.

Unless the context already provides an answer, explicitly ask the user which tool the setup is for: Cursor, Codex, or Conductor.
Map out the project (web, native, Rust, Swift, etc.) and make judgement calls on the right setup/install, run/actions, and teardown/archive commands.

Not all projects use bun. Some use

make

cargo

bun tauri dev

swift build

npm

pnpm

pip

, etc. Read the README,

package.json

scripts, top-level

Makefile

, or

Cargo.toml

to figure it out.

生成合适的配置，确保AI Agent在隔离的工作树/环境中启动时，拥有与主仓库一致的配置：已安装的依赖项、到位的环境文件、复制完成的工具配置。

除非上下文已给出答案，否则需明确询问用户安装针对的工具是Cursor、Codex还是Conductor。
梳理项目类型（Web、原生、Rust、Swift等），判断合适的安装/运行/操作命令，以及清理/归档命令。

并非所有项目都使用bun。有些项目使用

make

、

cargo

、

bun tauri dev

、

swift build

、

npm

、

pnpm

、

pip

等。请查看README、

package.json

脚本、顶层

Makefile

或

Cargo.toml

来确定合适的工具。

What each tool reads

各工具读取的配置文件

Cursor: Local parallel-agent worktrees in
```
.cursor/worktrees.json
```
.
Codex: Setup script + actions in
```
.codex/environments/environment.toml
```
.
Conductor: Workspace setup in
```
conductor.json
```
.

Cursor： 本地并行Agent工作树存储在
```
.cursor/worktrees.json
```
中。
Codex： 安装脚本与操作配置在
```
.codex/environments/environment.toml
```
中。
Conductor： 工作区配置在
```
conductor.json
```
中。

The shared pattern

通用模式

Across all of them, the setup script usually does the same 3 things:

Install dependencies - run appropriate commands by project type, like Bun, Tauri, make, cargo, swift, etc. Read the README,
```
package.json
```
,
```
Makefile
```
,
```
Cargo.toml
```
, or similar to figure out what's right.
Copy AI-tool config dirs -
```
.agents
```
,
```
.claude
```
,
```
.codex
```
,
```
.cursor
```
from the source repo into the new environment.
Copy env files -
```
.env
```
,
```
.env.local
```
,
```
.env.development
```
, etc.

CRITICAL: the setup script always lives project-scoped, not global.

所有工具的安装脚本通常都包含以下3个步骤：

安装依赖项 - 根据项目类型运行相应命令，如Bun、Tauri、make、cargo、swift等。请查看README、
```
package.json
```
、
```
Makefile
```
、
```
Cargo.toml
```
或类似文件来确定合适的命令。
复制AI工具配置目录 - 将源仓库中的
```
.agents
```
、
```
.claude
```
、
```
.codex
```
、
```
.cursor
```
目录复制到新环境中。
复制环境文件 - 复制
```
.env
```
、
```
.env.local
```
、
```
.env.development
```
等文件。

重要提示：安装脚本始终是项目级的，而非全局的。

Reusable copy snippet

可复用的复制代码片段

Replace

$SOURCE

and

$DEST

with the right env vars for the platform (see the table near the bottom):

bash

for d in .agents .claude .codex .cursor; do
    [ -d "$SOURCE/$d" ] && mkdir -p "$DEST/$d" && rsync -a "$SOURCE/$d/." "$DEST/$d/"
done
[ -f "$SOURCE/{ENV_FILE}" ] && cp "$SOURCE/{ENV_FILE}" "$DEST/{ENV_FILE}" || true

将

$SOURCE

和

$DEST

替换为对应平台的环境变量（参见底部的表格）：

bash

for d in .agents .claude .codex .cursor; do
    [ -d "$SOURCE/$d" ] && mkdir -p "$DEST/$d" && rsync -a "$SOURCE/$d/." "$DEST/$d/"
done
[ -f "$SOURCE/{ENV_FILE}" ] && cp "$SOURCE/{ENV_FILE}" "$DEST/{ENV_FILE}" || true

Templates

模板

Replace

{INSTALL_CMD}

{RUN_CMD}

, and

{ENV_FILE}

per project.

根据项目替换

{INSTALL_CMD}

、

{RUN_CMD}

和

{ENV_FILE}

。

Cursor

Cursor exposes

$ROOT_WORKTREE_PATH

(the source repo root). Scripts run inside the new worktree, so the destination is just the current working directory.

For OS-specific setups, use

setup-worktree-unix

setup-worktree-windows

setup-worktree

is the cross-platform fallback.

json

{
    "setup-worktree": [
        "{INSTALL_CMD}",
        "for d in .agents .claude .codex .cursor; do [ -d \"$ROOT_WORKTREE_PATH/$d\" ] && mkdir -p \"$d\" && rsync -a \"$ROOT_WORKTREE_PATH/$d/.\" \"$d/\"; done",
        "[ -f \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" ] && cp \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" \"{ENV_FILE}\" || true"
    ]
}

Cursor暴露

$ROOT_WORKTREE_PATH

（源仓库根目录）。脚本在新工作树内运行，因此目标路径就是当前工作目录。

针对不同系统的安装，请使用

setup-worktree-unix

或

setup-worktree-windows

。

setup-worktree

是跨平台的备选方案。

json

{
    "setup-worktree": [
        "{INSTALL_CMD}",
        "for d in .agents .claude .codex .cursor; do [ -d \"$ROOT_WORKTREE_PATH/$d\" ] && mkdir -p \"$d\" && rsync -a \"$ROOT_WORKTREE_PATH/$d/.\" \"$d/\"; done",
        "[ -f \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" ] && cp \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" \"{ENV_FILE}\" || true"
    ]
}

Codex

The file is autogenerated by the Codex desktop app - don't hand-edit it lightly, but it's plain TOML and committed to git. Schema:

toml

version = 1
name = "{PROJECT_NAME}"

[setup]
script = '''
#!/usr/bin/env bash
set -euo pipefail

{INSTALL_CMD}

该文件由Codex桌面应用自动生成——请勿随意手动编辑，但它是纯TOML格式并提交到Git。Schema如下：

toml

version = 1
name = "{PROJECT_NAME}"

[setup]
script = '''
#!/usr/bin/env bash
set -euo pipefail

{INSTALL_CMD}

Sync config dirs from source tree into the worktree

for d in .agents .claude .codex .cursor; do if [ -d "$CODEX_SOURCE_TREE_PATH/$d" ]; then mkdir -p "$CODEX_WORKTREE_PATH/$d" rsync -a "$CODEX_SOURCE_TREE_PATH/$d/." "$CODEX_WORKTREE_PATH/$d/" fi done

Copy env file if present

if [ -f "$CODEX_SOURCE_TREE_PATH/{ENV_FILE}" ]; then cp "$CODEX_SOURCE_TREE_PATH/{ENV_FILE}" "$CODEX_WORKTREE_PATH/{ENV_FILE}" fi '''

[[actions]] name = "Dev Server" icon = "run" command = "{RUN_CMD}"

[[actions]] name = "Build" icon = "build" command = "{BUILD_CMD}"


The `[setup]` script runs at the start of every new worktree / task. The `[[actions]]` blocks each become a named shortcut in the Codex UI. Common icons: `run`, `build`, `debug`, `logs`, `check`, `package`.

if [ -f "$CODEX_SOURCE_TREE_PATH/{ENV_FILE}" ]; then cp "$CODEX_SOURCE_TREE_PATH/{ENV_FILE}" "$CODEX_WORKTREE_PATH/{ENV_FILE}" fi '''

[[actions]] name = "Dev Server" icon = "run" command = "{RUN_CMD}"

[[actions]] name = "Build" icon = "build" command = "{BUILD_CMD}"


`[setup]`脚本会在每个新工作树/任务开始时运行。`[[actions]]`块会在Codex UI中成为命名快捷方式。常用图标包括：`run`、`build`、`debug`、`logs`、`check`、`package`。

Conductor

conductor.json

lives at the repo root and gets shared with teammates so everyone gets the same workspace setup.

Fields:

Field	Type	Description
`scripts.setup`	string	Command to run when setting up a new workspace.
`scripts.run`	string	Command to start the dev server.
`scripts.archive`	string	Command to run when archiving a workspace.
`runScriptMode`	`"concurrent"` \| `"nonconcurrent"`	Whether to kill in-progress run scripts before starting a new one.

Template:

json

{
    "scripts": {
        "setup": "{INSTALL_CMD}; for d in .agents .claude .codex .cursor; do [ -d \"$CONDUCTOR_ROOT_PATH/$d\" ] && mkdir -p \"$CONDUCTOR_WORKSPACE_PATH/$d\" && rsync -a \"$CONDUCTOR_ROOT_PATH/$d/.\" \"$CONDUCTOR_WORKSPACE_PATH/$d/\"; done; [ -f \"$CONDUCTOR_ROOT_PATH/{ENV_FILE}\" ] && cp \"$CONDUCTOR_ROOT_PATH/{ENV_FILE}\" \"$CONDUCTOR_WORKSPACE_PATH/{ENV_FILE}\"",
        "run": "{RUN_CMD}"
    }
}

conductor.json

位于仓库根目录，可与团队成员共享，确保所有人拥有相同的工作区配置。

字段说明：

字段	类型	描述
`scripts.setup`	string	新建工作区时运行的命令。
`scripts.run`	string	启动开发服务器的命令。
`scripts.archive`	string	归档工作区时运行的命令。
`runScriptMode`	`"concurrent"` \| `"nonconcurrent"`	启动新的运行脚本前是否终止正在运行的脚本。

模板：

json

{
    "scripts": {
        "setup": "{INSTALL_CMD}; for d in .agents .claude .codex .cursor; do [ -d \"$CONDUCTOR_ROOT_PATH/$d\" ] && mkdir -p \"$CONDUCTOR_WORKSPACE_PATH/$d\" && rsync -a \"$CONDUCTOR_ROOT_PATH/$d/.\" \"$CONDUCTOR_WORKSPACE_PATH/$d/\"; done; [ -f \"$CONDUCTOR_ROOT_PATH/{ENV_FILE}\" ] && cp \"$CONDUCTOR_ROOT_PATH/{ENV_FILE}\" \"$CONDUCTOR_WORKSPACE_PATH/{ENV_FILE}\",
        "run": "{RUN_CMD}"
    }
}

Environment variables by platform

各平台的环境变量

Cursor:
```
$ROOT_WORKTREE_PATH
```
/ (cwd is the new worktree, no separate destination var)

Codex:

$CODEX_SOURCE_TREE_PATH

$CODEX_WORKTREE_PATH

Conductor:

$CONDUCTOR_ROOT_PATH

$CONDUCTOR_WORKSPACE_PATH

Vendors rename these. Always check the platform's docs before writing them.

Cursor：
```
$ROOT_WORKTREE_PATH
```
/ （当前工作目录即为新工作树，无单独的目标变量）

Codex：

$CODEX_SOURCE_TREE_PATH

$CODEX_WORKTREE_PATH

Conductor：

$CONDUCTOR_ROOT_PATH

$CONDUCTOR_WORKSPACE_PATH

各厂商会对这些变量重命名。编写前请务必查看平台文档。

Usage

使用方法

CRITICAL: The user is a non-technical, non-engineer. Avoid technical jargon and help them set up the correct setup scripts for their setup.

Identify which environment the project needs (per the user's answer).
Detect project type and pick
```
{INSTALL_CMD}
```
/
```
{RUN_CMD}
```
/
```
{ENV_FILE}
```
from the table above (or read the README).
Generate the matching config file from Templates.
Offer to git commit for teams to have access to it too.
Offer to also generate the same for other agents that this skill supports.

重要提示：用户是非技术背景的非工程师。请避免使用技术术语，帮助他们为自身环境生成正确的安装脚本。

根据用户的回答确定项目所需的环境。
检测项目类型，从上述表格（或README）中选择
```
{INSTALL_CMD}
```
/
```
{RUN_CMD}
```
/
```
{ENV_FILE}
```
。
根据模板生成匹配的配置文件。
建议用户提交到Git，以便团队成员也能使用。
可主动提出为该技能支持的其他Agent生成相同配置。