How to Configure IDE Integration Hooks for Claude Code, Codex CLI, and Gemini CLI in AIOS-Core

AIOS-Core provides a unified sync system that propagates agent definitions and hook configurations from .aios-core/development/agents/ to Claude Code, Codex CLI, and Gemini CLI through platform-specific YAML configurations and npm validation scripts.

To configure IDE integration hooks in AIOS-Core, you leverage the repository's centralized architecture where agent definitions live in a single source of truth. The system automatically generates platform-specific configuration files, syncs them to IDE-specific directories, and validates compatibility against versioned contracts.

Understanding the AIOS-Core IDE Sync Architecture

The integration process follows a consistent three-step pattern across all supported platforms. First, AIOS-Core creates platform-specific configuration files (YAML or JSON) that describe agent locations, activation methods, and special features like hooks or MCP support. Second, you run the sync command that copies agents, hook scripts, and settings into the IDE's directory structure (.claude/, .codex/, .gemini/). Third, you validate the sync using provided validator scripts to ensure generated files match the compatibility contract at .aios-core/infrastructure/contracts/compatibility/aios-4.2.11.yaml.

Configuring Claude Code Integration Hooks

Configuration Structure

According to the source code in docs/ide-integration.md (lines 83-102), Claude Code integration uses a YAML configuration that defines the full-stack hook system. The configuration specifies:

config_file: .claude/CLAUDE.md
agent_folder: .claude/commands/AIOS/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

Sync and Validation Commands

After project initialization, AIOS-Core automatically creates the .claude/ directory. Execute the following commands as documented in lines 107-115:

# Sync all enabled IDE targets (including Claude)

npm run sync:ide

# Verify that the agents were generated

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

# Validate contract compliance

npm run validate:parity

Hook System Features

Claude Code integration supports pre-hooks and post-hooks that execute before and after agent actions. The system leverages Claude's native Task tool for subagent orchestration and MCP (Model Context Protocol) integration for extended capabilities.

Setting Up Codex CLI Integration

Configuration Files

The Codex-specific configuration appears in docs/ide-integration.md (lines 19-30). Unlike Claude's directory-based approach, Codex uses AGENTS.md at the repository root as the central configuration source:

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 (aios-<agent-id>)
  - Strong CLI workflow support
  - Easy integration with repository scripts
  - Notify command plus emerging tool hooks in recent Codex releases

Sync Workflow

Codex CLI requires a two-phase sync process followed by comprehensive validation. As documented in lines 38-45:

# 1️⃣ Keep AGENTS.md at the repo root

# 2️⃣ Generate Codex-specific files

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

# 3️⃣ Validate the generated artifacts

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

# 4️⃣ Verify the layout

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

Activation Methods

Once synced, activate agents through the Codex skill menu using /skills followed by the aios-<agent-id> prefix (for example, aios-architect or aios-dev). The system supports terminal-based instructions and integrates with repository scripts for enhanced CLI workflows.

Integrating Gemini CLI Hooks

Rule-Based Configuration

Gemini CLI integration uses a rule-based approach defined in docs/ide-integration.md (lines 71-88). The configuration specifies text-based rule files and native hook support:

config_file: .gemini/rules.md
agent_folder: .gemini/rules/AIOS/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

Sync and Validation

After selecting gemini in the installer wizard, AIOS-Core creates the necessary directory structure. The recommended workflow (lines 100-105) includes:

# Sync Gemini-specific artifacts

npm run sync:ide:gemini

# Verify that the hooks and commands are present

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

# Quick launch commands:

#   /aios-menu   – list all shortcuts

#   /aios-dev    – start the dev agent

#   /aios-architect – start the architect agent

JavaScript Hook Scripts

Gemini CLI stores hook scripts as JavaScript files under .gemini/hooks/*.js. These hooks are automatically enabled by the generated settings.json (as referenced in line 95) and execute before and after each agent action, providing native event handling within the Google AI ecosystem.

Complete Integration Examples

Execute the following commands to configure all three IDE integrations simultaneously:

# -------------------------------------------------

# 1️⃣ Claude Code – full integration

npm run sync:ide                 # copies agents to .claude/

npm run validate:parity          # checks contract compliance

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

# -------------------------------------------------

# 2️⃣ Codex CLI – terminal-first workflow

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
ls -la AGENTS.md .codex/agents/ .codex/skills/

# -------------------------------------------------

# 3️⃣ Gemini CLI – Google-native CLI

npm run sync:ide:gemini
npm run validate:gemini-sync
npm run validate:gemini-integration
ls -la .gemini/rules/AIOS/agents/ .gemini/hooks/

Summary

• AIOS-Core maintains a single source of truth for agent definitions at .aios-core/development/agents/ and syncs them to IDE-specific directories.
• Claude Code uses .claude/CLAUDE.md and .claude/commands/AIOS/agents/ with slash command activation and pre/post hooks.
• Codex CLI relies on AGENTS.md at the repository root and .codex/agents/, activated via /skills with the aios-<agent-id> prefix.
• Gemini CLI stores configurations in .gemini/rules.md and .gemini/rules/AIOS/agents/, using JavaScript hook scripts in .gemini/hooks/*.js.
• Always run the specific npm run validate:* commands after syncing to ensure compliance with .aios-core/infrastructure/contracts/compatibility/aios-4.2.11.yaml.

Frequently Asked Questions

What is the single source of truth for agent configurations in AIOS-Core?

AIOS-Core stores all agent definitions and hook configurations in .aios-core/development/agents/. This directory serves as the centralized repository that the sync system reads from when generating IDE-specific configuration files for Claude Code, Codex CLI, and Gemini CLI.

How do I validate that my IDE integration hooks are correctly configured?

After running the sync commands, execute the platform-specific validation scripts: npm run validate:parity for Claude Code, npm run validate:codex-sync and npm run validate:codex-integration for Codex CLI, and npm run validate:gemini-sync for Gemini CLI. These validators check generated files against the compatibility contract at .aios-core/infrastructure/contracts/compatibility/aios-4.2.11.yaml.

Can I use multiple IDE integrations simultaneously in the same project?

Yes, AIOS-Core supports concurrent IDE integrations. You can run npm run sync:ide to sync all enabled targets at once, or use specific commands like npm run sync:ide:codex and npm run sync:ide:gemini individually. Each IDE maintains its own directory structure (.claude/, .codex/, .gemini/) without conflicts.

Where are the hook scripts stored for Gemini CLI integration?

Gemini CLI hook scripts are stored as JavaScript files in .gemini/hooks/*.js. These scripts are automatically enabled by the generated settings.json file and execute before and after each agent action, providing native event handling within the Google AI ecosystem.

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