# How to Configure IDE Integration Hooks for Claude Code, Codex CLI, and Gemini CLI in AIOS-Core > Easily configure IDE integration hooks for Claude Code, Codex CLI, and Gemini CLI using AIOS-Core. Streamline your AI agent development with unified sync and platform-specific YAML. - Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core) - Tags: how-to-guide - Published: 2026-02-16 --- **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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/docs/ide-integration.md) (lines 83-102), Claude Code integration uses a YAML configuration that defines the full-stack hook system. The configuration specifies: ```yaml 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: ```bash # 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`](https://github.com/SynkraAI/aios-core/blob/main/docs/ide-integration.md) (lines 19-30). Unlike Claude's directory-based approach, Codex uses [`AGENTS.md`](https://github.com/SynkraAI/aios-core/blob/main/AGENTS.md) at the repository root as the central configuration source: ```yaml 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-) - 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: ```bash # 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-` 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`](https://github.com/SynkraAI/aios-core/blob/main/docs/ide-integration.md) (lines 71-88). The configuration specifies text-based rule files and native hook support: ```yaml 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: ```bash # 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`](https://github.com/SynkraAI/aios-core/blob/main/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: ```bash # ------------------------------------------------- # 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`](https://github.com/SynkraAI/aios-core/blob/main/.claude/CLAUDE.md) and `.claude/commands/AIOS/agents/` with slash command activation and pre/post hooks. - **Codex CLI** relies on [`AGENTS.md`](https://github.com/SynkraAI/aios-core/blob/main/AGENTS.md) at the repository root and `.codex/agents/`, activated via `/skills` with the `aios-` prefix. - **Gemini CLI** stores configurations in [`.gemini/rules.md`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/settings.json) file and execute before and after each agent action, providing native event handling within the Google AI ecosystem.