A CLI tool that syncs AI agent configurations (skills, agents, prompts, ...etc.) from shared sources into your project's tool directories (.github/, .cursor/, .claude/, ..etc.).
As teams adopt AI coding tools, agent instructions quickly scatter across projects with no shared structure. Agent Bridge solves this by letting you centralize and distribute AI agent features across any number of projects, teams, and repositories — using conventions over configuration, with no manifests or mapping files required.
- Convention over configuration — features are discovered from the filesystem automatically. No manifests, no mapping files — just organize by domain and feature type.
- Tool-agnostic, tool-aware — syncs to all configured tools by default, while the
<tool>--prefix convention lets you target features to specific tools (VS Code, Cursor, Claude Code, or custom tools) when needed. - Extensible — not limited to skills, agents, prompts, or instructions. Any new feature type that tools introduce is automatically supported — just add a folder to your source.
- Multiple sources — pull from any combination of Git repositories (HTTPS/SSH) and local paths. Mix company-wide standards with team-specific or project-specific sources.
- Multi-domain organization — structure features by domain (
backend,frontend,shared, or your own) so each project pulls only what it needs. - Non-destructive — previously defined skills, agents, prompts, and other tool files are never touched, modified, or deleted.
- Git (optional — needed only for remote sources)
- Node.js ≥ 18
npm install -g @sofatutor/agent-bridgeOr install locally as a dev dependency:
npm install --save-dev @sofatutor/agent-bridgeOr run directly with npx:
npx @sofatutor/agent-bridge initagent-bridge initThe interactive init flow will:
- Ask which domains to use (e.g.
backend,frontend,shared). - Ask which tools to configure — choose from well-known presets (VS Code, Cursor, Claude) or add custom tools.
- Ask for sources — Git repos (HTTPS/SSH) or local paths, with optional branch.
- Generate
.agent-bridge/config.yml. - Clone any remote sources.
- Create
.agent-bridge/.gitignore(ignores cloned repos, keeps config). - Optionally install git hooks to auto-sync on checkout/merge.
After init, commit .agent-bridge/config.yml to your repo.
agent-bridge syncFetches remote sources, discovers features, and copies them into your tool folders.
Run this whenever:
- A source repository has new or changed features.
- You add, rename, or remove sources in
config.yml. - You change tool or domain configuration.
agent-bridge updatePulls the latest changes from all remote sources. Local sources require no update.
After updating, run agent-bridge sync to reconcile features.
When running agent-bridge init inside a Git repository, you'll be prompted to install git hooks that automatically keep your AI agent configurations up to date. If enabled, Agent Bridge installs:
- post-checkout — runs after
git checkout(switching branches) - post-merge — runs after
git mergeorgit pull
These hooks run agent-bridge update && agent-bridge sync in the background, so your workflow isn't blocked.
The hooks execute asynchronously with a short delay to let Git complete its operations. They:
- Check if
agent-bridgeis available globally - Fall back to
npx @sofatutor/agent-bridgeif not - Run update and sync silently in the background
If you already have custom post-checkout or post-merge hooks, Agent Bridge will skip them to avoid conflicts. You can manually integrate Agent Bridge into your existing hooks by adding:
# At the end of your existing hook
(
sleep 1
agent-bridge update && agent-bridge sync
) >/dev/null 2>&1 &Agent Bridge marks its hooks with a special comment. To remove them, delete the hook files:
rm .git/hooks/post-checkout .git/hooks/post-mergeOr re-run agent-bridge init — Agent Bridge hooks are automatically updated on re-init.
| Command | Description |
|---|---|
agent-bridge init |
Interactive setup — creates .agent-bridge/config.yml |
agent-bridge sync |
Fetch sources, discover features, reconcile files |
agent-bridge update |
Fetch latest changes for all remote sources |
| Option | Description |
|---|---|
--cwd <path> |
Override the working directory. Defaults to the Git root, or cwd if not in a Git repo. |
Examples:
# Run sync for a specific project in a monorepo
agent-bridge sync --cwd ./packages/api
# Point at a project outside the current directory
agent-bridge sync --cwd /path/to/my-project- Configuration — config file reference, fields, source types
- Conventions — source directory structure, tool-prefix routing, authoring features
- Sync Strategy — marker files, project structure after sync, cleanup behavior
| Symptom | Fix |
|---|---|
config.yml not found |
Run agent-bridge init from the repo root |
| Source clone failed | Check the Git URL and your SSH/HTTPS credentials |
| Duplicate feature name error | Rename one of the conflicting features across sources |
| Local source path not found | Verify the path in config.yml is correct relative to the repo root |
| Path conflict error | A non-managed folder exists at the destination — rename or remove it |
| Git hooks not installed | Run agent-bridge init from inside a Git repository |
| Hooks skipped (existing) | Existing non-Agent-Bridge hooks are preserved; integrate manually |
npm install
npm run build # Package the CLI with Vite+
npm test # Run all tests
npm run test:watch # Watch mode