@sofatutor/agent-bridge

Agent Bridge

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.).

Why Agent Bridge?

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.

Prerequisites

• Git (optional — needed only for remote sources)
• Node.js ≥ 18

Installation

npm install -g @sofatutor/agent-bridge

Or install locally as a dev dependency:

npm install --save-dev @sofatutor/agent-bridge

Or run directly with npx:

npx @sofatutor/agent-bridge init

Quick Start

1. Initialize

agent-bridge init

The 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.

Non-Interactive Mode

Pass --tools and --source to skip all prompts:

agent-bridge init \
  --tools cursor,vscode,claude \
  --source https://github.com/org/repo.git#main

Multiple sources and custom tools are supported:

agent-bridge init \
  --domains shared,backend \
  --tools cursor,windsurf:.windsurf \
  --source https://github.com/org/repo.git#main \
  --source /local/path \
  --hooks

Option	Description
--tools <list>	Comma-separated tool names (cursor, vscode, claude) or name:folder pairs
-s, --source <url>	Source URL or path (repeatable). Append #branch for a specific branch
--domains <list>	Comma-separated domain list (default: backend,frontend,shared)
--hooks	Auto-install git hooks without prompting

After init, commit .agent-bridge/config.yml to your repo.

2. Sync

agent-bridge sync

Fetches 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.

3. Update

agent-bridge update

Pulls the latest changes from all remote sources. Local sources require no update.

After updating, run agent-bridge sync to reconcile features.

4. Opt Out

agent-bridge opt-out

opt-out is non-interactive and removes Agent Bridge from the current repository by:

• Removing synced feature and tool-root entries tracked in .agentbridge manifests
• Removing Agent Bridge-managed git hooks (post-checkout, post-merge)
• Removing config.yml and cloned sources from .agent-bridge/
• Leaving a .agent-bridge/optout tombstone behind so a postinstall guard won't silently reinstall

Notes:

• Root files like AGENTS.md, CLAUDE.md, and SYSTEM.md are not removed by opt-out.
• Existing non-Agent-Bridge hooks are preserved.
• The tombstone lives at .agent-bridge/optout and is gitignored by default, so opt-out is local to your machine. Force-add it (git add -f .agent-bridge/optout) to commit a repo-wide opt-out.
• While the tombstone exists, agent-bridge init and agent-bridge sync are no-ops.
• To re-enable, run agent-bridge init --force (which clears the tombstone) or delete .agent-bridge/optout.

Opting out with a postinstall hook

If a project auto-installs Agent Bridge via postinstall, guard it on .agent-bridge:

"postinstall": "test -d .agent-bridge || (npx agent-bridge init --domains … --tools … --source … --hooks && npx agent-bridge sync) || true"

Because opt-out keeps the .agent-bridge/ directory (holding only the tombstone), test -d .agent-bridge stays true after opting out and the guard short-circuits — nothing is reinstalled. If your guard invokes init/sync directly instead, they still no-op on the tombstone.

Git Hooks (Auto-Sync)

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 merge or git pull

These hooks run agent-bridge update && agent-bridge sync in the background, so your workflow isn't blocked.

How It Works

The hooks execute asynchronously with a short delay to let Git complete its operations. They:

• Check if agent-bridge is available globally
• Fall back to npx @sofatutor/agent-bridge if not
• Run update and sync silently in the background

Skipping Existing Hooks

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 &

Removing Hooks

Agent Bridge marks its hooks with a special comment.

Recommended: run agent-bridge opt-out to remove Agent Bridge-managed hooks and state.

Manual alternative: delete the hook files:

rm .git/hooks/post-checkout .git/hooks/post-merge

Or re-run agent-bridge init — Agent Bridge hooks are automatically updated on re-init.

CLI Commands

Command	Description
agent-bridge init	Interactive setup — creates .agent-bridge/config.yml (supports non-interactive mode)
agent-bridge sync	Fetch sources, discover features, reconcile files
agent-bridge update	Fetch latest changes for all remote sources
agent-bridge opt-out	Non-interactive cleanup of Agent Bridge-managed state

Global Options

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

Documentation

• 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

Troubleshooting

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
Remove Agent Bridge from repo	Run agent-bridge opt-out

Development

npm install
npm run build       # Package the CLI with Vite+
npm test            # Run all tests
npm run test:watch  # Watch mode