miniLV/Plexus

Plexus

Plexus Agent Config - 本地 Claude Code、Cursor、Codex、Gemini CLI、Qwen Code、DeepSeek Harness 和 OpenCode 配置同步。

一个本地控制台，把 Rules、MCP Servers 和 Skills 同步到你常用的 AI 编程工具。

先导入你已经配置好的 Claude Code、Cursor、Codex、Gemini CLI、Qwen Code、DeepSeek Harness、OpenCode 等工具，再用一次点击同步到其他 Agent。

Latest Release ·
Homepage ·
简体中文 · English

npx -y plexus-agent-config@latest start

场景指南：
Guides ·
中文场景说明 ·
Claude Code / Cursor Config ·
Claude Code / Codex Skills + MCP ·
CLAUDE.md / AGENTS.md

适合已经同时使用 Claude Code、Cursor、Codex、Gemini CLI、Qwen Code、DeepSeek Harness 或 OpenCode，并且已经开始被配置漂移折腾的人。

local-first · 写回前自动 snapshot · 对共享原生配置使用 partial-write，而不是整文件覆盖

如果 Plexus 帮你少维护几份重复的 Agent 配置，欢迎点个 Star，让更多多 Agent 用户看到它。

为什么需要 Plexus？

现在的 AI 编程工作很少只用一个工具。你可能用 Claude Code 做规划，用 Cursor 写代码，用 Codex 跑自动化，再偶尔切到 Gemini CLI、Qwen Code、DeepSeek Harness、OpenCode、Windsurf 或 Kiro。问题是，每个工具都有自己的配置文件、MCP 格式、Skill 目录和指令文件。

于是每次有一个好用配置，都要重复做几遍：

- 把同一个 MCP Server 复制到多个 agent 的原生配置里
- 让 CLAUDE.md 和 AGENTS.md 保持一致
- 在不同工具的 skill / prompt 目录里维护相似文件夹
- 出问题后很难知道到底改了哪里
- 想回滚一次同步，又担心覆盖掉 auth、history 或个人设置

Plexus 的目标很简单：给这些工具一个本地的 single source of truth。

30 秒看懂
如果你同时使用 Claude Code、Cursor、Codex、Gemini CLI、Qwen Code、DeepSeek Harness 或 OpenCode，并且已经厌倦了在五六个地方手动维护同一份配置，Plexus 就是为这个场景做的。

它会把 ~/.config/plexus/ 作为本机 canonical store，同时扫描各个 agent 的原生配置，把 Plexus store 和 native-only 配置取并集合并。同 ID 内容不同才需要你选择保留哪个版本；普通同步不需要选择 source。每次写入原生文件前都会创建 snapshot，后悔了可以从 Backups 页面恢复。

Plexus 能做什么？

| 能力 | Plexus 管什么 |
| --- | --- |
| 全局规则 | 在 ~/.config/plexus/personal/rules/global.md 维护一份基线，投射到 CLAUDE.md 和 AGENTS.md |
| MCP Servers | 把团队层和个人层的 MCP 同步到每个 agent 的原生格式 |
| Skills | 把 Markdown skill bundle 链接或复制到各 agent 的 skill 目录 |
| Skill Market | 按 GitHub 星标排行浏览社区技能，一键下载安装到 personal store 并同步 |
| Mirror | 从一个 agent 选择有效配置，预览差异后同步到其他 agent |
| Backups | 每次写入原生文件前自动 snapshot，并支持从 dashboard 恢复 |
| Team Layer | 订阅一个 Git repo，分发团队认可的 MCP 和 skills |

Plexus 不运行 MCP Server。它只是一个本地 dashboard，用来安全地编辑、同步和回滚配置。

一张图看懂同步模型

Plexus 不要求所有 AI 工具改成同一种格式。它只在本机维护一份 canonical config，然后按文件类型选择最合适的投射方式：Rules 和 Skills 优先软链接，MCP 对专用文件使用 cache symlink，对共享文件使用 partial-write。

这张图也可以在本地 dashboard 里打开：/architecture/config-sharing-map.html。

Agent Catalog 和手动新增入口在 Settings -> Agent Catalog。如果一个新工具还不在内置列表里，可以点 Add agent 先登记它的 instruction file；Plexus 会负责查看、编辑和备份，后续再逐步补齐 MCP / Skills adapter。

快速开始

需要 Node 20。

Plexus 现在通过一个 npm 包发布，内部的 core 和 web dashboard 已经随包带上，不需要分别安装多个包。

npm install -g plexus-agent-config
plexus

打开 http://localhost:7777。

不想全局安装也可以直接运行：

npx -y plexus-agent-config@latest start

也可以先检查 Plexus 能识别哪些 agent：

plexus detect

从源码运行

git clone https://github.com/miniLV/Plexus.git
cd Plexus
npm ci
npm run dev

打开 http://localhost:7777。

第一次使用时，只需要点 Dashboard 右上角的 Share config everywhere：

1. Plexus 会检测已安装的 Agent，并把 Plexus store、native Rules、MCP Servers 和 Skills 合并成并集。
2. 页面会展示 smart-merge preview；只有同 ID 不同内容时才进入冲突处理。
3. Plexus 会把配置应用到 enabled agents，并在写入原生文件前创建 snapshot。

如果想用本地 CLI：

npm run link
plexus

移除本地链接：

npm run unlink

支持的 Agent

| Agent | Rules 目标 | MCP 目标 | Skills 目标 | MCP 写入方式 |
| --- | --- | --- | --- | --- |
| Claude Code | ~/.claude/CLAUDE.md | ~/.claude.json | ~/.claude/skills/ | partial write |
| Cursor | ~/.cursor/AGENTS.md | ~/.cursor/mcp.json | ~/.cursor/skills/ | symlink or copy |
| Codex | ~/.codex/AGENTS.md | ~/.codex/config.toml | ~/.codex/skills/ | partial write |
| Gemini CLI | ~/.gemini/GEMINI.md | ~/.gemini/settings.json | ~/.gemini/skills/ | partial write |
| Qwen Code | ~/.qwen/QWEN.md | ~/.qwen/settings.json | ~/.qwen/skills/ | partial write |
| Factory Droid | ~/.factory/AGENTS.md | ~/.factory/mcp.json | ~/.factory/skills/ | symlink or copy |
| DeepSeek Harness | ~/.dsh/AGENTS.md | ~/.dsh/mcp.json | ~/.dsh/skills/ | partial write |
| OpenCode | ~/.config/opencode/AGENTS.md | ~/.config/opencode/opencode.json | ~/.config/opencode/skills/ | 部分写入 |

部分写入表示 Plexus 只重写 MCP section，保留同一个文件里由 agent 自己管理的 auth、history、profile 和 settings。

Settings 里还有 Agent Catalog，会列出 Windsurf、Kiro、VS Code Copilot、Cline、Roo Code、Kilo Code、Continue、Aider、Amp、OpenHands、Zed AI 等常见工具。没有 native adapter 的工具会作为 manual preset 展示，用户可以一键把它们注册成 custom agent 来追踪 instruction file。

手动新增入口在 Settings -> Agent Catalog -> Add agent。这适合新工具还没出现在内置列表、或者你的工具路径和预设不同的情况。

工作原理

Plexus 把 canonical config 放在 ~/.config/plexus/：

~/.config/plexus/
├── config.yaml
├── team/
├── personal/
│   ├── mcp/servers.yaml
│   ├── rules/global.md
│   └── skills//SKILL.md
├── .cache/mcp/
└── backups/

team/ 层设计为来自共享 Git repo。personal/ 层属于本机用户，并且会覆盖同 ID 的 team entry。

对于 Cursor、Factory Droid 这类单用途 MCP 文件，Plexus 会优先使用 symlink。对于 ~/.claude.json、~/.codex/config.toml、~/.gemini/settings.json、~/.qwen/settings.json、~/.dsh/mcp.json 和 ~/.config/opencode/opencode.json 这种共享原生文件，Plexus 只 partial-write MCP section。

Team Starter Repo

可以直接用 miniLV/agent-primer 作为第一份团队基线。它包含：

- rules/global.md：共享的 agent 行为准则
- skills//SKILL.md：团队可复用 skills
- mcp/servers.yaml：团队认可的 MCP servers

plexus join https://github.com/miniLV/agent-primer.git
plexus pull
plexus sync

也可以在 dashboard 里操作：打开 Team，点击 使用 agent-primer，再点击 加入。如果这个 repo 是 private，确保本机 GitHub credential 可用，或者改用 SSH URL：git@github.com:miniLV/agent-primer.git。

这条命令会把 agent-primer clone 到 ~/.config/plexus/team/。之后 Plexus 会把它当作 team layer，再叠加你本机的 ~/.config/plexus/personal/：

agent-primer repo
rules/global.md        -> Plexus Team Rules
skills/*/SKILL.md      -> Plexus Team Skills
mcp/servers.yaml       -> Plexus Team MCP

local machine
~/.config/plexus/team/     # git clone of agent-primer
~/.config/plexus/personal/ # your overrides, secrets, local paths

举个例子：团队把 code-review skill 加进 agent-primer，所有成员只需要执行 plexus pull && plexus sync，这个 skill 就会进入 Claude Code、Cursor、Codex 等已启用 agent 的 skill 目录。团队把 github MCP 留成 optional placeholder；个人需要时，在 Plexus 的 MCP 页面启用它，并在 personal layer 里补自己的 token。

注意：team repo 里的 MCP 如果依赖个人 token、本机路径或数据库连接，应该先保持 placeholder / optional，再由个人在 ~/.config/plexus/personal/ 里覆盖或补全。

Skill Market

打开 Skill Market，可以浏览来自 GitHub 社区的 Agent Skills，按星标排行，并支持自由搜索和翻页（最多 5 页）。点一个技能的 Install，Plexus 会：

1. 下载该 repo 的 tarball 并解压到临时目录；
2. 找到 SKILL.md（优先根目录），读取 frontmatter 作为技能名称和描述；
3. 把 SKILL.md 以及同目录的 scripts/、references/、assets/ 等资源写进 ~/.config/plexus/personal/skills//；
4. 在写入原生文件前创建 snapshot，然后同步到所有已启用 agent。

一次安装即可在所有支持的 agent（Claude Code、Cursor、Codex、Gemini CLI、Qwen Code、Factory Droid、DeepSeek Harness、OpenCode）里通用。

已安装的技能会显示 Installed。如果某个 repo 不是单技能仓库（没有 SKILL.md，或包含多个技能），安装会返回清晰的提示而不会写坏配置。

市场数据来自 GitHub Search API，按 star 数降序排列。未配置 token 时有速率限制；设置 GITHUB_TOKEN（或让本机 gh 已登录）即可自动提高限额。

CLI

plexus              start the dashboard
plexus start -p 7777
plexus detect       list detected agents
plexus join    clone a team config repo into ~/.config/plexus/team
plexus pull         pull the configured team repo
plexus sync         union Plexus + native config and apply to enabled agents
plexus sync --prefer codex   use Codex only to resolve native-native conflicts
plexus status       show team subscription and sync status
plexus help

安全模型

- Plexus 是 local-first。
- Plexus 不执行 MCP Server。
- 每次写入 agent 原生文件前都会创建 snapshot。
- 共享配置文件采用 partial-write，只改 Plexus 管理的 MCP section。
- 专用 MCP 文件优先使用 symlink/copy，写入前会 quarantine 原文件。
- Debug snapshots 只返回 metadata，不返回文件内容。
- 导入的 MCP env 会以明文存在本地 personal store。
- 不要在没有审查和脱敏的情况下，把 ~/.config/plexus/personal/ 推到团队 repo。

开发

npm ci
npm run verify

常用命令：

npm run check
npm run test:core
npm run build --workspace=plexus-agent-config-core
npm run build --workspace=plexus-agent-config-web

当前状态

Plexus 仍处于 alpha 阶段。本地工作流已经可以在 macOS 和 Linux 上使用，但仍有一些限制：

- 暂不管理 project-scoped MCP 文件
- Dashboard 里的 team config PR proposal 还没做
- Custom agents 目前只是 instruction-file registry records
- Rules apply 当前只覆盖内置 agents
- Windows 支持还未验证

License

Apache-2.0