Set up your agents

Quick start

1. Initialize

   terminal

   npx --yes @usefragments/cli init

   Init detects the project and its existing UI library, writes the contract — including govern.canonicalSources when a supported library is detected — pins the exact running version of @usefragments/cli as a dev dependency, and installs the Claude Code, Cursor, GitHub Copilot, and Codex integrations. Setup ends by running fragments doctor; only a successful required-check pass earns Ready. --no-install and --no-hook deliberately stage setup and finish as Configured, never Ready.

2. Verify

   terminal

   # npm: offline prevents a registry fallback if the local binary is missing
   npm exec --offline -- fragments status
   
   # equivalent local invocations
   pnpm exec fragments status
   yarn run fragments status
   bun run fragments status

   status checks the committed configuration — it does not claim the hosted MCP endpoint is reachable or that an agent executed its hook. Run fragments doctor anytime to re-prove the live activation chain.

3. Enforce in CI

   Init also writes a release-safe CI workflow that runs fragments check --ci on every pull request — make that check required in your repository rules when it must block merges. The full path (GitHub App, contract approval, Cloud ingest) and the init --token flow for Cloud-linked repos are in Set up governance.

Bespoke and ShadCN projects

For hand-rolled primitives, point init at their real source — Fragments classifies the exported primitives and keeps the directory source open-ended so components added later stay governed. ShadCN projects need no flags: run init after at least one component exists in your local components/ui directory (detection also expects tailwindcss in the project dependencies) and that directory becomes the canonical source.

npx --yes @usefragments/cli init \
--components "src/primitives/**/*.{tsx,jsx}"

The first check reports how many existing findings were accepted into the adoption baseline. Review that file before committing it: a green check means no new drift, not zero historical findings. For a registry-version dependency or multiple UI libraries, set govern.canonicalSources explicitly and rerun fragments doctor.

What init writes

Re-running init refreshes Fragments-owned sections without replacing unrelated config or instructions.

• package.json — an exact @usefragments/cli dev dependency matching the bootstrap CLI.
• fragments.config.ts — project shape, pinned preset version (e.g. universal@2), and govern.canonicalSources when an existing UI library is detected.
• AGENTS.md — created on first run; later runs add only one pointer to the generated context. The rest of the file stays yours.
• .fragments/agent-context.md — canonical primitives, available tokens, enabled rules, and the definition-of-done agents should follow; regenerated on every run.
• .mcp.json — a hosted fragments server entry, merged conservatively so other MCP servers are preserved. Endpoint and per-editor configuration: MCP.
• .github/workflows/fragments*.yml or .gitlab-ci.fragments.yml — a repository-root workflow that runs the committed CLI with fragments check --ci. CI and Cloud ingest details: Set up governance.
• .fragments/baseline.json — local accepted-debt authority; replace it deliberately with fragments check --update-baseline. Cloud-connected projects receive baseline authority from Cloud instead.
• .fragments/classification.json — per-component canonical mapping. Heuristics always run; setting ANTHROPIC_API_KEY or OPENAI_API_KEY adds an AI pass for low-confidence components (re-run fragments classify after adding a key).
• .fragments/init-state.json and .fragments/activation.json — the resume-safe setup journal and Doctor's verified activation receipt.
• Agent hook config — programmatic hooks for Claude Code and Codex, static rule files for Cursor and GitHub Copilot (skip with --no-hook).

Agent contract hook

MCP lets an agent pull validation when it chooses to; the contract hook pushes your guardrails into the agent as it works — before the PR, not flagged after merge. It checks a conservative subset of the same rules CI runs and fails open when policy context is unavailable; CI remains the complete repository check. Install for all four integrations, one agent, or with the local deny gate:

# all integrations, advisory mode
npm exec --offline -- fragments hook install --agent all

# one agent: --agent claude|codex|cursor|copilot
npm exec --offline -- fragments hook install --agent codex

# local deny gate (Claude/Codex) — blocks confirmed hard violations pre-write
npm exec --offline -- fragments hook install --agent claude --mode blocking
npm exec --offline -- fragments hook install --agent codex --mode blocking

# remove hooks later if desired
npm exec --offline -- fragments hook uninstall --agent all

• Claude Code — programmatic hooks inject the vocabulary card at session start plus a check at the moment of each governed edit. Advisory by default; --mode blocking also denies a write on a confirmed, deterministic violation — never a judgment call.
• Codex — session-start and prompt hooks inject the contract; blocking mode adds a pre-tool deny. Codex hooks are enabled by default (if you set [features].hooks = false, re-enable first); review and trust the project hook with /hooks.
• Cursor & GitHub Copilot — no programmatic edit hook, so they get static, always-on rule files (.cursor/rules/fragments-design-system.mdc, .github/copilot-instructions.md) embedding your canonical component names and token prefix. Injection, not interception: these tools cannot block a write.

A hook bug never blocks your agent — the engine always exits cleanly, and a deny is expressed in the response, never as an error. Prove the chain anytime with fragments doctor.

Deny with a fix

In blocking mode a deny embeds a conformed replacement — corrected content produced by the same deterministic rewrite engine as design_system/conform — so the agent retries with the fix instead of guessing. After two denies for the same file and finding set in one session, the hook downgrades to advisory so agents never thrash; deny copy names the @fragments-expect-error suppression path. The deny set is a strict subset of what CI fails, so CI stays the source of truth.

The vocabulary card

The vocabulary card is a compact digest of your contract, built from your confirmed canonical mappings: canonical component names with their import path, your token prefix, a short exemplar, and a contract-hash stamp so staleness is detectable. If no component names are confirmed yet, it degrades honestly to a token-prefix and canonical-preference nudge — it never fabricates names.

• Claude Code & Codex — injected at session start (including after a resume, compaction, or clear) and re-stamped on prompts with debounce.
• Cursor & GitHub Copilot — the same vocabulary is embedded in their static rule files at install time; it refreshes on the next install, not per session.

Injection raises the probability that the first draft is on-system — measured and improving, not a guarantee. Writes that bypass hooked tools are not intercepted; the CI check covers the repository regardless of which agent or human produced the change.

Verifying with fragments status

status reads six persisted configuration and activation items and reports a pass/fail per item. It verifies recorded state, not live MCP connectivity or a fresh agent execution.

$ npm exec --offline -- fragments status

Fragments status

  ✓ Local activation
    Doctor verified this context with the pinned local CLI.
  ✓ Agent context current
    .fragments/agent-context.md is referenced and current.
  ✓ MCP configured
    Fragments hosted MCP endpoint is configured; runtime availability is not asserted.
  ✓ CI mirrors local
    .github/workflows/fragments.yml runs fragments check with universal.
  ✓ Canonical direction resolved
    No unacknowledged wrapper-versus-package conflicts detected.
  - In sync with team
    No Cloud sync file found; local-only project.

Guardrails active.

Exit codes

status exits non-zero when any required item fails; each item has a stable exit code so scripts can react specifically.

• 0 — all required configuration checks pass.
• 10 — Local activation failed (partial or staged setup, corrupt journal, or a missing or stale Doctor receipt).
• 11 — Agent context current failed (missing or stale).
• 12 — MCP configured failed (entry missing, malformed, or locally unresolvable).
• 13 — CI mirrors local failed (no discoverable, gating pull-request or merge-request workflow runs the check for this project).
• 14 — In sync with team failed (Cloud sync stale or rules version mismatch).
• 15 — Canonical direction resolved failed (exported local wrappers conflict with npm policy without explicit identity decisions).

Pre-commit hook

npm example for Husky, lefthook, or a plain git hook — pass --json for machine-readable output:

#!/usr/bin/env sh
npm exec --offline -- fragments status || {
  echo "Run 'npx @usefragments/cli init' to refresh guardrails."
  exit 1
}

Monorepos

GitHub Actions only reads workflows from the repository root, so init walks to the git root and writes a unique workflow in .github/workflows/; dependency install runs where the detected lockfile lives, and only the check step gets a working-directory matching the subproject. Status likewise scans only repository-root workflows and requires a matching working directory or --dir. Run init from each project root — each gets its own scoped token (when Cloud-connected) and its own context files.

# from a monorepo subpackage
cd apps/cloud
npx --yes @usefragments/cli init
npm exec --offline -- fragments status

Updating

init is idempotent: an ordinary rerun keeps the pinned preset and accepted baseline while refreshing .fragments/agent-context.md, team rules from Cloud (when a token is configured), and generated integration files. Change preset versions deliberately with --force --preset universal@3 — --force backs up the config as fragments.config.ts.bak but never resets the accepted baseline (fragments check --update-baseline does that). Your AGENTS.md body is never touched after the initial pointer.

Troubleshooting

Keyed by the exit codes above:

• 10 — finish dependency installation and rerun fragments init, or rerun fragments doctor when only the activation receipt is stale.
• 11 — re-run init to add the pointer line, or add See: .fragments/agent-context.md to AGENTS.md by hand.
• 12 — re-run init; it repairs just the fragments entry and leaves other MCP servers untouched.
• 13 — put the workflow at the git root and either set a matching working-directory, pass --dir <your-project-path>, or scan the whole repo.
• 14 — sync metadata is older than the tolerance window (default 168h) or the catalog revision differs; re-run init with your token.

Pass --json to status for the same checks as a structured object with the failing item identified by id.