Equip

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

npm license node

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 snapshot-diff claude-code # Preview exactly what restore would change
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 snapshot-diff <platform>	Print a JSON preview of a snapshot restore
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>, --accept-risk, --non-interactive, --delete-added, --preserve-added, --json

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
Snapshots	Config restore points, JSON restore diffs, and restore safety policies
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

Broker Mode Boundary

The standalone equip CLI installs augments in direct mode. It writes platform MCP config, rules, skills, credentials, and local state, but it does not start, stop, monitor, or operate a broker runtime.

The npm package also exposes broker-aware platform config helpers for host applications that ship their own broker daemon. Those helpers only write the platform config entry that points at a host-provided bridge binary and preserve broker-managed state for status/doctor/reconcile. The host application owns the broker process, credential refresh, MCP proxying, runtime health, and any UI around that lifecycle.

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.