How to Generate AI Agent Documentation with `astryx init --features agents`

The astryx init --features agents command generates concise AI agent documentation files—such as AGENTS.md, CLAUDE.md, or .cursorrules—that provide AI coding assistants with component indexes, behavioral rules, and CLI references needed to produce correct XDS component code.

The facebook/astryx CLI ships with a built-in agent-docs generator designed to create the reference files necessary for AI coding assistants to generate valid XDS components. When you invoke astryx init --features agents, the tool assembles a curated knowledge base containing component definitions, prohibited patterns, and CLI shortcuts. These files are deliberately compact (approximately 2 KB) and marked with XDS comment delimiters so AI systems can locate relevant sections instantly.

How the Agent Documentation Generator Works

The generation logic is integrated into the init command flow at packages/cli/src/commands/init.mjs. When the agents feature is selected, the CLI parses the --agent and --agent-docs-path arguments (lines 71-80) and delegates the actual file creation to the installAgentDocs helper function.

The installAgentDocs Implementation

The core assembly logic resides in packages/cli/src/commands/agent-docs.mjs. This module constructs the documentation by compiling three essential sections:

• Component index – A searchable registry of all available components, their import paths, and prop definitions.
• Behavioral rules – Strict prohibitions such as "no raw <div> elements" and "no inline style attributes" that enforce XDS conventions.
• CLI quick-reference – A trimmed command reference including astryx component --list and astryx template for easy copy-pasting into AI prompts.

Once assembled, the write routine creates the target file (e.g., AGENTS.md, CLAUDE.md, or .cursorrules) and prints a success message: ✓ AI agent docs installed → ….

Path Safety and Error Handling

When specifying custom output locations via --agent-docs-path, the CLI validates path safety using the logic in packages/cli/src/lib/path-safety.mjs. If the target path is deemed unsafe (e.g., points outside the project root or to a protected system directory), the command throws a PathSafetyError with a clear, actionable message (lines 88-98).

Generating Documentation for Different AI Agents

The astryx init command supports multiple AI agent formats through the --agent flag. Each target produces a file optimized for that specific assistant's context window and rule structure.

Generate the default agent documentation:

npx astryx init --features agents

Target a specific AI assistant:

npx astryx init --features agents --agent claude
npx astryx init --features agents --agent cursor
npx astryx init --features agents --agent codex

These commands create CLAUDE.md, .cursorrules, or AGENTS.md respectively, each containing the same core XDS knowledge formatted for the target AI.

Customizing Output Paths

By default, files are written to the project root. Use --agent-docs-path to install documentation to arbitrary locations, such as Cursor's user rules directory:

npx astryx init --features agents \
  --agent-docs-path ~/.cursor/rules/xds.mdc

This is particularly useful when managing global AI rules or organizing documentation outside the repository root.

Non-Interactive Mode and CI Integration

The CLI detects interactive versus automated environments via packages/cli/src/utils/interactive.mjs. When running in non-interactive mode (such as CI pipelines), the command skips prompts, installs the docs silently, and exits with status code 0.

For scripted automation or CI pipelines, combine the --json flag for machine-readable output:

npx astryx init --features agents --agent codex --json

This ensures the command completes without hanging on input requests and provides structured output for downstream processing.

Keeping Documentation Current

After upgrading the Astryx CLI to a new version, re-running astryx init --features agents updates the agent documentation in place. This synchronizes the AI's knowledge base with any new components, changed prop signatures, or updated behavioral rules introduced in the latest release.

For a comprehensive guide on integrating these files into your AI workflow, see the documentation source at packages/cli/docs/working-with-ai.doc.mjs (lines 27-55), which covers CLI installation and agent-docs invocation in detail.

Summary

• astryx init --features agents invokes the installAgentDocs helper in packages/cli/src/commands/agent-docs.mjs to generate AI-specific documentation.
• Generated files include component indexes, behavioral prohibitions, and CLI quick-references, wrapped in XDS comment delimiters for rapid AI parsing.
• Use --agent to target specific formats (Claude, Cursor, Codex) and --agent-docs-path to customize the installation location.
• The CLI validates custom paths via path-safety.mjs, throwing PathSafetyError for unsafe destinations.
• Non-interactive mode (detected via interactive.mjs) supports CI automation with the --json flag.

Frequently Asked Questions

What files does astryx init --features agents generate?

The command generates context files for AI assistants, typically named AGENTS.md, CLAUDE.md, or .cursorrules depending on the --agent flag specified. These files contain approximately 2 KB of structured data including component indexes, XDS behavioral rules, and CLI references.

How do I generate documentation for a specific AI agent like Claude or Cursor?

Pass the --agent flag followed by the target agent name. For example, npx astryx init --features agents --agent claude creates CLAUDE.md, while --agent cursor generates .cursorrules in the project root. Omitting the flag defaults to the standard AGENTS.md format.

Can I specify a custom location for the agent documentation files?

Yes. Use the --agent-docs-path argument to define an absolute or relative path. For example, npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc installs the rules directly into Cursor's global configuration. The CLI validates the path using PathSafetyError handling to prevent unsafe writes.

How does the command handle errors or unsafe file paths?

If --agent-docs-path points to a restricted or unsafe directory, the CLI catches the error as PathSafetyError (defined in packages/cli/src/lib/path-safety.mjs) and reports a clear failure message without writing any files. In non-interactive mode, this error is returned as a JSON object when using the --json flag.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}