> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agents

> Use Humic with Claude Code, Cursor, Copilot, and other AI coding agents.

AI coding agents work best when they understand your design system. Humic gives agents access to your tokens through the CLI, so they can generate code that uses the right values instead of hardcoding colors and spacing.

<Note>
  Using **Claude**? The [Claude connector](/integrations/claude) is the easier path — one URL, no CLI install, and it can edit and publish tokens, not just read them. The CLI workflow below is for other agents, or for pinning tokens into a repo-local context file.
</Note>

## How it works

The Humic CLI supports `--json` output on every command. Agents can call these commands and parse the JSON to understand your design system — no custom integration needed.

## Setup

### 1. Install the CLI

Add Humic as a dev dependency so it's available in your project:

```bash theme={null}
npm install -D @humicdev/cli
```

### 2. Initialize your project

```bash theme={null}
npx humic init
```

This creates `humic.config.json` and writes a context file that agents can read.

### 3. Configure your agent

Add instructions to your agent's configuration or system prompt. Here's an example for Claude Code (in `CLAUDE.md`):

```markdown theme={null}
## Design System

This project uses Humic for design tokens. Before writing UI code:

- Run `npx humic tokens list --json` to see available tokens
- Run `npx humic tokens guidelines --json` for usage rules
- Use CSS custom properties (e.g., `var(--color-brand-primary)`) — never hardcode values
- Run `npx humic validate --file <path>` to check your code against the design system
```

For Cursor, add this to `.cursor/rules`:

```
When writing UI code, use design tokens from Humic.
Run `npx humic tokens list --json` to see available tokens.
Use CSS variables like var(--color-brand-primary) instead of hardcoded values.
```

## Useful commands for agents

| Command                                           | What the agent gets                    |
| ------------------------------------------------- | -------------------------------------- |
| `npx humic tokens list --json`                    | All tokens with types and values       |
| `npx humic tokens list --type color --json`       | Just color tokens                      |
| `npx humic scales list --json`                    | All color scales with hex values       |
| `npx humic tokens guidelines --json`              | Usage rules and recommendations        |
| `npx humic validate --file src/Button.tsx --json` | Validation results for a specific file |

## Code validation

The `validate` command uses AI to check code against your design system rules. It catches:

* Hardcoded color values that should use tokens
* Magic numbers for spacing that should use primitives
* Inconsistent usage patterns

This requires a Gemini API key (runs locally, no data sent to Humic):

```bash theme={null}
npx humic config set gemini-key AIza...
npx humic validate --file src/components/Card.tsx --json
```

```json theme={null}
{
  "score": 85,
  "issues": [
    {
      "line": 12,
      "severity": "warning",
      "message": "Hardcoded color #333. Use var(--color-neutral-900) instead."
    }
  ]
}
```

## CI integration

Add validation to your CI pipeline to catch design system violations before they're merged:

```bash theme={null}
npx humic login --token $HUMIC_CLI_TOKEN
npx humic validate --file src/**/*.tsx --json
```