> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# IDE Integration

> Set up AIOX agents in Claude Code, Cursor, Codex CLI, Gemini CLI, and other AI development platforms

## Supported IDEs

AIOX integrates with multiple AI-powered development platforms. Choose the one that fits your workflow.

<CardGroup cols={2}>
  <Card title="Claude Code" icon="c" color="#7C3AED">
    **Best AIOX integration** - Full hooks, MCP, slash commands
  </Card>

  <Card title="Codex CLI" icon="terminal" color="#F97316">
    **Terminal-first** - AGENTS.md, /skills, strong CLI workflow
  </Card>

  <Card title="Cursor" icon="square-c" color="#3B82F6">
    **Popular AI IDE** - Composer, @mentions, multi-file editing
  </Card>

  <Card title="Gemini CLI" icon="gem" color="#10B981">
    **Google AI** - Native hooks, slash launchers, MCP
  </Card>

  <Card title="GitHub Copilot" icon="github" color="#6B7280">
    **GitHub integration** - Repo instructions, PR assistance
  </Card>

  <Card title="AntiGravity" icon="cloud" color="#8B5CF6">
    **Google Cloud** - Workflow-based, Firebase tools
  </Card>
</CardGroup>

## Compatibility Matrix

<Note>
  **Version:** AIOX 4.2.11 | Enforced by compatibility contract at `.aiox-core/infrastructure/contracts/compatibility/aiox-4.2.11.yaml`
</Note>

| IDE/CLI            | Overall Status | Agent Activation               | Auto-Checks | Workaround               |
| ------------------ | -------------- | ------------------------------ | ----------- | ------------------------ |
| **Claude Code**    | ✅ Works        | `/agent-name`                  | ✅ Full      | —                        |
| **Gemini CLI**     | ✅ Works        | `/aiox-menu` → `/aiox-<agent>` | ✅ High      | —                        |
| **Codex CLI**      | ⚠️ Limited     | `/skills` → `aiox-<agent-id>`  | ⚠️ Partial  | `npm run sync:ide:codex` |
| **Cursor**         | ⚠️ Limited     | `@agent` + rules               | ❌ None      | Manual validation        |
| **GitHub Copilot** | ⚠️ Limited     | Chat modes + instructions      | ❌ None      | Repo instructions + MCP  |
| **AntiGravity**    | ⚠️ Limited     | Workflow-driven                | ❌ None      | Generated workflows      |

### What "Auto-Checks" Means

Some IDEs automatically run checks before and after agent actions (context validation, rule enforcement, audit logging):

| IDE            | Auto-Check Level | What's Missing                         | Compensation                           |
| -------------- | ---------------- | -------------------------------------- | -------------------------------------- |
| Claude Code    | **Full**         | Nothing                                | Built-in checks                        |
| Gemini CLI     | **High**         | Minor timing differences               | Native checks                          |
| Codex CLI      | **Partial**      | Session tracking, some pre/post checks | Use AGENTS.md + sync scripts           |
| Cursor         | **None**         | All automatic checks                   | Synced rules + MCP + manual validators |
| GitHub Copilot | **None**         | All automatic checks                   | Repo instructions + MCP                |
| AntiGravity    | **None**         | All automatic checks                   | Workflows + manual validators          |

## Quick Decision Guide

<Steps>
  <Step title="Best for Beginners">
    **Claude Code** or **Gemini CLI** - Most automation, fewest manual steps
  </Step>

  <Step title="Terminal Workflow">
    **Codex CLI** - Terminal-first with `/skills` activation
  </Step>

  <Step title="Visual IDE">
    **Cursor** - Popular AI IDE with composer and multi-file editing
  </Step>

  <Step title="Requires Manual Steps">
    **Cursor, Copilot, AntiGravity** - Work but need manual validation
  </Step>
</Steps>

## Claude Code Setup

<Note>
  **Recommendation Level:** Best AIOX integration
</Note>

### Configuration

```yaml theme={null}
config_file: .claude/CLAUDE.md
agent_folder: .claude/commands/AIOX/agents
activation: /agent-name (slash commands)
format: full-markdown-yaml
mcp_support: native
special_features:
  - Task tool for subagents
  - Native MCP integration
  - Hooks system (pre/post)
  - Custom skills
  - Memory persistence
```

### Installation

<Steps>
  <Step title="Install AIOX">
    AIOX automatically creates `.claude/` directory on init:

    ```bash theme={null}
    npx aiox-core init my-project
    ```
  </Step>

  <Step title="Sync Agents">
    ```bash theme={null}
    npm run sync:ide:claude
    ```
  </Step>

  <Step title="Verify Setup">
    ```bash theme={null}
    ls -la .claude/commands/AIOX/agents/
    ```

    You should see: `/dev`, `/qa`, `/architect`, etc.
  </Step>

  <Step title="Validate Integration">
    ```bash theme={null}
    npm run validate:claude-sync
    npm run validate:claude-integration
    ```
  </Step>
</Steps>

### MCP Configuration

Configure MCP servers in `~/.claude.json`:

```json theme={null}
{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/sse"
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    }
  }
}
```

### Usage

<CodeGroup>
  ```bash Activate Agent theme={null}
  /dev
  /architect
  /qa
  ```

  ```bash View Available Commands theme={null}
  /dev
  *help
  ```

  ```bash Execute Task theme={null}
  /dev
  *develop
  ```
</CodeGroup>

## Codex CLI Setup

<Note>
  **Recommendation Level:** Best for terminal-first workflow
</Note>

### Configuration

```yaml theme={null}
config_file: AGENTS.md
agent_folder: .codex/agents
skills_folder: .codex/skills (source), ~/.codex/skills (Codex menu)
activation: terminal instructions
format: markdown
mcp_support: native via Codex tooling
special_features:
  - AGENTS.md project instructions
  - /skills activators (aiox-<agent-id>)
  - Strong CLI workflow
  - Repository script integration
  - Notify command + tool hooks
```

### Installation

<Steps>
  <Step title="Keep AGENTS.md at Root">
    AIOX creates `AGENTS.md` at repository root automatically
  </Step>

  <Step title="Sync Codex Files">
    ```bash theme={null}
    npm run sync:ide:codex
    npm run sync:skills:codex
    ```

    This generates:

    * `.codex/agents/*.md`
    * `.codex/skills/aiox-*.md` (project-local skills)
  </Step>

  <Step title="Validate Setup">
    ```bash theme={null}
    npm run validate:codex-sync
    npm run validate:codex-integration
    npm run validate:codex-skills
    ```
  </Step>

  <Step title="Verify Files">
    ```bash theme={null}
    ls -la AGENTS.md .codex/agents/ .codex/skills/
    ```
  </Step>
</Steps>

### Global vs Local Skills

<Warning>
  This repository uses **project-local skills** (`.codex/skills`). Only use global installation for testing outside this repo.
</Warning>

```bash theme={null}
# Local skills (recommended for this repo)
npm run sync:skills:codex

# Global skills (use only outside this project)
npm run sync:skills:codex:global
```

### Usage

<Steps>
  <Step title="Open Codex CLI">
    Launch Codex CLI in your project directory
  </Step>

  <Step title="Access Skills Menu">
    Type `/skills` and press Enter
  </Step>

  <Step title="Select Agent">
    Choose from:

    * `aiox-dev`
    * `aiox-architect`
    * `aiox-qa`
    * `aiox-pm`
    * etc.
  </Step>

  <Step title="View Commands">
    ```bash theme={null}
    *help
    ```
  </Step>
</Steps>

## Cursor Setup

<Note>
  **Recommendation Level:** Popular AI IDE with limitations
</Note>

### Configuration

```yaml theme={null}
config_file: .cursor/rules.md
agent_folder: .cursor/rules
activation: @agent-name
format: condensed-rules
mcp_support: via configuration
special_features:
  - Composer integration
  - Chat modes
  - @codebase context
  - Multi-file editing
  - Subagents (latest releases)
  - Long-running workflows (preview)
```

### Installation

<Steps>
  <Step title="Sync Cursor Files">
    ```bash theme={null}
    npm run sync:ide:cursor
    ```
  </Step>

  <Step title="Verify Setup">
    ```bash theme={null}
    ls -la .cursor/rules/
    ```
  </Step>

  <Step title="Configure MCP (Optional)">
    Create `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "context7": {
          "url": "https://mcp.context7.com/sse"
        }
      }
    }
    ```
  </Step>
</Steps>

### Usage

<CodeGroup>
  ```text Activate Agent theme={null}
  @dev
  @architect
  @qa
  ```

  ```text Use Composer theme={null}
  Open Composer (Cmd/Ctrl+I)
  @dev implement feature X
  ```

  ```text Chat Mode theme={null}
  Open Chat
  @dev *help
  ```
</CodeGroup>

### Limitations

<Warning>
  * **No automatic pre/post checks** - Run validators manually
  * **No automatic audit trail** - Use git for tracking
  * **Limited session tracking** - Compensate with synced rules
</Warning>

**Workaround:**

```bash theme={null}
# After significant changes, validate manually
npm run validate:parity
```

## Gemini CLI Setup

<Note>
  **Recommendation Level:** Good with native hooks support
</Note>

### Configuration

```yaml theme={null}
config_file: .gemini/rules.md
agent_folder: .gemini/rules/AIOX/agents
activation: slash launcher commands
format: text
mcp_support: native
special_features:
  - Google AI models
  - CLI-based workflow
  - Multimodal support
  - Native hooks events
  - Native MCP servers
  - Rapidly evolving UX
```

### Installation

<Steps>
  <Step title="Run Installer">
    Select `gemini` during IDE selection:

    ```bash theme={null}
    npx aiox-core init my-project
    ```
  </Step>

  <Step title="Sync Gemini Files">
    ```bash theme={null}
    npm run sync:ide:gemini
    ```

    This creates:

    * `.gemini/rules.md`
    * `.gemini/rules/AIOX/agents/*.md`
    * `.gemini/commands/*.toml` (slash commands)
    * `.gemini/hooks/*.js`
    * `.gemini/settings.json`
  </Step>

  <Step title="Validate Integration">
    ```bash theme={null}
    npm run validate:gemini-sync
    npm run validate:gemini-integration
    ```
  </Step>
</Steps>

### Usage

<CodeGroup>
  ```bash Menu Launcher theme={null}
  /aiox-menu
  # Shows all available agents
  ```

  ```bash Direct Agent theme={null}
  /aiox-dev
  /aiox-architect
  /aiox-qa
  ```

  ```bash Generic Launcher theme={null}
  /aiox-agent dev
  ```
</CodeGroup>

## GitHub Copilot Setup

<Note>
  **Recommendation Level:** Good for GitHub integration
</Note>

### Configuration

```yaml theme={null}
config_file: .github/copilot-instructions.md
agent_folder: .github/agents
activation: chat modes
format: text
mcp_support: via VS Code MCP config
special_features:
  - GitHub integration
  - PR assistance
  - Code review
  - Repo instructions
```

### Installation

<Steps>
  <Step title="Enable Copilot">
    Enable GitHub Copilot in your repository
  </Step>

  <Step title="Sync Instructions">
    ```bash theme={null}
    npm run sync:ide
    ```

    Creates `.github/copilot-instructions.md`
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    cat .github/copilot-instructions.md
    ```
  </Step>
</Steps>

### Usage

Copilot reads repository instructions automatically. Use chat modes:

```text theme={null}
@workspace implement feature X following AIOX patterns
```

## AntiGravity Setup

<Note>
  **Recommendation Level:** Good for Google Cloud integration
</Note>

### Configuration

```yaml theme={null}
config_file: .antigravity/rules.md
config_json: .antigravity/antigravity.json
agent_folder: .agent/workflows
activation: workflow-based
format: cursor-style
mcp_support: native (Google)
special_features:
  - Google Cloud integration
  - Workflow system
  - Native Firebase tools
```

### Installation

<Steps>
  <Step title="Sync AntiGravity Files">
    ```bash theme={null}
    npm run sync:ide
    ```
  </Step>

  <Step title="Configure Google Cloud">
    Set up Google Cloud credentials
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    ls -la .antigravity/
    ```
  </Step>
</Steps>

## Sync System

### How Sync Works

AIOX maintains a **single source of truth** for agents and syncs to all IDEs:

```mermaid theme={null}
graph TD
    A[.aiox-core/development/agents/] --> B[Source of Truth]
    B --> C[.claude/]
    B --> D[.codex/]
    B --> E[.cursor/]
    B --> F[.gemini/]
    B --> G[.github/]
    B --> H[.antigravity/]
```

### Sync Commands

<CodeGroup>
  ```bash Sync All IDEs theme={null}
  npm run sync:ide
  ```

  ```bash Sync Specific IDE theme={null}
  npm run sync:ide:claude
  npm run sync:ide:codex
  npm run sync:ide:cursor
  npm run sync:ide:gemini
  npm run sync:ide:github-copilot
  npm run sync:ide:antigravity
  ```

  ```bash Check Sync Status theme={null}
  npm run sync:ide:check
  ```

  ```bash Validate All IDEs theme={null}
  npm run validate:parity
  ```
</CodeGroup>

### Automatic Sync

Configure auto-sync in `.aiox-core/core/config/sync.yaml`:

```yaml theme={null}
auto_sync:
  enabled: true
  watch_paths:
    - .aiox-core/development/agents/
  platforms:
    - claude
    - codex
    - cursor
    - gemini
    - github-copilot
    - antigravity
```

## Migration Between IDEs

### From Cursor to Claude Code

<Steps>
  <Step title="Export Cursor Rules">
    ```bash theme={null}
    cp -r .cursor/rules/ ./rules-backup/
    ```
  </Step>

  <Step title="Sync to Claude">
    ```bash theme={null}
    npm run sync:ide:claude
    ```
  </Step>

  <Step title="Verify Migration">
    ```bash theme={null}
    diff -r ./rules-backup/ .claude/commands/AIOX/agents/
    ```
  </Step>
</Steps>

### From Claude Code to Codex CLI

<Steps>
  <Step title="Sync to Codex">
    ```bash theme={null}
    npm run sync:ide:codex
    npm run sync:skills:codex
    ```
  </Step>

  <Step title="Validate">
    ```bash theme={null}
    npm run validate:codex-sync
    npm run validate:codex-integration
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent Not Appearing">
    ```bash theme={null}
    # Verify agent exists
    ls .aiox-core/development/agents/

    # Re-sync
    npm run sync:ide

    # Check platform-specific directory
    ls .claude/commands/AIOX/agents/
    ls .codex/skills/
    ls .cursor/rules/agents/
    ```
  </Accordion>

  <Accordion title="Sync Conflicts">
    ```bash theme={null}
    # Preview changes
    npm run sync:ide -- --dry-run

    # Backup before force sync
    cp -r .cursor/rules/ .cursor/rules.backup/
    npm run sync:ide
    ```
  </Accordion>

  <Accordion title="MCP Not Working">
    ```bash theme={null}
    # Check MCP status
    aiox mcp status

    # Verify config
    cat ~/.claude.json  # Claude Code
    cat .cursor/mcp.json  # Cursor
    ```
  </Accordion>

  <Accordion title="Validation Failures">
    ```bash theme={null}
    # Run full parity check
    npm run validate:parity

    # Check specific IDE
    npm run validate:claude-integration
    npm run validate:codex-integration
    npm run validate:gemini-integration
    ```
  </Accordion>
</AccordionGroup>

## Platform Decision Tree

```mermaid theme={null}
graph TD
    A[Choose IDE] --> B{Use Claude/Anthropic API?}
    B -->|Yes| C[Claude Code]
    B -->|No| D{Prefer VS Code?}
    D -->|Yes| E{Want Extension?}
    E -->|Yes| F[GitHub Copilot]
    E -->|No| F
    D -->|No| G{Dedicated AI IDE?}
    G -->|Yes| H{Which Model?}
    H -->|Claude/GPT| I[Cursor]
    G -->|No| J{Use Google Cloud?}
    J -->|Yes| K[AntiGravity]
    J -->|No| L{Terminal First?}
    L -->|Yes| M[Codex CLI]
    L -->|No| N[Gemini CLI]
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Always Validate" icon="check-circle">
    Run validation after syncing:

    ```bash theme={null}
    npm run validate:parity
    ```
  </Card>

  <Card title="Version Control Sync Files" icon="git">
    Commit IDE-specific directories:

    * `.claude/`
    * `.codex/`
    * `.cursor/`
  </Card>

  <Card title="Use Auto-Sync" icon="arrows-rotate">
    Enable automatic syncing in `sync.yaml`
  </Card>

  <Card title="Test in Multiple IDEs" icon="grid">
    Ensure agents work across platforms
  </Card>
</CardGroup>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Agent Reference" icon="users" href="/agents/overview">
    See all available agents and commands
  </Card>

  <Card title="Custom Agents" icon="wrench" href="/advanced/custom-agents">
    Create your own agent definitions
  </Card>

  <Card title="Squads" icon="people-group" href="/advanced/squads">
    Organize agents into teams
  </Card>

  <Card title="ADE System" icon="brain-circuit" href="/advanced/ade">
    Autonomous Development Engine
  </Card>
</CardGroup>