Integração com IDEs

Compatibilidade com Claude Code, Cursor, Gemini e mais

9 min de leitura
ideintegração

IDE Integration Guide

EN

Guide for integrating AIOX with supported IDEs and AI development platforms.

Version: 4.2.11 Last Updated: 2026-02-16

Compatibility Contract (AIOX 4.2.11)

The IDE matrix is enforced by a versioned contract:

  • Contract file: .aiox-core/infrastructure/contracts/compatibility/aiox-4.2.11.yaml
  • Validator: npm run validate:parity

If matrix claims in this document diverge from validator results, parity validation fails.

Supported IDEs

AIOX supports multiple AI-powered development platforms. Choose the one that best fits your workflow.

Quick Status Matrix (AIOX 4.2.11)

| IDE/CLI | Overall Status | How to Activate an Agent | Auto-Checks Before/After Actions | Workaround if Limited | | --- | --- | --- | --- | --- | | Claude Code | Works | /agent-name commands | Works (full) | -- | | Gemini CLI | Works | /aiox-menu then /aiox-<agent> | Works (minor differences in event handling) | -- | | Codex CLI | Limited | /skills then aiox-<agent-id> | Limited (some checks need manual sync) | Run npm run sync:ide:codex and follow /skills flow | | Cursor | Limited | @agent + synced rules | Not available | Follow synced rules and run validators manually (npm run validate:parity) | | GitHub Copilot | Limited | chat modes + repo instructions | Not available | Use repo instructions and VS Code MCP config for context | | AntiGravity | Limited | workflow-driven activation | Not available | Use generated workflows and run validators manually |

Legend:

  • Works: fully recommended for new users in AIOX 4.2.11.
  • Limited: usable with the documented workaround.
  • Not available: this IDE does not offer this capability; use the workaround instead.

What You Lose Without Full Auto-Checks

Some IDEs run automatic checks before and after each action (e.g., validating context, enforcing rules). Where this is not available, you compensate manually:

| IDE | Auto-Check Level | What Is Reduced | How to Compensate | | --- | --- | --- | --- | | Claude Code | Full | Nothing | Built-in checks handle everything | | Gemini CLI | High | Minor timing differences in checks | Gemini native checks cover most scenarios | | Codex CLI | Partial | Less automatic session tracking; some pre/post-action checks need manual trigger | Use AGENTS.md + /skills + sync/validation scripts | | Cursor | None | No automatic pre/post-action checks; no automatic audit trail | Follow synced rules, use MCP for context, run validators | | GitHub Copilot | None | Same as Cursor, plus more reliance on manual workflow | Use repo instructions, chat modes, VS Code MCP | | AntiGravity | None | No automatic check equivalents | Use generated workflows and run validators |

Beginner Decision Guide

If your goal is to get started as fast as possible:

  1. Best option: Use Claude Code or Gemini CLI -- they have the most automation and fewest manual steps.
  2. Good option: Use Codex CLI if you prefer a terminal-first workflow and can follow the /skills activation flow.
  3. Usable with extra steps: Use Cursor, Copilot, or AntiGravity -- they work but require more manual validation steps (see workarounds in the table above).

Practical Consequences by Capability

  • Session tracking (automatic start/end detection):
    • Automatic on Claude Code and Gemini CLI.
    • Manual or partial on Codex, Cursor, Copilot, and AntiGravity.
  • Pre/post-action guardrails (checks that run before and after each tool use):
    • Full on Claude Code and Gemini CLI.
    • Partial on Codex CLI (run sync scripts to compensate).
    • Not available on Cursor, Copilot, and AntiGravity (run validators manually).
  • Automatic audit trail (record of what happened in each session):
    • Richest on Claude Code and Gemini CLI.
    • Reduced on other IDEs (compensate with manual logging or validator output).

Setup Instructions

Claude Code

Recommendation Level: Best AIOX integration

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

Setup:

  1. AIOX automatically creates .claude/ directory on init
  2. Agents are available as slash commands: /dev, /qa, /architect
  3. Configure MCP servers in ~/.claude.json

Configuration:

# Sync all enabled IDE targets (including Claude)
npm run sync:ide

# Verify setup
ls -la .claude/commands/AIOX/agents/

Codex CLI

Recommendation Level: Best (terminal-first workflow)

config_file: AGENTS.md
agent_folder: .codex/agents
activation: terminal instructions
skills_folder: .codex/skills (source), ~/.codex/skills (Codex menu)
format: markdown
mcp_support: native via Codex tooling
special_features:
  - AGENTS.md project instructions
  - /skills activators (aiox-<agent-id>)
  - Strong CLI workflow support
  - Easy integration with repository scripts
  - Notify command plus emerging tool hooks in recent Codex releases

Setup:

  1. Keep AGENTS.md at repository root
  2. Run npm run sync:ide:codex to sync auxiliary agent files
  3. Run npm run sync:skills:codex to generate project-local skills in .codex/skills
  4. Use /skills and choose aiox-architect, aiox-dev, etc.
  5. Use npm run sync:skills:codex:global only when you explicitly want global installation

Configuration:

# Sync Codex support files
npm run sync:ide:codex
npm run sync:skills:codex
npm run validate:codex-sync
npm run validate:codex-integration
npm run validate:codex-skills

# Verify setup
ls -la AGENTS.md .codex/agents/ .codex/skills/

Cursor

Recommendation Level: Best (popular AI IDE)

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 and cloud handoff support (latest Cursor releases)
  - Long-running agent workflows (research preview)

Setup:

  1. AIOX creates .cursor/ directory on init
  2. Agents activated with @mention: @dev, @qa
  3. Rules synchronized to .cursor/rules/

Configuration:

# Sync Cursor only
npm run sync:ide:cursor

# Verify setup
ls -la .cursor/rules/

MCP Configuration (.cursor/mcp.json):

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

GitHub Copilot

Recommendation Level: Good (GitHub integration)

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
  - Works with repo instructions and VS Code MCP config

Setup:

  1. Enable GitHub Copilot in your repository
  2. AIOX creates .github/copilot-instructions.md
  3. Agent instructions synchronized

Configuration:

# Sync all enabled IDE targets
npm run sync:ide

# Verify setup
cat .github/copilot-instructions.md

AntiGravity

Recommendation Level: Good (Google integration)

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

Setup:

  1. AIOX creates .antigravity/ directory
  2. Configure Google Cloud credentials
  3. Agents synchronized as workflows

Gemini CLI

Recommendation Level: Good

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 and hook commands
  - Native MCP server support
  - Rapidly evolving command/tooling UX

Setup:

  1. Run installer flow selecting gemini in IDE selection (wizard path)
  2. AIOX creates:
    • .gemini/rules.md
    • .gemini/rules/AIOX/agents/*.md
    • .gemini/commands/*.toml (/aiox-menu, /aiox-<agent>)
    • .gemini/hooks/*.js
    • .gemini/settings.json (hooks enabled)
  3. Validate integration:
npm run sync:ide:gemini
npm run validate:gemini-sync
npm run validate:gemini-integration
  1. Quick agent activation (recommended):
    • /aiox-menu to list shortcuts
    • /aiox-dev, /aiox-architect, /aiox-qa, etc.
    • /aiox-agent <agent-id> for generic launcher

Sync System

How Sync Works

AIOX maintains a single source of truth for agent definitions and synchronizes them to all configured IDEs:

┌─────────────────────────────────────────────────────┐
│                    AIOX Core                         │
│  .aiox-core/development/agents/  (Source of Truth)  │
│                        │                             │
│            ┌───────────┼───────────┐                │
│            ▼           ▼           ▼                │
│  .claude/     .codex/      .cursor/                  │
│  .antigravity/ .gemini/                              │
└─────────────────────────────────────────────────────┘

Sync Commands

# Sync all IDE targets
npm run sync:ide

# Sync only Gemini
npm run sync:ide:gemini
npm run sync:ide:github-copilot
npm run sync:ide:antigravity

# Validate sync
npm run sync:ide:check

Automatic Sync

AIOX can be configured to automatically sync on agent changes:

# .aiox-core/core/config/sync.yaml
auto_sync:
  enabled: true
  watch_paths:
    - .aiox-core/development/agents/
  platforms:
    - claude
    - codex
    - github-copilot
    - cursor
    - gemini
    - antigravity

Troubleshooting

Agent Not Appearing in IDE

# Verify agent exists in source
ls .aiox-core/development/agents/

# Sync and validate
npm run sync:ide
npm run sync:ide:check

# Check platform-specific directory
ls .cursor/rules/agents/               # Cursor
ls .claude/commands/AIOX/agents/       # Claude Code
ls .gemini/rules/AIOX/agents/          # Gemini CLI

Sync Conflicts

# Preview what would change
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 MCP configuration for IDE
cat ~/.claude.json  # For Claude Code
cat .cursor/mcp.json  # For Cursor

IDE-Specific Issues

Claude Code:

  • Ensure .claude/ is in project root
  • Check hooks permissions: chmod +x .claude/hooks/*.py

Cursor:

  • Restart Cursor after sync
  • Check .cursor/rules/ permissions

Platform Decision Guide

Use this guide to choose the right platform:

Do you use Claude/Anthropic API?
├── Yes --> Claude Code (Best AIOX integration)
└── No
    └── Do you prefer VS Code?
        ├── Yes --> Want an extension?
        │   ├── Yes --> GitHub Copilot (Native GitHub features)
        │   └── No --> GitHub Copilot (Native GitHub features)
        └── No --> Want a dedicated AI IDE?
            ├── Yes --> Which model do you prefer?
            │   ├── Claude/GPT --> Cursor (Most popular AI IDE)
            └── No --> Use Google Cloud?
                ├── Yes --> AntiGravity (Google integration)
                └── No --> Gemini CLI (Specialized)

Migration Between IDEs

From Cursor to Claude Code

# Export current rules
cp -r .cursor/rules/ ./rules-backup/

# Initialize Claude Code
npm run sync:ide

# Verify migration
diff -r ./rules-backup/ .claude/commands/AIOX/agents/

From Claude Code to Cursor

# Sync to Cursor
npm run sync:ide:cursor

# Configure MCP (if needed)
# Copy MCP config to .cursor/mcp.json

Related Documentation

Synkra AIOX IDE Integration Guide v4.2.11

Falar com o Time