Universal Skill & MCP Sync Engine for AI Coding Agents.
Google Antigravity, Claude Code, and OpenAI Codex each keep their own private copy of your custom Skills, MCP servers, and project rules - in different folders, different file formats, none of them aware the others exist. Add a skill or an MCP server to one, and it's invisible to the rest until you copy it over by hand, every time, per agent.
AgentBridge fixes that with one shared hub (~/.agentbridge/skills
) that every agent's own skills folder links to directly via a native OS symlink/junction - no daemon, no polling, no elevated privileges. Add a skill once, it's instantly available everywhere. MCP servers and project rules (AGENTS.md
→ CLAUDE.md
/GEMINI.md
/etc.) get merged and mirrored the same way with a single command instead of four manual edits.
flowchart TD
CLI[agentbridge CLI / SDK]
subgraph Core Engine
Detector[Client Detector]
SkillLinker[Skill Linker & Hub]
MCPSync[MCP Synchronizer]
Rules[Rule Consolidator]
Doctor[Health Diagnostics]
Rollback[Backup & Rollback]
Watcher[Live File Watcher]
end
CLI --> Detector
Detector -.detects installed agents.-> SkillLinker
Detector -.detects installed agents.-> MCPSync
CLI --> SkillLinker
CLI --> MCPSync
CLI --> Rules
CLI --> Doctor
CLI --> Rollback
CLI --> Watcher
Watcher -.logs change, hub is already live via the link.-> SkillLinker
Watcher -->|debounced auto-sync| Rules
SkillLinker <== "Junction / Symlink" ==> Hub[(~/.agentbridge/skills Hub)]
Hub <== "Junction / Symlink" ==> G[Google Antigravity<br/>~/.gemini]
Hub <== "Junction / Symlink" ==> C[Claude Code / Desktop<br/>~/.claude]
Hub <== "Junction / Symlink" ==> O[OpenAI Codex<br/>~/.codex]
MCPSync <== "Merge JSON" ==> G
MCPSync <== "Merge JSON" ==> C
MCPSync <== "Merge TOML" ==> O
Rules -->|source of truth| AGENTS[AGENTS.md]
AGENTS -->|sync| CLAUDEMD[CLAUDE.md]
AGENTS -->|sync| GEMINIMD[GEMINI.md]
AGENTS -->|sync| CODEXMD[CODEX.md]
AGENTS -->|sync| CURSORRULES[.cursorrules]
AGENTS -->|sync| COPILOT[.github/copilot-instructions.md]
Rollback -.snapshot before write.-> MCPSync
Rollback -.snapshot before write.-> Rules
Doctor
reads across the hub and all 3 agents for diagnostics but writes nothing on its own (--fix
repairs broken links directly via the same cross-platform link helper SkillLinker
uses, not by calling into SkillLinker
itself), so it has no outgoing edges above. SkillLinker
's own pre-link backup (see link-skills
below) is a separate mechanism from Rollback
- that's why no edge connects them.
Key safety properties baked into every write path: automatic pre-write backups (link-skills
, sync-mcp
, sync-rules
- see the Commands section below for exactly which mechanism each uses and how to restore), and secrets are never persisted in plain text if an equivalent OS environment variable already exists (see the Secret Redaction note under
sync-mcp
).
Skills are shared; MCP servers are copied - and that's deliberate, not a shortcut. A skill is an isolated unit on disk (a folder with SKILL.md
and nothing else mixed in), so every agent's skills directory can just be a symlink/junction into the same hub folder - genuinely one file, visible under multiple paths. Editing it anywhere changes it everywhere instantly, with no sync step needed (link-skills
only has to run once, to create the links).
An MCP server definition can't work the same way: it's one field inside a much larger config file that also holds each agent's own unrelated settings (Claude's own preferences, Codex's own settings, etc.) - a symlink only works at the whole-file level, and symlinking the entire file would leak one agent's unrelated settings into another's. So sync-mcp
copies the merged definition into each agent's config separately - a real, independent copy per agent (plus one more in the hub's own ~/.agentbridge/mcp_servers.json
registry, used as a merge source). The tradeoff: MCP servers only stay in sync at the moment you run sync-mcp
(or an agent gets re-synced by link-skills
/doctor --fix
) - edit one agent's server definition by hand and the others won't know until the next sync. doctor
and sync-mcp
both detect and warn when two agents have drifted into disagreeing about the same server (see the MCP Server Conflict Detection note under sync-mcp
in Commands, below) so drift doesn't go unnoticed between syncs.
Requirements: Node.js ≥18.0.0.
Run directly without installing, using npx
:
npx @helter/agentbridge status # See what's detected - read-only, changes nothing
npx @helter/agentbridge link-skills # Merge skills into the hub, link every agent to it
npx @helter/agentbridge sync-mcp # Merge and mirror MCP servers across agents
npx @helter/agentbridge doctor # Health check
Or install globally for a shorter command:
npm install -g @helter/agentbridge
agentbridge status
Most commands accept --hub <path>
to override the default ~/.agentbridge/skills
hub location.
| # | Command | What it does | Key options |
|---|---|---|---|
| 1 | status |
||
| Overview: detected agents, skill counts, MCP server counts, hub link status | --json , --hub |
||
| 2 | pick (alias import ) |
||
| Interactively choose which skills/MCPs to import | --target , --hub |
||
| 3 | link-skills |
||
| Merge existing skills into the hub, link every agent to it | --dry-run , --no-backup , -y , --hub |
||
| 4 | sync-mcp |
||
| Merge & mirror MCP servers across all agent configs | --output , --dry-run , -y |
||
| 5 | sync-rules |
||
Sync AGENTS.md to CLAUDE.md /GEMINI.md /CODEX.md /.cursorrules /copilot |
|||
--mode , --cwd , -y , --no-backup |
|||
| 6 | add-skill <name> |
||
| Scaffold a new skill directly in the hub | --desc , --tags , --author , --hub |
||
| 7 | doctor |
||
| Health check: broken links, exposed secrets, name/MCP-server conflicts | --fix , --hub |
||
| 8 | unlink |
||
| Disconnect agents from the hub, restore standalone copies | --no-restore , -y |
||
| 9 | rollback |
||
| List or restore automatic backup snapshots | --list , <snapshot-id> |
||
| 10 | watch |
||
Live auto-sync for the skills hub and AGENTS.md |
|||
--cwd |
Common flags (same meaning everywhere they appear):
| Flag | Meaning |
|---|---|
-y , --yes |
|
| Skip the confirmation prompt | |
--dry-run |
|
| Preview what would happen, write nothing to disk | |
--no-backup |
|
| Skip the automatic pre-write backup for this run | |
--hub <path> |
|
Use a different hub directory instead of ~/.agentbridge/skills |
|
--json |
|
Machine-readable output instead of the formatted table (status only) |
Scans the system and presents an ASCII table overview of all installed AI coding agents, skills counts, hub linking status, and configured MCP servers.
agentbridge status
agentbridge status --json # Output machine-readable JSON
Interactively multiselect which skills, commands, or MCP servers to import into your active environment.
agentbridge pick
agentbridge pick --target ./my-skills # Import into a custom directory instead of the default hub
Migrates existing skills into the central hub (~/.agentbridge/skills
) without data loss, then creates transparent directory junctions (Windows) or symbolic links (macOS/Linux).
agentbridge link-skills
agentbridge link-skills --dry-run # Preview actions without modifying disk
agentbridge link-skills --no-backup # Skip the pre-link snapshot backup
agentbridge link-skills -y # Skip confirmation prompt
Note (partial failure):if linking fails partway through more than one agent, the error names which agent actually failed, which agents were already processed before it (their skills may already be merged into the hub), and recommends runningagentbridge doctor
to check the current state before retrying.
Safely reads MCP server declarations across all detected client configuration files, deep-merges environment variables, command arguments, and server keys, then mirrors them across all agents.
agentbridge sync-mcp
agentbridge sync-mcp --output ./mcp-unified.json # Export merged config to standalone file
agentbridge sync-mcp --dry-run # Preview the merge without writing to disk
agentbridge sync-mcp -y
Secret Redaction:sync-mcp
never writes a plain-text secret to disk if it doesn't have to. Before writing any agent config, it checks eachenv
value against your current OS environment variables - if a value exactly matches one (e.g.GITHUB_PERSONAL_ACCESS_TOKEN
), it writes${GITHUB_PERSONAL_ACCESS_TOKEN}
instead of the literal value. Set the variable once:
[System.Environment]::SetEnvironmentVariable('GITHUB_PERSONAL_ACCESS_TOKEN', 'your-token', 'User')
export GITHUB_PERSONAL_ACCESS_TOKEN=your-token
then run
agentbridge sync-mcp
again - any agent's config still holding the literal value gets rewritten to the${VAR}
reference automatically, no matter how many agents you have.agentbridge doctor
flags any plain-text secret it finds (with this same fix in its warning text) but never sets an OS environment variable on your behalf - that's a real side effect on your machine only you should trigger, and only you know the right value.
MCP Server Conflict Detection:if two agents independently define a server with the same name but genuinely differentcommand
,args
, or an overlappingenv
key with a different value,sync-mcp
merges them field-by-field - the later-processed agent's value silently wins on the fields that actually conflict (an env key present in only one side isn't a conflict; both survive).sync-mcp
prints a warning naming the server, which fields disagreed, and which agents disagreed;agentbridge doctor
reports the same thing as a persistent check ("MCP Server Conflicts") so it shows up even between syncs. Neither auto-resolves it - only you know which agent's definition should actually win. Re-runsync-mcp
after fixing the losing agent's config directly, or edit the merged result viasync-mcp --output
.
Synchronizes project-level agent rules. Reads AGENTS.md
as the single source-of-truth and mirrors or symlinks it to CLAUDE.md
, GEMINI.md
, CODEX.md
, .cursorrules
, and .github/copilot-instructions.md
.
agentbridge sync-rules
agentbridge sync-rules --mode symlink # Create symlinks instead of auto-sync copies
agentbridge sync-rules --cwd ./my-repo
agentbridge sync-rules -y # Skip confirmation prompt
agentbridge sync-rules --no-backup # Skip snapshotting existing target files before overwriting
Note (creating a real file symlink requires Developer Mode or an elevated shell. Without either, AgentBridge transparently falls back to a hardlink, which stays in sync when--mode symlink
on Windows):AGENTS.md
is edited in place but can go stale if it's replaced outright (e.g. some editors' "atomic save" does a delete + rewrite). The CLI output tells you which one you actually got (Symlinked to source
vsHardlinked to source
) - if you see the latter and need true symlinks, enable Developer Mode or run as admin, then re-run the command.
Scaffolds a new skill directory in the central hub with a standard SKILL.md
template containing YAML frontmatter.
agentbridge add-skill database-migration --desc "Automated PostgreSQL schema migration recipes" --tags db,sql,migrations --author "Your Name"
Runs health diagnostics: audits plain-text tokens and secrets in MCP configs, detects skill name collisions and same-named MCP servers with conflicting definitions across agents, checks junction integrity, and repairs broken links with --fix
.
agentbridge doctor
agentbridge doctor --fix # Automatically repair broken links and missing folders
Note (exit codes):without--fix
, any warning or error in the report exits1
(broken links, exposed secrets, and skill-name collisions are all reported atwarning
severity, so this catches them too) - soagentbridge doctor && deploy
stops before a real problem. With--fix
, the exit code reflects the repair pass instead and is0
once it has run.
Safely disconnects agents from the central hub, removing junctions/symlinks and restoring independent directories with copies of hub skills.
agentbridge unlink
agentbridge unlink --no-restore # Disconnect without copying hub skills back
agentbridge unlink -y # Skip confirmation prompt
Lists timestamped backup snapshots from ~/.agentbridge/backups/
and restores configurations to an earlier state.
agentbridge rollback
agentbridge rollback --list # List all available snapshots
agentbridge rollback snapshot-1787674932079 # Restore a specific snapshot directly by ID
Starts a lightweight live file watcher that monitors the central skills hub and workspace AGENTS.md
, automatically synchronizing changes in real time.
agentbridge watch
agentbridge watch --cwd ./my-repo # Watch a specific project root instead of the current directory
| AI Coding Agent | Config Directory | Skills Directory | MCP Config Path | Rules Target |
|---|---|---|---|---|
| Google Antigravity | ||||
~/.gemini/config |
||||
~/.gemini/config/skills |
||||
mcp_config.json |
||||
GEMINI.md |
||||
| Claude Code | ||||
~/.claude |
||||
~/.claude/skills |
||||
claude_desktop_config.json |
||||
CLAUDE.md |
||||
| OpenAI Codex | ||||
~/.codex |
||||
~/.codex/skills |
||||
config.toml |
||||
CODEX.md |
||||
| — | — | — | — | .cursorrules (Cursor is a sync-rules target only for now - it isn't skill/MCP-managed like the 3 agents above) |
| — | — | — | — | .github/copilot-instructions.md (GitHub Copilot is a sync-rules target only - it isn't skill/MCP-managed like the 3 agents above) |
| Operating System | Skills Linking Strategy | Administrator Privileges Required? | Status |
|---|---|---|---|
| macOS (Apple Silicon / Intel) | |||
POSIX Symbolic Links (dir ) |
|||
| No | Supported | ||
| Linux (Ubuntu / Fedora / Arch) | |||
POSIX Symbolic Links (dir ) |
|||
| No | Supported | ||
| Windows 10 / 11 | |||
NTFS Directory Junctions (junction ) |
|||
| No | Supported |
You can import and use @helter/agentbridge
directly in Node.js / TypeScript code:
import {
detectInstalledAgents,
linkAgentsToHub,
syncMcpConfigs,
syncProjectRules,
runDiagnostics,
} from '@helter/agentbridge';
// 1. Detect installed agents
const agents = await detectInstalledAgents();
// 2. Link skills to central hub
const linkSummary = await linkAgentsToHub(agents);
// 3. Mirror MCP configs
const mcpSummary = await syncMcpConfigs(agents);
// 4. Run diagnostics
const report = await runDiagnostics();
git clone https://github.com/Helter5/agentbridge.git
cd agentbridge
npm install
npm test
npm run test:coverage
npm run build
node dist/cli.js status
MIT (c) AgentBridge Contributors