AI agents

nativecn is built so that AI agents can build whole mobile apps with it and check the result on a real device. Every project gets the Agent Kit: the Rules, Skills and nativecn MCP server, with a Plugin for agent hosts.

create and init write the Agent Kit for the agents you choose with --agents. Supported agents are Claude Code (claude), Codex (codex), Cursor (cursor) and Antigravity (antigravity). To add agents or refresh the kit later, run:

npx nativecn-cli@latest agents --agents claude,cursor --update

If fetching the Skills fails (for example, offline), create and init still finish and print how to retry.

Rules

A Rule is a project-level instruction file that constrains how an agent writes code in your app. nativecn writes its Rules into AGENTS.md (or appends a nativecn section to yours) and adds @AGENTS.md to CLAUDE.md for Claude Code. AGENTS.md stays under 24 KB.

1. Styling: Tokens only, via createStyles. No hard-coded colours or sizes; t.scaleValue(n) for genuine one-offs. No Tailwind, NativeWind or className.
2. Building blocks: all text uses Text, all glyphs use Icon, and Screens are wrapped in Container.
3. Feedback: never Alert.alert or any platform alert. Use nativecn's own toast() and Alert Components.
4. Navigation: the drawer comes only from expo-router/drawer; never install @react-navigation/* or the npm package expo-drawer. SegmentedTabs is for tabs inside a Screen and TabNavigation for the bottom bar; neither is Expo Router's Tabs.
5. Dependencies: npx expo install for Expo SDK packages. Anything else: ask the user first.
6. Storage: AsyncStorage holds only non-sensitive preferences. Tokens, credentials and personal data go in expo-secure-store.
7. Placement: follow structure and the placement rule.
8. The Preset is fixed. Never change preset in components.json or try to switch Style.
9. Adding items: use the MCP tool get_add_command or nativecn-cli add. Always pass --route for Screen Blocks, and --feature too in feature mode. Run --diff before updating, and use -o only when the user asks for their edits to be replaced.
10. Forms: react-hook-form and zod, wired through FormField, with fields inside FocusChain.
11. Accessibility: meet the accessibility checklist. Never remove role or aria-* props.
12. After changes: run get_audit_checklist and fix anything it flags.

AGENTS.md also lists the Skills, the MCP tools and the key commands.

Skills

A Skill is a packaged set of instructions that teaches an agent one mobile task with nativecn. nativecn ships five. The CLI writes one copy of each to .agents/skills/<name>/ (read by Codex, Cursor and Antigravity) and links .claude/skills/<name> to it for Claude Code (a copy on Windows).

The nativecn MCP server

The nativecn MCP server tells an agent which Components, Blocks, Block Variants and Themes exist and what they contain, like shadcn's MCP. It is read-only: it never writes files or runs the CLI.

Local and remote

• Local (npx -y nativecn-cli@latest mcp, over stdio) reads your components.json, so its answers fit your Style, Structure and routes. This is what create, init and agents configure.
• Remote (https://nativecn.dev/mcp) is for browsing without a project. It has the same tools except get_project_config, and answers with the default settings.

Both fetch live data from the nativecn.dev Registry, cache it for a few minutes, and return a clear error rather than a guess when the Registry is unreachable.

MCP config files

The CLI writes one config file per chosen agent:

For example, .mcp.json:

{
  "mcpServers": {
    "nativecn-cli": {
      "command": "npx",
      "args": ["-y", "nativecn-cli@latest", "mcp"]
    }
  }
}

Codex loads .codex/config.toml only in a trusted project.

To browse without a project, point an agent at the remote server instead. In Claude Code:

claude mcp add --transport http nativecn https://nativecn.dev/mcp

AI-friendly docs

Everything on nativecn.dev is also available as plain text for agents, generated from the same sources as the pages:

• Copy for AI, at the top of every docs page, copies the page as clean markdown.
• .md twins: append .md to any docs URL, e.g. /docs/installation.md.
• /llms.txt indexes every page and Registry item; /llms-full.txt has every page in one file.
• Copy to LLM, on every Component and Block page, copies one item's description, add command, props, usage examples and source as a single prompt-ready block. For example, the Pressable Primitive:

Plugin

A Plugin is an agent-host package that bundles the Agent Kit for one-step installation. The nativecn Plugin contains the five Skills and the local MCP server, packaged as a Claude-format marketplace (for Claude Code and Codex) plus Cursor and Antigravity manifests.

Plugins install per user, not per project, so create and init print the install command for each chosen agent rather than running it. A Plugin can't write AGENTS.md, so the nativecn-setup Skill carries the Rules and tells the agent to run init (or agents) the first time it is used in a project.

Visual QA Loop

The Visual QA Loop is an agent-driven design and UX review of your running app, run by the nativecn-visual-qa Skill. The agent navigates Screens and User Flows on a device, captures screenshots, judges them against the Reference Design, traces each problem to its root in the code, fixes small and safe problems, and reports the rest.

It is not pixel comparison and not a test runner, and there is no nativecn-cli qa command. nativecn provides only the Skill and Rules; the agent drives devices with the platform's own tools: adb for Android and xcrun simctl for the iOS Simulator.

The design folder

All optional, at the root of your app:

design/screens/<screen>.png        Reference Design images, such as Figma exports (+ <screen>.dark.png)
design/flows.md                    confirmed User Flows
design/expectations.md             your description of Screens that have no image

• A Reference Design is what a Screen is meant to look like: an image in design/screens/ when there is one, otherwise your description in design/expectations.md.
• A User Flow is a confirmed sequence of Screens and actions, such as sign up → verify code → home. The agent derives flows from your code and docs, asks you to confirm or correct them, and saves them in design/flows.md.
• For a Screen with no image, the agent asks what it should look like or do and records your answer.
• If a Figma MCP server is connected, the agent also reads the design's real values from it.

How the agent judges

At the design-system level, never pixel by pixel:

• spacing on the Token scale;
• typography: the right Text Variant for each role, and a clear hierarchy;
• layout: alignment, safe areas, clipping and overlap;
• Components: the right Component and Variant, with all states present;
• Colour Roles in light and dark;
• misalignment and broken Components;
• non-functional actions: every action does something and leads where the User Flow says.

Every confirmed User Flow is checked end to end against the Screens and the code.

Fix or report

The rule: the agent fixes a problem itself only if the fix is visual-only, stays inside one Screen, uses what already exists (Tokens, Components, Variants) and is easy to undo. Otherwise it reports the problem and waits for you.

Limits on auto-fixes:

• Each stays within one Screen file and its private parts.
• A fix needing more than about 30 changed lines becomes a report.
• After fixing, the agent captures the Screen again to confirm. A fix that doesn't hold after three attempts is reverted and reported.
• The agent never commits. Auto-fixes stay uncommitted for you to review.

The report

Shown in chat and saved as report.md in the run's temp folder. Each finding gives where (the Screen and file:line), what's wrong, the root cause in the code, options with trade-offs (one recommended), the severity (broken, wrong or polish) and the status (auto-fixed or awaiting you).

Allowed device commands

The agent opens, navigates and screenshots only the app under development (its scheme, package and bundle id from app.json, or Expo Go's exp:// URL), using only these commands. Nothing else on the device unless you ask.

Android screenshots are saved, pulled to your computer, then deleted from the phone, every time:

adb shell screencap -p /sdcard/nativecn-qa.png
adb pull /sdcard/nativecn-qa.png <tmp>/nativecn-qa/<device>/<timestamp>-<screen>.png
adb shell rm /sdcard/nativecn-qa.png

• With exactly one Android device attached, commands leave out -s. With several, the agent adds -s <serial> and you are asked to approve.
• iOS commands use booted instead of a Simulator id. iOS flows use deep links plus reading the code, since there is no tap tool.
• Screenshots go to <OS temp>/nativecn-qa/<device>/, and only the last 20 per device are kept. Nothing is left on the phone.
• Installing apps, clearing data, adb push, other adb shell commands, and automation tools such as Maestro are out of scope.

--qa-permissions

By default your agent asks before each device command. To skip those prompts, opt in when you run init or agents:

npx nativecn-cli@latest agents --qa-permissions

It writes auto-approve rules for exactly the commands above:

• Allow rules only. The rules only skip the confirmation prompt for matching commands. Every other command still asks, and nothing is blocked. The Rules and the Skill remain the real guard.
• No deny rules, because they would give false assurance: extra commands can be smuggled through adb shell.
• Cursor: the project files replace your own IDE terminal allowlist in this project, which is why the flag is opt-in.