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.

Claude Code

Best AIOX integration - Full hooks, MCP, slash commands

Codex CLI

Terminal-first - AGENTS.md, /skills, strong CLI workflow

Cursor

Popular AI IDE - Composer, @mentions, multi-file editing

Gemini CLI

Google AI - Native hooks, slash launchers, MCP

GitHub Copilot

GitHub integration - Repo instructions, PR assistance

AntiGravity

Google Cloud - Workflow-based, Firebase tools

Compatibility Matrix

Version: AIOX 4.2.11 | Enforced by compatibility contract at .aiox-core/infrastructure/contracts/compatibility/aiox-4.2.11.yaml

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

1. Best for Beginners

   Claude Code or Gemini CLI - Most automation, fewest manual steps

2. Terminal Workflow

   Codex CLI - Terminal-first with /skills activation

3. Visual IDE

   Cursor - Popular AI IDE with composer and multi-file editing

4. Requires Manual Steps

   Cursor, Copilot, AntiGravity - Work but need manual validation

Claude Code Setup

Recommendation Level: Best AIOX integration

Configuration

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

1. Install AIOX

   AIOX automatically creates .claude/ directory on init:

   npx aiox-core init my-project
   
2. Sync Agents

   npm run sync:ide:claude
   
3. Verify Setup

   ls -la .claude/commands/AIOX/agents/
   

   You should see: /dev, /qa, /architect, etc.

4. Validate Integration

   npm run validate:claude-sync
   npm run validate:claude-integration
   

MCP Configuration

Configure MCP servers in ~/.claude.json:

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

Usage

Activate Agent

/dev
/architect
/qa

Codex CLI Setup

Recommendation Level: Best for terminal-first workflow

Configuration

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

1. Keep AGENTS.md at Root

   AIOX creates AGENTS.md at repository root automatically

2. Sync Codex Files

   npm run sync:ide:codex
   npm run sync:skills:codex
   

   This generates:

   • .codex/agents/*.md
   • .codex/skills/aiox-*.md (project-local skills)
3. Validate Setup

   npm run validate:codex-sync
   npm run validate:codex-integration
   npm run validate:codex-skills
   
4. Verify Files

   ls -la AGENTS.md .codex/agents/ .codex/skills/
   

Global vs Local Skills

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

# 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

1. Open Codex CLI

   Launch Codex CLI in your project directory

2. Access Skills Menu

   Type /skills and press Enter

3. Select Agent

   Choose from:

   • aiox-dev
   • aiox-architect
   • aiox-qa
   • aiox-pm
   • etc.
4. View Commands

   *help
   

Cursor Setup

Recommendation Level: Popular AI IDE with limitations

Configuration

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

1. Sync Cursor Files

   npm run sync:ide:cursor
   
2. Verify Setup

   ls -la .cursor/rules/
   
3. Configure MCP (Optional)

   Create .cursor/mcp.json:

   {
     "mcpServers": {
       "context7": {
         "url": "https://mcp.context7.com/sse"
       }
     }
   }
   

Usage

Activate Agent

@dev
@architect
@qa

Limitations

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

Workaround:

# After significant changes, validate manually
npm run validate:parity

Gemini CLI Setup

Recommendation Level: Good with native hooks support

Configuration

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

1. Run Installer

   Select gemini during IDE selection:

   npx aiox-core init my-project
   
2. Sync Gemini Files

   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
3. Validate Integration

   npm run validate:gemini-sync
   npm run validate:gemini-integration
   

Usage

Menu Launcher

/aiox-menu
# Shows all available agents

GitHub Copilot Setup

Recommendation Level: Good for GitHub integration

Configuration

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

1. Enable Copilot

   Enable GitHub Copilot in your repository

2. Sync Instructions

   npm run sync:ide
   

   Creates .github/copilot-instructions.md

3. Verify

   cat .github/copilot-instructions.md
   

Usage

Copilot reads repository instructions automatically. Use chat modes:

@workspace implement feature X following AIOX patterns

AntiGravity Setup

Recommendation Level: Good for Google Cloud integration

Configuration

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

1. Sync AntiGravity Files

   npm run sync:ide
   
2. Configure Google Cloud

   Set up Google Cloud credentials

3. Verify

   ls -la .antigravity/
   

Sync System

How Sync Works

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

Sync Commands

Sync All IDEs

npm run sync:ide

Automatic Sync

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

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

1. Export Cursor Rules

   cp -r .cursor/rules/ ./rules-backup/
   
2. Sync to Claude

   npm run sync:ide:claude
   
3. Verify Migration

   diff -r ./rules-backup/ .claude/commands/AIOX/agents/
   

From Claude Code to Codex CLI

1. Sync to Codex

   npm run sync:ide:codex
   npm run sync:skills:codex
   
2. Validate

   npm run validate:codex-sync
   npm run validate:codex-integration
   

Troubleshooting

Agent Not Appearing

# 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/

Sync Conflicts

# Preview changes
npm run sync:ide -- --dry-run

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

MCP Not Working

# Check MCP status
aiox mcp status

# Verify config
cat ~/.claude.json  # Claude Code
cat .cursor/mcp.json  # Cursor

Validation Failures

# 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

Platform Decision Tree

Best Practices

Always Validate

Run validation after syncing:

npm run validate:parity

Version Control Sync Files

Commit IDE-specific directories:

• .claude/
• .codex/
• .cursor/

Use Auto-Sync

Enable automatic syncing in sync.yaml

Test in Multiple IDEs

Ensure agents work across platforms

Related Documentation

Agent Reference

See all available agents and commands

Custom Agents

Create your own agent definitions

Squads

Organize agents into teams

ADE System

Autonomous Development Engine