@codefilabs/tailwind-for-agents

Resolve your Tailwind CSS theme into AI-friendly token maps.

Every AI coding assistant guesses your Tailwind theme from training data. tailwind-for-agents gives them the truth.

Your Tailwind config defines custom spacing, colors, border radii, and fonts. But AI coding assistants -- Claude, Cursor, Copilot, Windsurf, Aider -- don't know about your theme. They hallucinate rounded-lg when your project uses rounded-xl. They suggest text-blue-500 when your palette is entirely custom.

tailwind-for-agents resolves your actual Tailwind theme into lookup tables that any AI assistant can read. Give it a project, get back the truth.

Claude Code Plugin

Install via the codefilabs marketplace:

/plugin marketplace add codefilabs/marketplace
/plugin install tailwind-for-agents@codefilabs

Quick Start

npx @codefilabs/tailwind-for-agents --project .

This produces two files in .tailwind-for-agents/:

• tokens.md -- AI-readable lookup tables (give this to your assistant)
• tokens.json -- Machine-readable structured data (for tooling)

How It Works

1. Auto-detects your Tailwind version (v3 or v4) and setup type
2. Resolves your full theme using the best available strategy
3. Scans your project CSS for additional variables and utility classes
4. Produces lookup tables mapping design values to Tailwind classes

Three resolution strategies, selected automatically:

| Strategy | When Used | How It Works | |----------|-----------|--------------| | v3-node | Tailwind v3 with tailwind.config.js | Calls resolveConfig() on your config | | v4-node | Tailwind v4 with @theme in CSS | Parses theme.css from node_modules | | v4-cli | Tailwind v4 with standalone CLI (e.g., Rails) | Runs the binary, parses :root output + utility classes |

CLI Usage

tailwind-for-agents -- Resolve your Tailwind theme for AI coding assistants

Usage:
  npx @codefilabs/tailwind-for-agents [options]
  tfa [options]

Options:
  --project <path>     Project root (default: current directory)
  --output <path>      Output directory (default: <project>/.tailwind-for-agents)
  --strategy <name>    Force strategy: v3-node, v4-node, v4-cli
  --format <type>      Output format: json, markdown, both (default: both)
  --mcp                Start as MCP server (stdio transport)
  --help               Show this help message
  --version            Show version

Examples

# Resolve current directory
npx @codefilabs/tailwind-for-agents

# Resolve a specific project
npx @codefilabs/tailwind-for-agents --project /path/to/my-app

# Only generate markdown
npx @codefilabs/tailwind-for-agents --project . --format markdown

# Force a specific strategy
npx @codefilabs/tailwind-for-agents --project . --strategy v4-cli

# Custom output directory
npx @codefilabs/tailwind-for-agents --project . --output ./docs/tokens

Programmatic API

const { resolve, lookup, formatJSON, formatMarkdown } = require('@codefilabs/tailwind-for-agents');

// Resolve all tokens from a project
const { tokens, meta } = await resolve('/path/to/project');

// Quick lookup: pixel value -> Tailwind class
const result = lookup(tokens, '16px');
// { type: 'numeric', matches: [{ category: 'spacing', class: { padding: 'p-4', ... } }] }

// Quick lookup: hex color -> Tailwind class
const color = lookup(tokens, '#3b82f6');
// { type: 'color', matches: [{ category: 'colors', classes: ['blue-500'] }] }

// Format as JSON string
const json = formatJSON({ tokens, meta });

// Format as Markdown string
const md = formatMarkdown(tokens, meta);

resolve(projectRoot, options?)

Resolves a project's full Tailwind theme into structured token data.

Parameters:

• projectRoot (string) -- Absolute path to project root
• options.strategy (string, optional) -- Force a strategy: 'v3-node', 'v4-node', 'v4-cli'
• options.silent (boolean, optional) -- Suppress console output

Returns: Promise<{ tokens, meta }>

• tokens -- Structured token data with categories: spacing, colors, borderRadius, fontSize, fontWeight, fontFamily, lineHeight, screens, cssVars
• meta -- Resolution metadata: project, tailwindVersion, strategy, generatedAt, sourceFiles

lookup(tokens, value)

Look up a design value and find matching Tailwind classes.

Parameters:

• tokens (object) -- Resolved token data from resolve()
• value (string) -- Value to look up: '16px', '16', '#3b82f6', '700'

Returns: { type: string, matches: object[] }

formatJSON({ tokens, meta })

Format resolved data as a JSON string.

formatMarkdown(tokens, meta)

Format resolved data as Markdown lookup tables.

MCP Server

tailwind-for-agents includes a built-in MCP (Model Context Protocol) server that exposes two tools:

• get_tokens -- Resolve a project's full Tailwind theme into token lookup tables
• lookup -- Look up a specific design value and find the matching Tailwind class(es)

Claude Code

Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "tailwind-for-agents": {
      "command": "npx",
      "args": ["@codefilabs/tailwind-for-agents", "--mcp"]
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "tailwind-for-agents": {
      "command": "npx",
      "args": ["@codefilabs/tailwind-for-agents", "--mcp"]
    }
  }
}

Generic

Start the MCP server directly:

npx @codefilabs/tailwind-for-agents --mcp

This starts a stdio-based MCP server. The server caches resolved tokens per project path -- subsequent lookup calls after the first get_tokens are instant.

AI Assistant Setup

After generating tokens, tell your AI assistant to use them. Add one of these to your project:

Claude Code (CLAUDE.md)

For Tailwind classes, always check .tailwind-for-agents/tokens.md before guessing.
Use the exact spacing, color, and border-radius classes defined in the token tables.

Cursor (.cursorrules)

For Tailwind classes, always check .tailwind-for-agents/tokens.md before guessing.
Use the exact spacing, color, and border-radius classes defined in the token tables.

GitHub Copilot (.github/copilot-instructions.md)

For Tailwind classes, always check .tailwind-for-agents/tokens.md before guessing.
Use the exact spacing, color, and border-radius classes defined in the token tables.

Auto-Regeneration with Claude Code Hooks

Keep your token files fresh automatically. These Claude Code hooks regenerate .tailwind-for-agents/ whenever Claude edits a Tailwind source file — so your AI assistant always has current data without manually re-running the CLI.

How it works: A PostToolUse hook sets a flag file when Claude writes or edits a Tailwind source file. A Stop hook checks for that flag at end of session and runs tailwind-for-agents if needed. This avoids running the tool on every file change — it runs once, at the end.

1. Create the hook scripts

.claude/hooks/flag-css-changes.sh — sets the flag when a source file changes:

#!/usr/bin/env bash
# PostToolUse hook: sets a flag when a Tailwind source file is written or edited.
# This signals the Stop hook to regenerate .tailwind-for-agents/ via tailwind-for-agents.

set -euo pipefail

command -v jq >/dev/null 2>&1 || exit 0

INPUT=$(cat)

TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
if [[ "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "Edit" ]]; then
  exit 0
fi

FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
if [[ -z "$FILE_PATH" ]]; then
  exit 0
fi

# Adjust this pattern to match your project's Tailwind source files.
# Examples:
#   Rails:   'app/assets/(tailwind|stylesheets)/.*\.css$'
#   Node:    'src/.*\.css$|tailwind\.config\.(js|ts|mjs|cjs)$'
if echo "$FILE_PATH" | grep -qE '\.(css|scss)$|tailwind\.config\.(js|ts|mjs|cjs)$'; then
  PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "$0")/../.." && pwd)}"
  touch "$PROJECT_DIR/.claude/tailwind_tokens_needed"
fi

exit 0

.claude/hooks/regenerate-tokens.sh — regenerates tokens at session end:

#!/usr/bin/env bash
# Stop hook: regenerates .tailwind-for-agents/ if Tailwind source files changed this session.

set -euo pipefail

PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "$0")/../.." && pwd)}"
FLAG="$PROJECT_DIR/.claude/tailwind_tokens_needed"

if [[ ! -f "$FLAG" ]]; then
  exit 0
fi

rm -f "$FLAG"

echo "[tailwind-for-agents] Tailwind source files changed — regenerating .tailwind-for-agents/..."
cd "$PROJECT_DIR"
npx @codefilabs/tailwind-for-agents --project . 2>&1
echo "[tailwind-for-agents] Done."

exit 0

Make both scripts executable:

chmod +x .claude/hooks/flag-css-changes.sh
chmod +x .claude/hooks/regenerate-tokens.sh

2. Register the hooks in .claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/flag-css-changes.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/regenerate-tokens.sh"
          }
        ]
      }
    ]
  }
}

Tip: Narrow the file pattern in flag-css-changes.sh to your project's specific paths for better performance. For example, a Rails project with Tailwind source in app/assets/tailwind/ would use 'app/assets/tailwind/.*\.css$' instead of the generic pattern.

Supported Setups

| Setup | Detected By | Strategy | |-------|-------------|----------| | Tailwind v3 (npm) | tailwind.config.js + tailwindcss in node_modules | v3-node | | Tailwind v4 (npm) | tailwindcss v4+ in node_modules | v4-node | | Tailwind v4 (standalone CLI) | tailwindcss binary in project or tailwindcss-rails gem | v4-cli | | Rails with tailwindcss-rails | Gemfile with tailwindcss-rails | v4-cli |

Output Format

Markdown (tokens.md)

The markdown file contains lookup tables optimized for AI assistants:

## Quick Reference Tables

### Spacing

| px | padding | px/py | margin | mx/my | gap | width | height |
|----|---------|-------|--------|-------|-----|-------|--------|
| **4px** | `p-1` | `px-1`/`py-1` | `m-1` | `mx-1`/`my-1` | `gap-1` | `w-1` | `h-1` |
| **8px** | `p-2` | `px-2`/`py-2` | `m-2` | `mx-2`/`my-2` | `gap-2` | `w-2` | `h-2` |
| **16px** | `p-4` | `px-4`/`py-4` | `m-4` | `mx-4`/`my-4` | `gap-4` | `w-4` | `h-4` |

### Colors (hex -> utility name)

| hex | name(s) |
|-----|---------|
| `#3b82f6` | blue-500 |
| `#ef4444` | red-500 |
| `#22c55e` | green-500 |

### Border Radius

| px | class |
|----|-------|
| **4px** | `rounded` |
| **6px** | `rounded-md` |
| **8px** | `rounded-lg` |

JSON (tokens.json)

Structured data with lookup maps:

{
  "meta": {
    "project": "/path/to/project",
    "tailwindVersion": "4.0.0",
    "strategy": "v4-node",
    "generatedAt": "2026-02-20T12:00:00.000Z"
  },
  "spacing": {
    "byPx": {
      "4": { "padding": "p-1", "margin": "m-1", "gap": "gap-1", ... },
      "8": { "padding": "p-2", "margin": "m-2", "gap": "gap-2", ... }
    }
  },
  "colors": {
    "byHex": {
      "#3b82f6": ["blue-500"],
      "#ef4444": ["red-500"]
    }
  }
}

Add to .gitignore

The generated token files should be gitignored (they are derived from your theme and can be regenerated):

# tailwind-for-agents output
.tailwind-for-agents/

Requirements

• Node.js >= 18
• A project with Tailwind CSS installed (v3 or v4)

License

MIT -- see LICENSE.