Equip

Equip your AI agents with augments — packages of MCP servers, behavioral rules, and agent skills that work across every platform.

Discord · Augment Author Guide

What It Does

You want to add a capability to your AI coding agent — a knowledge base, a documentation fetcher, a code formatter. It should work on Claude Code, Cursor, VS Code, Windsurf, and every other platform. Each platform has its own config format, file paths, and quirks.

Equip handles all of that. One command, every platform.

equip prior           # Installs MCP server + rules + skills on all detected platforms

Install

npm install -g @cg3/equip

Or use without installing:

npx @cg3/equip prior

Quick Start

equip prior                    # Install an augment
equip status                   # See what's installed across all platforms
equip doctor                   # Validate config integrity + credential health
equip update prior             # Re-fetch and re-install latest version
equip refresh                  # Refresh expired OAuth tokens
equip reauth prior             # Re-authenticate and rotate credentials
equip restore claude-code      # Restore a platform to its pre-equip state
unequip prior                  # Remove an augment

Development and CI

npm test                       # Unit + integration coverage on the host
npm run test:docker:acceptance # Hermetic Docker acceptance for fake Claude/Codex homes
npm pack --dry-run             # Inspect the exact npm payload before release

The Docker acceptance lane is intentionally narrow: it boots a clean Node container, serves a local fixture registry, installs a direct-mode augment into fake Claude Code and Codex homes, and verifies the written MCP config, rules, skills, and ~/.equip state. This is the right place for CLI-level install flows that should stay hermetic and CI-friendly without depending on live registry data.

Release Model

Stable npm releases now use Changesets plus a dedicated GitHub Actions release workflow.

Contributor workflow:

npm run changeset

Maintainer workflow:

• merge changesets to main
• let the release workflow open or update the Version packages PR
• merge that PR to publish @cg3/equip

For the PR-creation step, either enable Settings -> Actions -> General -> Workflow permissions -> Allow GitHub Actions to create and approve pull requests, or set a RELEASE_GITHUB_TOKEN repository secret for the workflow to use instead.

The committed package.json version on main is the canonical release version. Tags and GitHub releases are outputs of that flow, not the mechanism that decides the version.

When package.json is already ahead of npm for an unpublished release, there should be no pending .changeset/*.md files for that same release line. Otherwise the workflow will prepare the next version PR instead of publishing the current package.

See Release Management for the full release and publishing contract.

How Augments Work

An augment is a bundle of up to four layers that enhance your agent:

| Layer | What It Does | Coverage | |---|---|---| | MCP Server | Makes capabilities available — agent can call them | All platforms | | Behavioral Rules | Teaches the agent when and how to use them | Most platforms | | Agent Skills | Gives detailed knowledge loaded on demand | Most platforms | | Lifecycle Hooks | Structurally enforces behavior at key moments | Claude Code |

Each layer compensates for the limitations of the one before it. Together, they give your agent the best coverage available.

Supported Platforms

| Platform | MCP | Rules | Skills | Hooks | |---|---|---|---|---| | Claude Code | Yes | Yes | Yes | Yes | | Cursor | Yes | — | Yes | — | | VS Code / Copilot | Yes | — | Yes | — | | Windsurf | Yes | Yes | Yes | — | | Cline | Yes | Yes | Yes | — | | Roo Code | Yes | Yes | Yes | — | | Codex | Yes | Yes | Yes | — | | Gemini CLI | Yes | Yes | Yes | — | | Junie | Yes | — | — | — | | Copilot (JetBrains) | Yes | — | — | — | | Copilot CLI | Yes | — | — | — | | Amazon Q | Yes | — | — | — | | Tabnine | Yes | Yes | — | — |

See Platforms for config paths, detection, and per-platform details.

CLI Commands

| Command | Description | |---|---| | equip <augment> | Install an augment from the registry | | equip status | Cross-platform inventory of installed augments | | equip doctor | Validate config integrity and credential health | | equip update <augment> | Re-fetch definition and re-install | | equip refresh [augment] | Refresh expired OAuth tokens | | equip reauth <augment> | Re-authenticate and update credentials | | equip uninstall <augment> | Remove an augment (alias: unequip) | | equip snapshot [platform] | Capture current platform config state | | equip snapshots [platform] | List available config snapshots | | equip restore <platform> | Restore platform config to a previous snapshot | | equip ./script.js | Run a local setup script (for development) |

Options: --verbose, --dry-run, --api-key-file <path>, --api-key <key>, --platform <name>, --non-interactive

See CLI Reference for details.

For Augment Authors

Equip distributes your augment through the registry service. Define your MCP server URL, auth requirements, rules, and skills — equip handles platform detection, config translation, credential management, and installation across all platforms.

For local development:

equip ./my-augment.js          # Test locally on all detected platforms
equip .                        # Run current directory's package

See the Augment Author Guide for the full walkthrough.

Auth

Equip handles authentication for augments that require it:

• API key — prompt, --api-key-file <path> (recommended for CI and shell safety), or --api-key <key> when you accept shell-history/process-list exposure
• OAuth — browser PKCE flow with automatic token refresh
• OAuth + key exchange — browser flow to provider-issued API key
• OIDC delegated auth — token exchange that injects a short-lived delegated access token according to the augment definition

Credentials stored securely at ~/.equip/credentials/. Expired tokens are auto-refreshed on every equip command.

Documentation

| Guide | Description | |---|---| | Augment Author Guide | Build and publish augments | | Platforms | Supported platforms, capabilities, config paths | | MCP Servers | Config format translation, API reference | | Behavioral Rules | Marker-based versioned instructions | | Agent Skills | SKILL.md format, cross-platform distribution | | Lifecycle Hooks | Event-driven enforcement scripts | | CLI Reference | Commands, state, options | | Release Management | Changesets, CI publish flow, npm auth |

State Management

Equip tracks everything in ~/.equip/:

• storage/intents.jsonl — Append-only install/update/uninstall journal
• storage/content/ — Immutable content blobs for registry definitions and local edits
• cache/registries/ — Registry-scoped HTTP cache for offline fallback
• platforms.json — Detected platforms with capabilities and enabled/disabled preferences
• platforms/ — Per-platform scan results (all MCP servers, managed and unmanaged)
• credentials/ — Stored auth credentials per augment
• snapshots/ — Platform config snapshots for rollback (initial state captured automatically)
• equip.json — Preferences such as telemetry and local config metadata

Install and local-script flows reconcile state from disk by scanning platform config files after writes. equip status reads current platform config files directly, and initial snapshots are captured before modifications so you can restore to your pre-equip state.

Design Principles

• Zero runtime dependencies — fast installs, no supply chain risk
• Registry service as source of truth — augment definitions served from api.cg3.io/equip
• Single-process installs — no secondary npm/npx for direct-mode augments
• Atomic file writes — crash-safe config modifications
• Structured observability — every install returns typed results with error codes and warnings
• Credential lifecycle — store, validate, refresh, and rotate automatically

Telemetry

Equip sends privacy-preserving install metrics (augment name, platform, OS, architecture, Node version, equip version, and a generated install ID) to help improve equip. No credentials, file paths, or user-authored content are included.

Telemetry is on by default. To disable, edit ~/.equip/equip.json and set preferences.telemetry to false.

License

FSL-1.1-ALv2 — CG3, Inc.