agentbrew

A skill manager and sync engine for AI coding agents, written in TypeScript.

The problem

Most developers now use 2-4 AI coding tools — Claude Code, Cursor, Windsurf, Copilot, Codex — and every tool stores its config differently: JSON here, TOML there, YAML somewhere else. Add an MCP server? Edit 4 files. Add a skill? Copy it to 4 directories. Joined a team? Manually replicate everyone's setup. Something silently breaks? Nobody notices until a tool stops working.

AgentBrew fixes this. One source of truth, synced to every tool, with drift detection that auto-repairs broken config. Works for solo developers with multiple tools and for teams that need a shared baseline.

Highlights

• A single tool to manage skills, MCP servers, rules, and commands across 45+ agents — Claude Code, Cursor, Windsurf, Devin, Codex, Goose, Kiro, Amp, and more.
• Installs a skill or MCP server once and deploys it to every agent in every native format (JSON, TOML, YAML, symlinks).
• Background drift detection catches config changes and auto-repairs them every 30 minutes.
• Declarative Agentfile (like Brewfile or package.json) lets you commit your agent setup to git.
• Never destroys data it didn't create. Manual edits, extra fields, and user-added servers survive every sync.
• Catalog of 150+ items — 130+ skills, 15+ MCP servers, 5 rule sets — curated from Vercel, Anthropic, obra/superpowers, Supabase, Trail of Bits, slavingia/skills, awesome-design-md, and more.

Installation

npx agentbrew           # try it — detects agents, discovers config, installs recommended set

npm install -g agentbrew   # or install globally for faster startup + tab completion

Requires Node.js 20.11+ and git.

First run: On an interactive terminal, agentbrew auto-runs init — detects agents, installs recommended items, and sets up background drift repair. In non-interactive environments (CI, pipes, scripts), it prints help instead. Opt out of auto-init with AGENTBREW_NO_AUTO_INIT=1.

Features

Install skills and MCP servers

Install from the catalog or from anywhere else. Everything you install — catalog or custom — syncs to all 45+ agents identically. There's no second-class citizen.

# From the catalog (150+ curated items)
agentbrew install debug                  # skill (global — all agents get it)
agentbrew install debug --local          # project-local — only this repo
agentbrew install context7               # MCP server
agentbrew install --recommended          # all recommended skills + MCP servers + rules

MCP servers that need credentials (Jira, Slack, GitHub, etc.) print per-token instructions immediately after install. Run the setup wizard to fill them in interactively — it shows where to get each token and saves to your shell config:

agentbrew install atlassian      # deploys Jira + Confluence MCP to all agents
agentbrew setup atlassian        # guided wizard → token instructions + saves to ~/.zshenv.secrets

# From any npm package (auto-detected as MCP server)
agentbrew install @anthropic/mcp-proxy
agentbrew install @modelcontextprotocol/server-github

# From any command (your own server, any language)
agentbrew install sqlite -- uvx mcp-server-sqlite
agentbrew install my-api -- python3 ./server.py

# From a URL (SSE/HTTP transport)
agentbrew install api --url https://api.example.com/mcp

# From a git repo (cloned, built, entrypoint auto-detected)
agentbrew install --git https://github.com/org/mcp-server

# From a GitHub skill repo (adds as a skill source)
agentbrew install vercel-labs/skills

How sync works: Every registered item (catalog or custom) is stored in your Agentfile. On agentbrew sync, each item is translated to every agent's native format — JSON for Cursor/Claude, TOML for Codex, YAML for Goose, symlinks for skills. Custom servers get the same drift detection and auto-repair as catalog ones.

Install scopes: By default, install is global — the skill goes to every agent. Use --local (or --project) to install into the current repo's .agentbrew/skills/ directory instead. Local skills are checked into version control and only activate when agents work in that repo — ideal for project-specific conventions or team-shared skills.

Remove anything:

agentbrew remove context7   # auto-detects type, removes from all agents

Browse what's available:

agentbrew catalog                      # interactive browser
agentbrew catalog --search security    # search across all sources

Want to add something to the catalog? See CONTRIBUTING.md.

Agentfile

A declarative manifest you commit to your repo — like Brewfile for Homebrew. Catalog items use shorthand names. Custom servers use the full spec. Both sync identically.

# Agentfile.yaml
recommended: true               # install all curated defaults (recommended skills + servers + rules)

mcp:
  # Catalog items — just the name, agentbrew knows the command
  - context7
  - playwright

  # Custom server — full spec, same sync as catalog items
  - name: my-server
    command: npx
    args: [tsx, ./mcp-server.ts]
    env:
      API_KEY: ${API_KEY}       # substituted from shell env at sync time

  # URL-based server (SSE/HTTP transport)
  - name: remote-api
    url: https://api.example.com/mcp
    headers:
      Authorization: Bearer ${TOKEN}

skills:
  - semgrep
  - codeql
  - property-based-testing

sources:
  - vercel-labs/skills           # GitHub skill repos
  - trailofbits/skills

rules: ./shared-rules.md        # file path (relative to Agentfile) or inline text
commands:
  - ./.claude/commands          # optional extra command source dirs for this repo

hooks:
  - event: PreToolUse             # agent lifecycle hooks (Claude Code)
    command: "bash /path/to/hook.sh"
    matcher: "Bash"               # optional tool name filter
  - event: Stop
    type: prompt
    prompt: "Append session summary to log"

Keys:

| Key | Type | Description | |-----|------|-------------| | mcp | list | MCP servers — catalog shorthand names or full specs with command/args/env/url | | skills | list | Catalog skill names to install | | sources | list | GitHub repos or URLs to add as skill sources | | rules | string | Inline rules text (rules: \|) or path to a rules file (rules: ./file.md) | | commands | list | Extra command source dirs to merge during sync | | hooks | list | Agent lifecycle hooks — event, command/prompt, optional matcher (Claude Code; other agents as supported) | | recommended | bool | Install all recommended items (skills + MCP servers + rules) |

${VAR} values are substituted from your shell environment at sync time. ${VAR:-default} provides a fallback.

Generate one from your current setup, or let an agent create one for you:

agentbrew init --from-state          # generate from existing agentbrew state

Agents with the agentfile-init skill (installed by default) will automatically offer to create a project Agentfile when they enter a repo without one.

Global vs. project Agentfile

The global Agentfile (~/.config/agentbrew/Agentfile.yaml) is authoritative — items you remove from it are removed from state on next sync. The project Agentfile (in cwd) is additive — it can only add items for that repo, never remove your global config.

If a project commands: directory and the global ~/.config/agentbrew/commands directory contain the same filename, the later source wins. In practice that means project commands override the global copy, and sync prints a warning so the collision is visible.

install and remove always update the global Agentfile, similar to how npm install updates package.json. Use --project for a project-scoped Agentfile instead.

Dotfiles workflow

Point sync at an Agentfile outside the current directory — ideal for dotfiles repos:

agentbrew sync --agentfile ~/dotfiles/Agentfile.yaml

Or symlink it as your global Agentfile for automatic use on every sync:

ln -sf ~/dotfiles/Agentfile.yaml ~/.config/agentbrew/Agentfile.yaml

Sync

Translates one source of truth into each agent's native format:

• MCP Servers → JSON (Cursor, Claude), TOML (Codex), YAML (Goose)
• Rules → marker-injected sections in each agent's rules file
• Skills → symlinks into each agent's skills directory
• Commands → Markdown auto-transformed per agent
• Hooks → lifecycle hooks written to settings.json (Claude Code; other agents as supported)
• Instructions → templates/AGENTS.md deployed to every agent's instruction file (CLAUDE.md, Windsurf memories, Augment guidelines, Codex AGENTS.md, etc.), with automatic deduplication against managed rules so nothing is repeated

agentbrew sync                  # deploy + prune stale items (the one healing command)
agentbrew sync --pull           # fetch latest from sources first, then deploy
agentbrew sync --no-prune       # keep stale items in agent configs
agentbrew sync --dry-run        # preview without applying
agentbrew sync --rollback       # restore from last pre-sync snapshot

Every sync creates a timestamped snapshot. Pruning only touches entries agentbrew deployed — user-added items are always preserved.

Drift detection

A background scheduler (LaunchAgent / systemd / cron) runs agentbrew fix every 30 minutes. If an agent update or manual edit breaks your config, it gets re-synced automatically. You can also repair drift manually:

agentbrew sync                 # deploy + repair drift
agentbrew status               # see what's configured + drift summary
agentbrew status --fix         # detailed drift check + auto-repair
agentbrew status --ci          # exit 1 on drift (for CI pipelines)

Team config

Share a standard baseline across your team via a git repo:

# Team lead: create the config
agentbrew team init              # creates .agentbrew-team.yaml in current dir
# edit the file, push to git

# Team members: 2 commands to full setup
npm install -g agentbrew         # 1. install (auto-detects agents on first run)
agentbrew team set <repo-url>    # 2. apply team baseline (MCP servers, rules, sources)

agentbrew team sync              # pull latest baseline + apply changes
agentbrew team check             # verify your setup matches (CI-friendly: --json, exit 1 on drift)
agentbrew setup                  # configure API keys for MCP servers that need them

Or share without git:

agentbrew export -o my-setup.yaml           # portable bundle
agentbrew import --bundle my-setup.yaml      # merge on another machine

If no agents are detected on first run, install at least one: Claude Code, Cursor, Windsurf, or Devin. Then re-run agentbrew init.

Troubleshooting:

• git: command not found — install git: brew install git (macOS) or apt install git (Linux)
• Permission denied (publickey) — your SSH key isn't set up for the config repo. Run ssh-keygen -t ed25519 then add the key.
• MCP server errors after sync — run agentbrew setup <server> to configure missing tokens (guided wizard), then agentbrew sync
• agentbrew status shows drift — run agentbrew status --fix to auto-repair

Project detection

Install the shell hook to see a hint when you cd into a repo with agent assets:

agentbrew hook install --shell   # auto-detects bash/zsh/fish, < 5ms per cd

$ cd ~/apps/my-project
  ⚡ agentbrew: Agentfile + skills + MCP detected. Run `agentbrew` for details.

Validation

agentbrew lint   # validate state, Agentfile, MCP configs, rules, skills

Returns exit 1 on errors — safe for CI and pre-commit hooks.

Supported agents (45+)

Full sync (skills + MCP + rules + commands): Claude Code, Claude Desktop, Cursor, Windsurf, Devin, Gemini CLI

Skills + MCP + rules: Codex

Skills + rules: Augment

Skills + MCP + commands: OpenCode

Skills + MCP: Kiro, Amp, Goose, Cline, Roo Code, Intuit Desktop

Skills: Copilot

Skills sync (29 additional): Trae, Junie, Continue, Warp, Qwen Code, OpenHands, Kilo Code, Pi, Crush, Kode, Qoder, Zencoder, Cortex, Mux, CodeBuddy, Kimi CLI, Replit, and more

How AgentBrew compares

| | AgentBrew | skills CLI | MCPM | ai-rules-sync | block/ai-rules | skillfile | |---|---|---|---|---|---|---| | Skills sync | 45+ agents | 45+ agents | — | 10+ agents | 10+ agents | 8 agents | | MCP sync | 15+ agents | — | 10+ clients | — | Partial | — | | Rules sync | 8 agents | — | — | 10+ agents | 10+ agents | — | | Commands sync | 7 agents | — | — | 10+ agents | 10+ agents | — | | Hooks sync | 1 agent | — | — | — | — | — | | Drift detection | Auto (30 min) | — | Manual | — | Manual | — | | Auto-repair | Yes | — | — | — | — | — | | Catalog | 150+ items | skills.sh | mcpm.sh | — | — | 110K+ skills | | Declarative config | Agentfile | — | — | JSON | Markdown dir | Skillfile | | Lock file | SHA pinning | Yes (v3) | — | — | — | Yes (SHA + patches) | | Team config | Yes | — | — | — | — | — | | Export/import | Yes | — | — | — | — | — |

See docs/COMPETITION.md for the full analysis.

Refresh competition docs safely with npm run docs:competition after updating docs/competition-snapshot.json. The sync exits non-zero if handwritten docs/COMPETITION.md prose still contains stale tracked counts, so update the surrounding narrative first instead of overwriting drift silently.

CLI reference

agentbrew                              Status dashboard (auto-init on first run)
agentbrew init [--force]               Detect agents, discover config, set up drift repair
agentbrew status [--verbose] [--json]  Show agents, servers, sources, skills, drift
agentbrew sync [--dry-run] [--no-prune] Deploy + repair drift (prunes stale items by default)
agentbrew sync --pull                  Fetch latest from sources, then deploy
agentbrew sync --agentfile <path>      Apply an Agentfile before syncing (dotfiles workflow)

agentbrew install [name]               Install from catalog, npm, source, or folder
agentbrew install @scope/pkg           Any npm package (auto-detected as MCP server)
agentbrew install srv -- <cmd> <args>  Any command as an MCP server
agentbrew install srv --url <url>      SSE/HTTP server
agentbrew install --git <url>          MCP server from a git repo (clone + build + detect)
agentbrew install user/repo            GitHub skill repo (adds as a source)
agentbrew remove [name]                Remove any item (auto-detects type)

agentbrew catalog [--search <term>]    Browse available items
agentbrew lint                         Validate all config files
agentbrew import [--from <agent>]      Discover MCP servers from agent configs
agentbrew export [-o file]             Export portable config bundle
agentbrew setup [server]               Configure API keys for MCP servers
agentbrew run [server]                 Test an MCP server locally over stdio

agentbrew team init                    Create a shareable team config in the current directory
agentbrew team set <repo-url>          Apply a team baseline (MCP, rules, sources)
agentbrew team sync                    Pull latest baseline + apply changes
agentbrew team check [--json]          Verify setup matches baseline (CI-friendly)

agentbrew upgrade [--check]            Check for / install CLI updates
agentbrew env check                    Warn about env vars that could leak across agent sessions
agentbrew env sanitize                 Print unset commands for dangerous env vars (eval $(agentbrew env sanitize))
agentbrew completions                  Shell completions (bash, zsh, fish)

agentbrew --help shows all commands grouped by category.

How config is stored

AgentBrew has two config layers:

| | Agentfile | state.yaml | |---|---|---| | Path | ~/.config/agentbrew/Agentfile.yaml (global) or ./Agentfile.yaml (project) | ~/.config/agentbrew/state.yaml | | What's in it | What you want: MCP servers, skills, sources, rules | What agentbrew discovered: detected agents, resolved paths, source metadata, catalog version | | Who edits it | You (or agents via install/remove) | Agentbrew only — never edit by hand | | Commit to git? | Yes — this is your portable config | No — machine-specific cache, always regenerated | | Scope | Global (your machine baseline) + per-project (repo-specific additions) | Global only — one per machine |

Agentfile is the user-facing config — like package.json for npm. You write what you want, agentbrew figures out the rest. Commit it to your dotfiles repo so a fresh machine can bootstrap with agentbrew sync --agentfile ~/dotfiles/Agentfile.yaml.

state.yaml is the internal cache — like node_modules for npm. It stores which agents are detected on this machine, resolved file paths, source indexing timestamps, and catalog version. You never need to look at it. If you delete it, agentbrew init regenerates it.

Why global, not per-project? Agent config is machine-wide. You want the same MCP servers and skills available in every repo, not reinstalled per-project. Project Agentfiles (./Agentfile.yaml) add repo-specific items on top of the global baseline — they're additive, never override the global config.

Development

npm ci && npm run dev -- status        # clean bootstrap from the committed npm lockfile
npm test                               # affected Vitest tests (git-aware)
npm run test:all                       # full Vitest suite
npm run test:real-e2e                  # opt-in fixture-backed real CLI scenarios
npm run test:real-e2e:selected -- \
  real-e2e/scenarios/us04-share-rules.test.ts \
  real-e2e/scenarios/us21-shell-hooks.test.ts
                                       # run selected real e2e scenarios sequentially
                                       # pass only real-e2e/scenarios/*.test.ts before `--`
                                       # invalid or unknown scenario paths fail before Vitest starts
npm run typecheck && npm run lint      # tsc + biome
npm run verify                         # full gate: typecheck + lint + security + tests
npm run build                          # tsup → dist/

For the public GitHub cutover flow, see docs/oss-publish-mirror-runbook.md. Use scripts/validate-public-mirror.sh to recheck a scrubbed clone before pushing or publishing.

See AGENTS.md for repo layout and editing rules. See TASKS.md for the backlog.

License

MIT