Working with AI

The design system is built to be AI-friendly: consistent naming, predictable prop patterns, and a CLI that feeds structured documentation directly into AI context windows. But models still need the right context to avoid falling back to generic React patterns or inventing props.

The CLI includes a built-in agent docs system that generates context files for your AI tool of choice. One command sets up everything your AI needs to write correct component code.

Tell your AI to install the CLI and set itself up:

text
Install @astryxdesign/cli and run `npx @astryxdesign/cli init --features agents` to set up your Astryx context. Read the generated file.

That's it. The init --features agents command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, npx @astryxdesign/cli upgrade --from <old version> reports a stale block and adding --apply refreshes it.

By default this writes the instructions to AGENTS.md (the tool-agnostic standard most agents read), in the project root: the nearest folder whose package.json declares an Astryx package, else the nearest with any package.json. The search stops at the repository root. In the home folder, or in a settings folder in it outside a project, init writes no agent docs: every folder of the home folder whose name starts with a dot (~/.claude, ~/.gemini, ~/.codex) is a settings folder, and such a folder itself never counts as a project, even with a package.json; a project below it with its own package.json, such as an agent worktree, is set up normally. Claude Code skips AGENTS.md when the project has a CLAUDE.md or .claude/CLAUDE.md, so init also writes them to that file, even when it imports AGENTS.md: Claude Code does not follow that import in a session started in a subfolder. When both files exist, root CLAUDE.md gets the copy and a copy in .claude/CLAUDE.md is removed, unless the project ignores CLAUDE.md, in which case a .claude/CLAUDE.md the project commits keeps a copy. Gemini CLI reads only GEMINI.md, so init adds a one-line import of AGENTS.md there, unless GEMINI.md already imports it. upgrade keeps the copies in sync. The block between the Astryx markers belongs to Astryx: init and upgrade write, refresh, and remove it whatever the project's ignore rules or generated markers say, and never change the text around it. To target a specific tool's file instead:

bash
npx @astryxdesign/cli init --features agents --agent claude    # CLAUDE.md if present, else .claude/CLAUDE.md
npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules if present, else AGENTS.md
npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)
npx @astryxdesign/cli init --features agents --agent hermes    # .hermes.md or HERMES.md if present, else AGENTS.md
npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)
npx @astryxdesign/cli init --features agents --agent all       # every agent file present except GEMINI.md, else AGENTS.md and .claude/CLAUDE.md

With --agent all, GEMINI.md keeps its one-line import of AGENTS.md. With --agent claude or --agent all, as by default, when CLAUDE.md gets the instructions, .claude/CLAUDE.md gets none and a copy already there is removed, unless the project ignores CLAUDE.md: a fresh clone does not have it, so a .claude/CLAUDE.md the project commits gets a copy too, with --agent claude and --agent all alike. init --remove-agents removes them at the project root and in the folder it runs in.

For agents that work outside any one project, your global install keeps one short Astryx skill, ~/.agents/skills/astryx/SKILL.md, linked into the skill folders agent tools read, such as ~/.claude/skills/astryx. It tells agents Astryx is there and when to use it; npx @astryxdesign/cli init --user writes it now or, with --remove-agents, turns it off. Inside a project, agents follow that project's own agent docs. See npx @astryxdesign/cli docs global/computer-agent-guide.

The generated context teaches your AI a 3-step workflow before writing any UI code:

1. npx @astryxdesign/cli build "<idea>": get the page template to start from (always one: the closest match, or the app shell), two other templates, and the blocks and components for the parts it lacks
2. npx @astryxdesign/cli template <name> <path>: scaffold that template into the project, keep its frame and spacing, and replace its content
3. npx @astryxdesign/cli component <Name>: read props and examples for every component used

It also includes rules that prevent common mistakes (start every page from a template, no raw divs, no style={{}}, use tokens not magic values), a CLI quick reference, and package-labeled integration guidance when a configured manifest declares agentDocs. After setup, you shouldn't need to manually correct your AI on these conventions; the agent docs handle it at the system level.

Cursor reads project rules from .cursor/rules/. To keep the Astryx context in a rule of its own, write it there. Give a path relative to the project root, such as .cursor/rules/astryx.mdc; an absolute path is refused.

bash
npx @astryxdesign/cli init --features agents --agent-docs-path .cursor/rules/astryx.mdc

Rerunning the same command rewrites only the Astryx block, so frontmatter you add above it (such as alwaysApply: true) stays.

Paste this into your AI before writing any component code. If your AI can't answer these questions, it'll know to install the agent docs first.

text
Before writing any Astryx code, check your knowledge:
​
1. What is the correct import path for Button?
2. How do you make a Dialog non-dismissible?
3. What prop does Selector use for its items?
​
If you don't know all three, run `npx @astryxdesign/cli init --features agents` to generate agent docs, then read the generated file.

AI agents frequently invoke the CLI with incorrect paths (e.g. node_modules/@astryxdesign/cli/bin/docs.mjs instead of astryx.mjs), leading to silent failures. Adding an npm script alias with the correct path eliminates this entirely.

json
"scripts": {
  "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}

With this alias, agents run npm run astryx -- component --list instead of guessing the binary path. The -- separator is standard npm convention for passing flags to scripts.

bash
npm run astryx -- component --list
npm run astryx -- component Dialog --dense
npm run astryx -- docs styling --full --detail brief
npm run astryx -- docs tokens --dense

For a shorter read, add --detail brief (one line per section) or --detail compact. --dense swaps in a shorter text where a doc ships one. Use them when pasting CLI output into a web-based AI tool like ChatGPT or Claude.

bash
npx @astryxdesign/cli docs styling --full --detail brief
npx @astryxdesign/cli component Dialog --detail compact
npx @astryxdesign/cli docs principles --dense

Astryx ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the Astryx design system directly, searching for components, reading full documentation, and pulling code examples on demand.

The MCP server exposes two tools: search(query) for discovering components, doc topics, and templates; and get(name) for retrieving full documentation with props, usage, and examples.

Add the server to your MCP config file. The entry is a remote HTTP server, and the exact shape differs per client, so use the snippet for the tool you run. An entry with an unrecognized transport is skipped with a warning rather than an error, which reads as a server that connects but exposes no tools.

json
{
  "mcpServers": {
    "astryx": {
      "type": "http",
      "url": "https://astryx.atmeta.com/mcp"
    }
  }
}

Claude Code can also write that entry from the terminal:

bash
claude mcp add --transport http astryx https://astryx.atmeta.com/mcp

json
{
  "mcpServers": {
    "astryx": {
      "type": "streamableHttp",
      "url": "https://astryx.atmeta.com/mcp"
    }
  }
}

json
{
  "mcpServers": {
    "astryx": {
      "url": "https://astryx.atmeta.com/mcp"
    }
  }
}

Claude Desktop is the exception: claude_desktop_config.json holds local stdio servers, so a remote server is added through Settings, then Connectors, then Add custom connector, pasting the URL above.

Once connected, your AI tool can search for components by natural language (e.g. "dropdown menu", "success message") and retrieve full documentation without any manual CLI invocation. The server uses the same keyword index from component docs, so search quality improves automatically as component documentation is updated.

In global mode: your global install keeps one Astryx skill in your home folder, linked into the folders agent tools read, so agents outside any project know Astryx is there; inside a project, its own agent docs come first. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs global/computer-agent-guide.