# Set up onsystem

These are the steps to set onsystem up in the user's project. onsystem keeps coding agents on the project's design system: it reads the components, their props and variants, and the tokens from source, gives the agent MCP tools to look them up and `check_ui` to check its own UI code, and checks pull requests in CI. Make only the changes below, and ask the user before anything else, such as fixing what it finds.

The docs are at https://onsystem.vercel.app/docs, and all of them in one file at https://onsystem.vercel.app/llms-full.txt.

## 1. Look at the project

- onsystem checks React (`.tsx` and `.jsx`) and needs Node.js 20.19 or later. If the project has no React UI, stop and tell the user.
- Find the package manager from the lockfile, and whether this is one app or a monorepo. If the dependencies are not installed, install them first: without them, the props of components that wrap a library (Radix, React Aria) are not read.
- Set it up in the folder that CI will check: the app's folder, or the root of a monorepo, where each app and design-system package is checked against its own design system.

## 2. Write the config and record the baseline

In that folder, run:

```sh
npx -y onsystem init --yes
```

It writes `onsystem.config.json` from the components and tokens it finds, checks the project once, and records the findings already in the code in `onsystem.baseline.json`, so that the check fails only on new ones. Keep what it prints for step 5.

- If it says a config already exists, keep that config: do not pass `--force`. If there is no `onsystem.baseline.json` next to it, record the findings already in the code with `npx -y onsystem check . --update-baseline`.
- If it found no design system, run `npx -y onsystem inspect --explain` to see where it looked, ask the user where the components and tokens are, and run it again with them: `npx -y onsystem init --yes --components "src/components/ui/**/*.tsx" --tokens src/app/globals.css`.

## 3. Add it to your agent

Add onsystem to the agent you are running in, in files the repository keeps, so the whole team gets it. Merge into a file that is already there; do not replace it.

- **Claude Code**: the plugin, with the hook that checks each file Claude writes, the MCP server and the skill. `.claude/settings.json`:

  ```json
  {
    "extraKnownMarketplaces": {
      "dgesteves": {
        "source": { "source": "github", "repo": "dgesteves/onsystem" }
      }
    },
    "enabledPlugins": {
      "onsystem@dgesteves": true
    }
  }
  ```

  Claude Code loads it the next time it starts in this folder, once the user accepts the folder's trust prompt. Do not add onsystem to `.mcp.json` as well: both register the same tools. To install it for the user alone instead, they run `/plugin marketplace add dgesteves/onsystem`, then `/plugin install onsystem@dgesteves`.
- **Cursor**: the MCP server. `.cursor/mcp.json`:

  ```json
  {
    "mcpServers": {
      "onsystem": {
        "command": "npx",
        "args": ["-y", "onsystem", "--root", "${workspaceFolder}"]
      }
    }
  }
  ```

- **VS Code**: the MCP server, for Copilot agent mode. `.vscode/mcp.json`:

  ```json
  {
    "servers": {
      "onsystem": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "onsystem", "--root", "${workspaceFolder}"]
      }
    }
  }
  ```

- **Codex CLI**: the plugin, with the MCP server and the skill: `codex plugin marketplace add dgesteves/onsystem`, then `codex plugin add onsystem@dgesteves`.
- **Any other agent**: the MCP server runs over stdio as `npx -y onsystem --root <the project's absolute path>`, and [Set up your agent](https://onsystem.vercel.app/docs/clients#other-clients) has the config for each client. If the project has an `AGENTS.md`, add this line to it:

  ```md
  Before writing UI, use the onsystem tools. Run check_ui on every file you change and fix all errors. Without the tools, run `npx onsystem check <file>` on each file you change and fix all errors.
  ```

## 4. Check pull requests

On GitHub, add `.github/workflows/onsystem.yml`. It runs the GitHub Action, which checks the lines each pull request changes, leaves out the findings in the baseline, and fails on errors:

```yaml
name: Design system
on:
  pull_request:
  merge_group:
permissions:
  contents: read
jobs:
  onsystem:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - uses: dgesteves/onsystem@v0
```

Install the dependencies the way the project does: with pnpm, add `pnpm/action-setup` before `actions/setup-node` and run `pnpm install --frozen-lockfile` ([Roll out to a team](https://onsystem.vercel.app/docs/rollout#gate-pull-requests)). When the folder from step 1 is not the root, give the action that folder as `working-directory` ([GitHub Action](https://onsystem.vercel.app/docs/required-check)). On another CI, run `npx -y onsystem check . --require-design-system` in that folder.

## 5. Check it works, and report

1. Run `npx -y onsystem check . --require-design-system` in the folder from step 1, and look at its exit code:
   - 0: the check passes. The findings already in the code are in the baseline.
   - 1: it found errors that are not in the baseline, such as ones in code written since it was recorded. Do not fix them: list them for the user in the next step.
   - 2: it found no design system or could not read the config: go back to step 2.
2. Tell the user:
   - the files you added or changed, to review and commit: `onsystem.config.json`, `onsystem.baseline.json`, and the agent's and CI's files;
   - what the baseline holds (what `init` printed by rule, or the count `check . --update-baseline` printed), and that `npx -y onsystem check . --ignore-baseline` lists each finding with its fix;
   - with code 1, the findings the check printed, each with its fix;
   - what is left for them to do, such as restarting the agent so it loads the plugin or the MCP server.
3. Leave the findings as they are unless the user asks you to fix them.