Skip to main content
Join the waitlist

Fragments in Claude Code and Codex

Your coding agent checks its own UI work against your design system as it writes.

The plugin runs the same Drift Engine as the Fragments app and your CI, so all three give the same answer. You don’t need the app open, or installed.

What it does

  • After each edit, the agent hears what that edit drifted from: a hand-written colour, size or radius, with your system’s value beside it.
  • Before it hands back, the agent fixes the drift it added, or tells you why it kept it.
  • Before writing UI, the agent can read your tokens and components, so it starts from what you already have.

It reads CSS, SCSS (including Modules) and class names in React projects. Tested on macOS.

Before you start

  • Node 22.9 or newer. Run node --version. macOS doesn’t come with Node: get it from nodejs.org, or brew install node.
  • Claude Code or Codex, installed and signed in.

  1. Install the plugin

    Claude Code

    claude plugin marketplace add fragments-sdk/agent-plugin
    claude plugin install fragments@fragments

    Restart any Claude Code session that’s already open.

    Install it once. If you turned Fragments on in Claude’s plugin directory, Claude Code already has it as fragments@synced: don’t install it here too. Keep one or the other, so only one Fragments answers.

    Codex

    codex plugin marketplace add fragments-sdk/agent-plugin
    codex plugin add fragments@fragments

    Then trust the hooks, once. The next time you open Codex, it asks you to review the Fragments hooks: choose Trust all and continue. If you skip it, Codex runs without them and asks again next time; to trust them later, type /hooks and press t. An update that changes the hooks needs trusting again.

  2. Check it’s working

    Ask your agent for a small change with a hand-written value, for example: “add a footer with padding: 20px”. It should name the Fragments finding and say whether it kept the value.

    claude plugin list or codex plugin list should show fragments.

What it reads and writes

Fragments reads your project’s source, on your machine, and sends nothing off your machine: it makes no network calls. What it tells your agent joins the agent’s conversation, like any tool result.

It writes nothing to your project. It keeps its working files in one folder: in Claude Code, ~/.claude/plugins/data/fragments-fragments; in Codex, ~/.fragments/agent-state. To delete them, remove that folder. The README lists what’s in it.

Update

In Claude Code:

claude plugin marketplace update fragments
claude plugin update fragments@fragments

In Codex:

codex plugin marketplace upgrade fragments
codex plugin add fragments@fragments

Codex picks up a new version only when you add the plugin again; a new session isn’t enough.

Coming from 0.9.0

Update the same way. 1.0 is a new plugin on a new engine, and it drops some of 0.9.0:

  • The search, get and tokens tools. The server was fragments-workspace and is now fragments-drift, with check, explain, design_system and contract. Permission rules you wrote for the old server stop matching.
  • The Fragments Cloud contract and the hosted profile. Everything runs on your machine.
  • Opening a preview, and /fragments:create, with the create and design-system-pass skills. Ask your agent directly.

Then remove @usefragments/cli from your project, and the hooks it installed there (in .claude/settings.json, .codex/hooks.json or .cursor/hooks.json). Otherwise two engines answer. Delete its files too:

  • fragments.config.ts (or .js)
  • fragments.manifest.json
  • .fragments/manifest.json
  • .fragments/sync.json

Delete .fragments/tokens.json only if it has catalogRevision in it: that one came from the old CLI. Fragments keeps its own list of approved tokens at the same path, with "version": 1 and a tokens list, so keep that one. While an old file is there, Fragments can’t check your edits, and it tells you so once a session.

Uninstall

In Claude Code:

claude plugin uninstall fragments@fragments
claude plugin marketplace remove fragments

In Codex:

codex plugin remove fragments@fragments
codex plugin marketplace remove fragments

Claude Code deletes what Fragments keeps when you uninstall it (add --keep-data to keep it). Codex doesn’t: delete ~/.fragments/agent-state yourself.

Turned it on in Claude’s plugin directory (fragments@synced)? Turn it off there.

Limits

  • Shell writes: a file the agent writes with a shell command, such as cat > file, gets no note right after the edit. Only edit tools say which files they changed.
  • Values the agent names: if the agent’s closing reply names a drifted value, for example one you asked it to keep, Fragments treats it as explained and lets the agent finish.
  • Very large files: Fragments reads files up to 1 MB. If one of your app’s stylesheets is bigger, or a file the agent changed is, Fragments doesn’t guess: it tells you once a session that it can’t check, and why.

If something’s wrong

  • “Fragments is off: it needs Node 22.9 or later”: your node is too old. Upgrade it, then restart the session.
  • Codex says nothing about drift: trust the hooks: type /hooks and press t.
  • Claude Code shows hook errors: run node --version in the same terminal you start Claude Code from.
  • Started from the Dock? The Claude and Codex apps take your PATH from your login shell. If Fragments doesn’t start there, check that node --version works in a new terminal window.

Licence

Free to use for your own projects, including commercial ones, under the Fragments Local Use License.

Next steps