Installation

GitHub App (Easiest)

The fastest way to start catching design drift is to install the Buoy GitHub App from the GitHub Marketplace. It scans every PR automatically — no CLI, no config, no CI setup.

  1. Install from the GitHub Marketplace
  2. Select your repositories
  3. Open a PR — Buoy posts a review with drift issues

No Buoy account or sign-up is needed; installing the App is enough. See GitHub App docs for details.

Coding Agents (Claude Code, Cursor)

Give your agent the design system while it writes, so it uses tokens instead of hardcoding values.

Claude Code — the plugin bundles the MCP server, a post-edit drift check and a design-tokens skill:

/plugin marketplace add ahoybuoy/buoy
/plugin install buoy@buoy

Cursor, Codex, Windsurf or any MCP client — write the config into your repository:

npx @buoy-design/cli mcp install cursor   # or codex, windsurf, all

See MCP Server for the tools and the hook.

CLI Installation

For local scanning, auto-fixing, and project setup, install the Buoy CLI. It can be run directly with npx or installed as a dependency.

Using npx (Recommended)

Run Buoy without installing:

npx ahoybuoy dock

This launches the interactive setup wizard that scans your project and guides you through setup.

To run a quick drift scan:

npx ahoybuoy drift

Installing as a Dev Dependency

For ongoing use, install Buoy in your project. Any of these package names work:

# npm
npm install --save-dev @buoy-design/cli

# pnpm
pnpm add -D @buoy-design/cli

# yarn
yarn add -D @buoy-design/cli

# Alternative package names (same CLI)
npm install --save-dev buoy-design
npm install --save-dev ahoybuoy

Then run with npx or add to your package.json scripts:

{
  "scripts": {
    "lint:design": "buoy drift",
    "check:design": "buoy drift check --fail-on critical"
  }
}

Global Installation

Install globally to use buoy anywhere:

npm install -g @buoy-design/cli
# or: npm install -g buoy-design

Requirements

  • Node.js 18 or higher
  • A frontend codebase (React, Vue, Svelte, Angular, Next.js, Tailwind, or plain CSS/HTML)

Verify Installation

$ buoy --version
0.7.5

$ buoy --help
Usage: buoy [command] [options]

Commands:
  show        Show design system status and health
  drift       Detect, check, and fix design drift
  dock        Dock Buoy into your project
  ahoy        Manage account and integrations
  mcp         Connect coding agents to your design system

Next Steps