AgentBridge – sync skills/MCP servers across Claude Code, Codex, Antigravity

AgentBridge, a new open-source tool, synchronizes custom skills, MCP servers, and project rules across Google Antigravity, Claude Code, and OpenAI Codex using a shared hub at ~/.agentbridge/skills with native OS symlinks, eliminating manual copying. The tool merges MCP server definitions into each agent's config files and consolidates project rules from AGENTS.md into CLAUDE.md, GEMINI.md, CODEX.md, .cursorrules, and .github/copilot-instructions.md, with automatic pre-write backups and secret redaction.

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 running agentbridge 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 each env 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: Windows PowerShell System.Environment ::SetEnvironmentVariable 'GITHUB PERSONAL ACCESS TOKEN', 'your-token', 'User' macOS/Linux - add to your shell profile ~/.zshrc, ~/.bash profile, ... 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 different command , args , or an overlapping env 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-run sync-mcp after fixing the losing agent's config directly, or edit the merged result via sync-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 vs Hardlinked 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 exits 1 broken links, exposed secrets, and skill-name collisions are all reported at warning severity, so this catches them too - so agentbridge doctor && deploy stops before a real problem. With --fix , the exit code reflects the repair pass instead and is 0 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: js 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 ; Clone repository git clone https://github.com/Helter5/agentbridge.git cd agentbridge Install dependencies npm install Run Vitest test suite npm test Run tests with code coverage npm run test:coverage Build TypeScript binary npm run build Run local CLI node dist/cli.js status MIT c AgentBridge Contributors