快速开始

要求：Bun 1.3+。

运行引导式 CLI：

npx @iannuttall/dotagents

或者使用 Bun：

bunx @iannuttall/dotagents

选择工作空间（全局主目录或项目文件夹），挑选你想要管理的客户端，并按照提示操作。你可以随时再次运行它来修复链接或撤销更改。

全局主目录会影响所有项目。而项目文件夹仅影响你当前运行 dotagents 的目录。

它的作用

• 将 .agents 作为唯一事实来源。
• 根据你的选择，为 Claude、Codex、Factory、Cursor、OpenCode 和 Gemini 创建符号链接。
• 在任何覆盖操作之前都会创建备份，因此更改可以撤销。

全局范围内的链接位置

.agents/CLAUDE.md → ~/.claude/CLAUDE.md（如果存在）

.agents/AGENTS.md → ~/.claude/CLAUDE.md（当没有 CLAUDE.md 时的备用）

.agents/GEMINI.md → ~/.gemini/GEMINI.md（如果存在）

.agents/AGENTS.md → ~/.gemini/GEMINI.md（当没有 GEMINI.md 时的备用）

.agents/commands → ~/.claude/commands

.agents/commands → ~/.factory/commands

.agents/commands → ~/.codex/prompts

.agents/commands → ~/.cursor/commands

.agents/commands → ~/.config/opencode/commands

.agents/commands → ~/.gemini/commands

.agents/hooks → ~/.claude/hooks

.agents/hooks → ~/.factory/hooks

.agents/AGENTS.md → ~/.factory/AGENTS.md

.agents/AGENTS.md → ~/.codex/AGENTS.md

.agents/AGENTS.md → ~/.config/opencode/AGENTS.md

.agents/skills → ~/.claude/skills

.agents/skills → ~/.factory/skills

.agents/skills → ~/.codex/skills

.agents/skills → ~/.cursor/skills

.agents/skills → ~/.config/opencode/skills

.agents/skills → ~/.gemini/skills

项目范围内的链接仅将 commands/hooks/skills 链接到项目的客户端文件夹中（不涉及 AGENTS/CLAUDE/GEMINI 规则）。

开发

在开发模式下运行 CLI：

bun run dev

类型检查：

bun run type-check

运行测试：

bun test

构建 CLI：

bun run build

注意事项

• Cursor 支持 .claude/commands 和 .claude/skills（全局或项目）。dotagents 还会将 .agents/commands 链接到 .cursor/commands，将 .agents/skills 链接到 .cursor/skills。
• OpenCode 使用 ~/.config/opencode/AGENTS.md，并且当 AGENTS.md 和 CLAUDE.md 同时存在时，优先使用 AGENTS.md。
• Codex 的提示始终会符号链接到 .agents/commands（规范来源）。
• 技能需要有效的 SKILL.md 文件，其中包含 name 和 description 的 frontmatter。
• Claude 提示的优先级：如果存在 .agents/CLAUDE.md，则会链接到 .claude/CLAUDE.md；否则将使用 .agents/AGENTS.md。添加或移除 .agents/CLAUDE.md 后，请重新运行 dotagents 并应用/修复链接以更新符号链接。Factory 和 Codex 始终链接到 .agents/AGENTS.md。
• Gemini 上下文文件的优先级：如果存在 .agents/GEMINI.md，则会链接到 .gemini/GEMINI.md；否则将使用 .agents/AGENTS.md。添加或移除 .agents/GEMINI.md 后，请重新运行 dotagents 并应用/修复链接以更新符号链接。
• 项目范围只会创建 .agents 目录以及用于 commands/hooks/skills 的客户端文件夹。规则文件（AGENTS.md/CLAUDE.md/GEMINI.md）保留在仓库根目录，以便你可以显式地管理它们。
• 备份存储在 .agents/backup/<timestamp> 下，可以通过“撤销上次更改”恢复。

许可证

MIT

dotagents 快速上手指南

dotagents 是一个统一的配置管理工具，通过一个标准的 .agents 文件夹来驱动你所有的 AI 编程助手（如 Claude、Cursor、Gemini 等），实现“一次配置，处处生效”。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 运行时环境：必须安装 Bun，版本需为 1.3 或更高。
• 操作系统：支持 macOS、Linux 及 Windows (WSL)。

提示：如果你尚未安装 Bun，可以通过以下命令安装（国内用户如遇网络问题，可尝试使用镜像源或代理）：

curl -fsSL https://bun.sh/install | bash

安装步骤

dotagents 无需全局安装，推荐直接使用 npx 或 bunx 运行引导式 CLI 工具。

方式一：使用 npx (npm 用户)

npx @iannuttall/dotagents

方式二：使用 bunx (推荐，速度更快)

bunx @iannuttall/dotagents

基本使用

运行上述命令后，CLI 将启动交互式向导，请按以下步骤操作：

1. 选择工作空间范围：

   • Global home (全局)：配置将影响你本机所有项目（符号链接指向用户主目录下的配置文件）。
   • Project folder (项目级)：配置仅影响当前运行命令的目录（符号链接指向当前项目内的客户端文件夹）。

2. 选择客户端： 勾选你需要管理的 AI 工具（支持 Claude, Codex, Factory, Cursor, OpenCode, Gemini 等）。

3. 自动链接与备份： 工具会自动将 .agents 目录下的文件（如 CLAUDE.md, commands, skills 等）创建符号链接到对应工具的配置目录。

   • 安全机制：在覆盖任何现有文件前，dotagents 会自动创建备份（存储在 .agents/backup/<时间戳>），确保操作可随时撤销。

4. 维护与修复： 你可以随时再次运行该命令。如果链接丢失或配置出错，重新运行即可修复链接或撤销更改。

核心文件结构说明

运行后，你的项目中将生成 .agents 目录作为唯一事实来源（Source of Truth）：

• 规则文件：
  • .agents/CLAUDE.md → 优先链接至 Claude 配置（若无则 fallback 到 AGENTS.md）。
  • .agents/GEMINI.md → 优先链接至 Gemini 配置（若无则 fallback 到 AGENTS.md）。
  • .agents/AGENTS.md → 通用规则，用于 Factory, Codex, OpenCode 等。
• 功能目录：
  • .agents/commands → 同步所有工具的自定义命令/Prompts。
  • .agents/skills → 同步所有工具的技能定义（需包含有效的 SKILL.md frontmatter）。
  • .agents/hooks → 同步钩子脚本。

注意：若修改了 .agents 下的核心文件（如新增或删除 CLAUDE.md），请重新运行 bunx @iannuttall/dotagents 以更新符号链接。