agentbrew 0.1.0

package/README.md

@@ -0,0 +1,315 @@
+# agentbrew
+
+One source of truth for AI coding agent config. Sync skills, MCP servers, rules, and commands across **42 agents** — Claude Code, Cursor, Windsurf, Augment, Codex, Gemini CLI, Copilot, OpenCode, Kiro, Amp, Trae, Junie, Continue, Warp, and more.
+
+```bash
+npx agentbrew init
+```
+
+## The Problem
+
+Every AI coding agent wants its own config — `CLAUDE.md`, Cursor rules, Windsurf workflows, MCP server JSON, slash commands. When you use 2–4 agents (most developers do), keeping them in sync is manual, error-prone, and nobody's job. Config drifts silently.
+
+## What AgentBrew Does
+
+1. **Detects** your installed agents and discovers existing config
+2. **Syncs** MCP servers, rules, and commands to every agent in its native format
+3. **Repairs** drift automatically — a LaunchAgent checks every 30 minutes, with macOS notifications
+4. **Catalogs** 51 curated skills, 11 MCP servers, 4 rule sets — install with one command
+5. **Sources** any GitHub repo or local folder as a skill source
+6. **Dashboards** — web GUI and full-screen TUI for visual management
+
+No other tool combines sync + drift repair + catalog + dashboard + sources in one CLI.
+
+## Quick Start
+
+```bash
+npx agentbrew init                   # detect agents, discover config, install drift repair
+npx agentbrew install --recommended  # install curated skills + MCP servers + rules
+npx agentbrew sync                   # deploy everything to all agents
+```
+
+Or install globally: `npm i -g agentbrew` — then use `agentbrew` directly.
+
+After this, drift repair runs in the background. You're done.
+
+## CLI Reference
+
+### Core
+
+```
+agentbrew init [--force]              Detect agents, discover config, set up drift repair
+agentbrew status                      Show agents, MCP servers, sources, and skills
+agentbrew status --usage              Show usage analytics (last-used timestamps)
+agentbrew sync                        Deploy MCP servers, rules, commands, skills, and instructions
+agentbrew sync --only <modules>       Run only specific modules (e.g. --only mcp,skills)
+agentbrew sync --parallel              Run all sync categories in parallel (faster)
+agentbrew check [--no-fix] [--ci]     Detect drift, broken symlinks, skill validity; auto-repair
+agentbrew doctor                      Alias for check
+agentbrew fix                         Force re-sync everything (all 6 modules)
+agentbrew diff                        Preview what sync would change (all 6 modules)
+agentbrew update                      Pull latest from all sources, re-sync
+agentbrew log [-n N]                  View sync and drift history
+agentbrew backup                      Snapshot current state
+agentbrew rollback                    Revert to last snapshot
+agentbrew discover                    Scan for unknown agents
+agentbrew lock                        Generate lock file with SHA pins
+agentbrew lock --verify               Verify lock file integrity
+agentbrew gui [-p PORT] [--no-open]   Web dashboard with live health, sync, and fix (localhost:3141)
+agentbrew dashboard                   Alias for gui
+agentbrew tui                         Full-screen terminal dashboard
+```
+
+### Catalog & Install
+
+```
+agentbrew catalog                     Browse skills, MCP servers, and rules
+agentbrew catalog --skills|--mcp|--rules  Filter by type
+agentbrew catalog --search <term>     Search by keyword
+agentbrew search <query>              Search mdskills.ai online marketplace
+agentbrew search <query> --json       Search online, output as JSON
+agentbrew install <name>              Install from catalog or any added source
+agentbrew install --recommended       Install the curated starter set
+```
+
+### Team Config
+
+```
+agentbrew team init                   Create a shareable .agentbrew-team.yaml in cwd
+agentbrew team set <repo-url>         Clone a team config repo (MCP servers, rules, sources)
+agentbrew team show                   Show current team config details
+agentbrew team sync                   Pull latest team config from remote
+agentbrew team unset                  Remove team config
+```
+
+Team config merges as the base layer: **team → user → project**. User config overrides team, project overrides both.
+
+### Sources
+
+```
+agentbrew add <source>                Add a GitHub repo or local folder
+agentbrew add <source> --skill <name> Install one skill from a source
+agentbrew add <source> --list         List available skills without installing
+agentbrew sources                     Show tracked sources
+agentbrew remove-source <url>         Stop tracking a source
+```
+
+### MCP Servers
+
+```
+agentbrew mcp list                    Show registered servers
+agentbrew mcp add <name> -c <cmd> [-a args...] [-e KEY=VAL...]
+agentbrew mcp remove <name>           Remove from state + all agents
+agentbrew mcp sync                    Deploy to all agents
+agentbrew mcp run <name>              Run a server locally over stdio
+agentbrew mcp run <name> --dry-run    Print resolved command without executing
+agentbrew mcp share <name>            Share a server via SSE + public tunnel
+agentbrew mcp share <name> --no-tunnel  Expose locally only (no tunnel)
+agentbrew mcp search <query>          Search the official MCP registry
+agentbrew mcp install <name>          Install a server from the registry
+agentbrew mcp info <name>             Show registry details for a server
+```
+
+### MCP Profiles
+
+```
+agentbrew mcp profile create <name> --servers <names>  Create a profile
+agentbrew mcp profile list            List all profiles
+agentbrew mcp profile activate <name> Activate a profile (only its servers sync)
+agentbrew mcp profile deactivate      Deactivate (all servers sync)
+agentbrew mcp profile delete <name>   Delete a profile
+```
+
+### Per-Project MCP
+
+```
+agentbrew mcp project init            Import existing .mcp.json / .cursor/mcp.json into .agentbrew.yaml
+agentbrew mcp project sync            Deploy project MCP servers to native configs
+agentbrew mcp project status          Show project MCP server status
+```
+
+### Skill Scenarios
+
+```
+agentbrew scenario create <name>      Snapshot current skills as a scenario
+agentbrew scenario list               List all scenarios
+agentbrew scenario activate <name>    Activate (only its skills sync)
+agentbrew scenario deactivate         Deactivate (all skills sync)
+agentbrew scenario delete <name>      Delete a scenario
+```
+
+### Rules
+
+```
+agentbrew rules init                  Create shared rules file
+agentbrew rules show                  Show rules and deployment status
+agentbrew rules sync                  Deploy to all agents (managed markers)
+```
+
+### Commands
+
+```
+agentbrew commands init               Create commands dir with starter
+agentbrew commands list               Show commands and deployment status
+agentbrew commands add <file>         Add a command file
+agentbrew commands sync               Deploy to all agents (auto-transforms)
+```
+
+### Auto-Sync
+
+```
+agentbrew auto-sync watch             Watch config dir, sync on changes
+agentbrew auto-sync install           Install macOS LaunchAgent
+agentbrew auto-sync uninstall         Remove LaunchAgent
+agentbrew auto-sync status            Show auto-repair status
+```
+
+### Skills
+
+```
+agentbrew skill                       List all skills grouped by source
+agentbrew skill <name>                Show full info: metadata, capabilities, security, content
+agentbrew capabilities <skill>        List capabilities for a skill
+agentbrew capabilities enable <skill> <cap>   Enable a capability
+agentbrew capabilities disable <skill> <cap>  Disable a capability
+agentbrew capabilities reset <skill>  Reset overrides to defaults
+agentbrew pin <skill>                 Pin a skill — preserve local edits
+agentbrew unpin <skill>               Unpin a skill
+agentbrew pinned                      Show pinned skills and patch status
+agentbrew validate                    Validate all skills against SKILL.md spec
+agentbrew validate --verbose          Include passing skills and info-level issues
+```
+
+### Clean & Usage
+
+```
+agentbrew clean <name>                Remove a skill or command from all agents
+agentbrew clean --list                List all cleanable items
+agentbrew clean --unused              Show items not used in 30+ days
+agentbrew clean --unused --days 14    Custom unused threshold
+```
+
+## How Sync Works
+
+### MCP Servers
+
+One registry → every agent gets the server in its native format:
+
+| Agent | Method |
+|-------|--------|
+| Claude Code | `claude mcp add-json` CLI → `~/.claude.json` |
+| Cursor | Write to `~/.cursor/mcp.json` |
+| Windsurf | Write to `~/.codeium/mcp_config.json` |
+| Kiro | Write to `~/.kiro/settings/mcp.json` |
+| OpenCode | Write to `~/.config/opencode/opencode.json` (key: `mcp`) |
+| Amp | Write to `~/.config/amp/settings.json` (key: `amp.mcpServers`) |
+| Codex | Write to `~/.codex/config.toml` (TOML format) |
+| Goose | Write to `~/.config/goose/config.yaml` (YAML format) |
+
+### Rules
+
+One markdown file (`~/.config/agentbrew/shared-rules.md`) → injected between managed markers (`<!-- agentbrew:start/end -->`) into each agent's rules file. Content outside the markers is never touched.
+
+| Agent | Rules file |
+|-------|-----------|
+| Claude Code | `~/.claude/CLAUDE.md` |
+| Windsurf | `~/.codeium/windsurf/memories/global_rules.md` |
+| Augment | `~/.augment/guidelines.md` |
+| Codex | `~/.codex/AGENTS.md` |
+
+### Commands
+
+One canonical format (Markdown + YAML frontmatter) → auto-transformed per agent:
+
+| Agent | Transform | Location |
+|-------|-----------|----------|
+| Claude Code | Strip frontmatter | `~/.claude/commands/` |
+| Cursor | Strip frontmatter, `<!-- turbo -->` → `// turbo` | `~/.cursor/commands/` |
+| Windsurf | Keep as-is | `~/.codeium/global_workflows/` |
+| OpenCode | Keep as-is | `~/.config/opencode/commands/` |
+
+### Drift Repair
+
+`agentbrew init` installs a macOS LaunchAgent that runs `agentbrew check` (or `agentbrew doctor`) every 30 minutes. It detects MCP drift, missing rules, broken skill symlinks, and skill validation errors — shows what drifted, re-syncs automatically, and sends a macOS notification so you know it happened. View history with `agentbrew log`.
+
+## Supported Agents (42)
+
+**Full config sync** (skills + MCP + rules + commands):
+
+| Agent | Skills | MCP | Rules | Commands |
+|-------|--------|-----|-------|----------|
+| Claude Code | ✓ | ✓ | ✓ | ✓ |
+| Cursor | ✓ | ✓ | — | ✓ |
+| Windsurf | ✓ | ✓ | ✓ | ✓ |
+| Augment | ✓ | — | ✓ | — |
+| Codex | ✓ | ✓ | ✓ | — |
+| OpenCode | ✓ | ✓ | — | ✓ |
+| Kiro | ✓ | ✓ | — | — |
+| Amp | ✓ | ✓ | — | — |
+| Goose | ✓ | ✓ | — | — |
+| Cline | ✓ | ✓ | — | — |
+| Roo Code | ✓ | ✓ | — | — |
+
+**Skills sync** (31 additional agents):
+
+Gemini CLI, Copilot, Trae, Trae CN, Junie, Continue, Warp, Antigravity, Qwen Code, OpenHands, Kilo Code, Droid, OpenClaw, Pi, Crush, Kode, Qoder, Zencoder, Cortex, Mistral Vibe, Mux, CodeBuddy, Kimi CLI, Replit, Universal, Command Code, iFlow CLI, MCPJam, Neovate, Pochi, Adal
+
+## Catalog
+
+51 skills, 11 MCP servers, 4 rule sets — curated from [Vercel](https://github.com/vercel-labs/skills), [Anthropic](https://github.com/anthropics/skills), [obra/superpowers](https://github.com/obra/superpowers), [Supabase](https://github.com/supabase/agent-skills), [Trail of Bits](https://github.com/trailofbits/skills), [actionbook](https://github.com/actionbook/actionbook), [tasks.md](https://github.com/tasksmd/tasks.md), and more. ★ = installed with `--recommended`.
+
+**Skills**
+
+| Tier | Skills |
+|------|--------|
+| ★ Recommended (15) | find-skills, debug, plan, commit, review, taste, react-best-practices, web-design-guidelines, frontend-design, mcp-builder, skill-creator, next-task, agent-browser, project-audit, refactor |
+| Strong (20) | pr, pr-fix, pr-comments, composition-patterns, fix-styles, screenshot, actionbook, doc-check, rfc, rfc-iterate, rfc-review, jira, jira-task, github-actions-debugging, cursor-bg, research-url, markdown-for-gdoc, webapp-testing, shadcn, next-best-practices |
+| Specialized (16) | postgres-best-practices, playwright-best-practices, react-native-guidelines, remotion-best-practices, sync-agent-config, subagent-driven-development, executing-plans, search, static-analysis, supply-chain-risk-auditor, property-based-testing, security-best-practices, better-auth-best-practices, dotfiles-development, dotfiles-new-module, dotfiles-doctor-debug |
+
+**MCP Servers**: context7 ★, playwright ★, tasks-mcp ★, github, filesystem, sentry, postgres, brave-search, notion, sequential-thinking, memory
+
+**Rules**: conventional-commits ★, test-before-commit ★, minimal-changes ★, tasks-md-spec ★
+
+Add any repo as a source to expand your catalog:
+
+```bash
+agentbrew add vercel-labs/agent-skills   # index available skills
+agentbrew add ~/my-company/skills        # local folder
+agentbrew catalog                         # browse built-in + all sources
+```
+
+## State
+
+All state lives in `~/.config/agentbrew/state.yaml` — detected agents, registered MCP servers, tracked sources, installed skills. Human-readable YAML.
+
+## Roadmap
+
+See [TASKS.md](TASKS.md) for the prioritized backlog.
+
+**Completed**: Web dashboard (GUI + TUI), tasks.md integration, auto-sync on all mutations, drift pre-fix reporting, macOS repair notifications, online catalog, team config, browsable web catalog, usage analytics, parallel sync, JSONC/TOML config support, GitHub Actions / CI integration, AgentAdapter pattern, pure diff/IO separation, MCP server sharing, skill patch system, per-project manifests, multi-registry search, structured error handling, security risk scoring, lock file with SHA pinning, per-project MCP configs, auth for remote MCP servers, format conversion for commands, automated agent discovery, feature flags / skill capabilities, skill preview / render
+
+See [docs/COMPETITION.md](docs/COMPETITION.md) for competitive analysis vs MCPM, vsync, mdskills.ai.
+
+> **Note**: The npm package is `agentbrew` (with hyphen). The CLI command is `agentbrew` (no hyphen) for ergonomics. Both `agentbrew` and `agentbrew` work as commands.
+
+## Contributing
+
+Want to add a skill, MCP server, or rule to the catalog? See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Development
+
+```bash
+npm install
+npm run dev -- status          # run CLI in dev mode
+npm test                       # vitest (69 test files, 1260 tests)
+npm publish --access public    # publish to npm
+npm run generate:catalog-html  # build browsable catalog → docs/catalog/
+npm run typecheck              # tsc --noEmit
+npm run build                  # tsup → dist/
+```
+
+Pure Node.js CLI — no external dependencies beyond npm. See [AGENTS.md](AGENTS.md) for the full repo layout and editing rules.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "agentbrew",
+  "version": "0.1.0",
+  "description": "Skill manager and sync engine for AI coding tools — sync skills, MCP servers, rules, and commands across 42 agents",
+  "type": "module",
+  "main": "./dist/cli.js",
+  "bin": {
+    "agentbrew": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "generate:catalog": "tsx src/generate-catalog.ts",
+    "generate:catalog-html": "tsx src/generate-catalog-html.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "mcp",
+    "sync",
+    "claude",
+    "cursor",
+    "windsurf",
+    "augment",
+    "codex",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fivanishche/agentbrew"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "7.10.1",
+    "@types/react": "19.2.14",
+    "chalk": "^5.6.2",
+    "chokidar": "5.0.0",
+    "commander": "^14.0.3",
+    "ink": "6.8.0",
+    "js-yaml": "^4.1.1",
+    "react": "19.2.4",
+    "smol-toml": "1.6.0",
+    "write-file-atomic": "7.0.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "4.0.18",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.18"
+  }
+}