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

# Installation

> Complete installation guide for Synkra AIOX on all platforms

# Installation Guide

This guide covers all installation methods for Synkra AIOX across different platforms and scenarios.

## System Requirements

<ParamField path="Node.js" type="string" required>
  Version 18.0.0 or higher (v20+ recommended)
</ParamField>

<ParamField path="npm" type="string" required>
  Version 9.0.0 or higher
</ParamField>

<ParamField path="Git" type="string">
  Required for version control and team collaboration
</ParamField>

<ParamField path="GitHub CLI" type="string">
  Optional, required for team collaboration features
</ParamField>

<Warning>
  **Minimum versions are enforced**. AIOX will not install on Node.js below 18.0.0 or npm below 9.0.0. Update your environment before proceeding.
</Warning>

***

## Installation Methods

### Method 1: NPX (Recommended)

The easiest way to install AIOX is using npx, which always uses the latest version:

<Tabs>
  <Tab title="New Project">
    Create a new project with AIOX:

    ```bash theme={null}
    npx aiox-core init my-project
    cd my-project
    ```

    This will:

    * Create a new directory
    * Set up project structure
    * Install AIOX framework
    * Configure agents and workflows
    * Initialize Git repository (optional)
    * Install dependencies
  </Tab>

  <Tab title="Existing Project">
    Install AIOX in an existing project:

    ```bash theme={null}
    cd your-existing-project
    npx aiox-core install
    ```

    This will:

    * Detect existing installation
    * Update AIOX framework files
    * Preserve your custom configurations
    * Create backup files (.bak) for changes
  </Tab>
</Tabs>

### Method 2: Clone and Build

For contributors or advanced users who want to modify the source:

```bash theme={null}
# Clone the repository
git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core

# Install dependencies
npm install

# Run the installer
npm run install:aiox
```

### Method 3: Team Setup

For team members joining an existing AIOX project:

```bash theme={null}
# Clone your team's repository
git clone <your-team-repo>
cd <your-project>

# Install/update AIOX
npx aiox-core@latest install

# Verify installation
npx aiox-core doctor
```

***

## IDE Configuration

AIOX supports multiple IDEs with varying levels of integration. Choose your IDE and follow the setup instructions:

<Tabs>
  <Tab title="Claude Code">
    ### Claude Code (Best Integration)

    **Setup**: Automatic - no configuration needed!

    Claude Code automatically loads AIOX configuration from `.claude/CLAUDE.md`.

    **Verification**:

    ```bash theme={null}
    npm run validate:claude-sync
    npm run validate:claude-integration
    ```

    **Agent Activation**:

    ```
    @dev
    @qa
    @architect
    ```

    **Features**:

    * ✅ Full lifecycle hooks
    * ✅ Context automation
    * ✅ Quality gates
    * ✅ Audit trails
  </Tab>

  <Tab title="Codex CLI">
    ### Codex CLI (Terminal-First)

    **Setup**: AIOX 4.2 includes first-class Codex integration.

    1. The `AGENTS.md` file at project root is auto-loaded
    2. Generate local skills (recommended for this repo):
       ```bash theme={null}
       npm run sync:skills:codex
       ```

    **Agent Activation**:

    ```
    /skills
    # Select: aiox-dev, aiox-architect, etc.
    ```

    Or use shortcuts:

    ```
    @dev
    /dev
    /dev.md
    ```

    **Validation**:

    ```bash theme={null}
    npm run validate:codex-sync
    npm run validate:codex-integration
    npm run validate:codex-skills
    ```

    **Features**:

    * ✅ Shared activation pipeline
    * ✅ Local-first skills
    * ✅ MCP integration
    * ⚠️ Partial lifecycle hooks
  </Tab>

  <Tab title="Cursor">
    ### Cursor (Popular AI IDE)

    **Setup**: Manual rules configuration required.

    1. Open Cursor settings
    2. Navigate to **User Rules**
    3. Copy contents from `.cursor/global-rules.md`
    4. Paste into rules section and save

    **Agent Activation**:

    ```
    @dev
    @qa
    ```

    **Limitations**:

    * ❌ No lifecycle hooks
    * ✅ Rules and MCP support
    * ⚠️ Manual context management
  </Tab>

  <Tab title="Gemini CLI">
    ### Gemini CLI (Google AI)

    **Setup**: Sync agents and hooks.

    ```bash theme={null}
    npm run sync:ide:gemini
    ```

    This generates:

    * `.gemini/rules.md` - Agent rules
    * `.gemini/rules/AIOX/agents/` - Agent definitions
    * `.gemini/commands/*.toml` - Slash commands
    * `.gemini/hooks/` - Local hooks

    **Agent Activation**:

    ```
    /aiox-menu
    /aiox-dev
    /aiox-architect
    ```

    **Validation**:

    ```bash theme={null}
    npm run validate:gemini-sync
    npm run validate:gemini-integration
    ```

    **Features**:

    * ✅ Native event hooks
    * ✅ Strong automation
    * ✅ Slash commands
  </Tab>

  <Tab title="GitHub Copilot">
    ### GitHub Copilot

    **Setup**: Repository instructions only.

    GitHub Copilot reads from repository-level instructions but has limited AIOX integration.

    **Limitations**:

    * ❌ No lifecycle hooks
    * ⚠️ Basic agent awareness
    * ✅ MCP support in VS Code
  </Tab>

  <Tab title="AntiGravity">
    ### AntiGravity (Google Cloud)

    **Setup**: Workflow-based integration.

    ```bash theme={null}
    npm run sync:ide:antigravity
    ```

    **Note**: AntiGravity uses workflows rather than lifecycle hooks. Integration is workflow-based, not hook-based.
  </Tab>
</Tabs>

***

## Hook Compatibility Matrix

AIOX 4.2 provides different levels of automation depending on your IDE:

| IDE/CLI            | Hook Parity          | Impact                                            |
| ------------------ | -------------------- | ------------------------------------------------- |
| **Claude Code**    | Complete (reference) | Maximum automation of context, guardrails, audit  |
| **Gemini CLI**     | High (native events) | Strong pre/post tool and session automation       |
| **Codex CLI**      | Partial/limited      | Some automation via AGENTS.md, /skills, MCP       |
| **Cursor**         | None                 | Lower automation; focus on rules and MCP          |
| **GitHub Copilot** | None                 | Minimal automation; repository instructions + MCP |
| **AntiGravity**    | Workflow-based       | Integration by workflows, not hooks               |

<Info>
  For detailed impact analysis and mitigation strategies, see the [IDE Integration guide](/advanced/ide-integration).
</Info>

***

## Post-Installation

### Verify Installation

Run the diagnostic tool to verify everything is set up correctly:

```bash theme={null}
npx aiox-core doctor
```

This checks:

* Node.js and npm versions
* AIOX framework installation
* Agent definitions (11 agents)
* Workflow files
* Template files
* Configuration files

### Expected Output

```bash theme={null}
🏥 AIOX System Diagnostics

✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ Synkra AIOX: v4.4.6

Configuration:
✔ .aiox-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found

✅ All checks passed! Your installation is healthy.
```

### Configure Sync Commands

AIOX provides npm scripts for IDE synchronization:

```bash theme={null}
# Sync all IDEs
npm run sync:ide

# Sync specific IDE
npm run sync:ide:claude
npm run sync:ide:codex
npm run sync:ide:gemini

# Validate sync
npm run sync:ide:check
npm run validate:parity
```

***

## Updating AIOX

To update an existing AIOX installation:

```bash theme={null}
npx aiox-core@latest install
```

The installer will:

* Detect your existing version
* Update framework files
* Preserve custom configurations
* Create backups of modified files (.bak)
* Migrate configuration if needed

<Tip>
  Regular updates ensure you have the latest features, bug fixes, and agent improvements.
</Tip>

***

## Platform-Specific Notes

<Accordion title="macOS">
  **Recommended Installation**:

  * Use Homebrew for Node.js: `brew install node`
  * Or use nvm: `nvm install 20`

  **Permissions**: If you encounter permission errors, do NOT use sudo. Instead:

  ```bash theme={null}
  # Fix npm permissions
  mkdir ~/.npm-global
  npm config set prefix '~/.npm-global'
  echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
  source ~/.zshrc
  ```

  **Shell**: AIOX works with bash and zsh (default on macOS).
</Accordion>

<Accordion title="Windows">
  **Recommended Installation**:

  * Download Node.js from [nodejs.org](https://nodejs.org)
  * Or use nvm-windows

  **Terminal**: Use PowerShell or Command Prompt. WSL2 with Ubuntu is also supported.

  **Path Issues**: Ensure Node.js is in your PATH. The installer should handle this, but verify with:

  ```powershell theme={null}
  node --version
  npm --version
  ```

  **Git Bash**: AIOX works with Git Bash on Windows.
</Accordion>

<Accordion title="Linux">
  **Recommended Installation**:

  * Use nvm for Node.js: `nvm install 20`
  * Or use your distribution's package manager

  **Ubuntu/Debian**:

  ```bash theme={null}
  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  sudo apt-get install -y nodejs
  ```

  **Permissions**: Follow the npm permission fix from macOS section if needed.
</Accordion>

***

## Troubleshooting

<Accordion title="Installation fails with EACCES error">
  **Cause**: npm permission issues.

  **Solution**: Never use sudo with npm. Fix permissions:

  ```bash theme={null}
  mkdir ~/.npm-global
  npm config set prefix '~/.npm-global'
  echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
  source ~/.bashrc
  ```
</Accordion>

<Accordion title="Node.js version too old">
  **Cause**: System has Node.js below 18.0.0.

  **Solution**: Update Node.js:

  ```bash theme={null}
  # Using nvm (recommended)
  nvm install 20
  nvm use 20
  nvm alias default 20

  # Or download from nodejs.org
  ```
</Accordion>

<Accordion title="npx command not found">
  **Cause**: npm not properly installed or not in PATH.

  **Solution**:

  1. Verify npm installation: `npm --version`
  2. Reinstall Node.js if needed
  3. Check PATH includes npm binaries
</Accordion>

<Accordion title="Agent files not found">
  **Cause**: Incomplete installation or sync needed.

  **Solution**:

  ```bash theme={null}
  # Reinstall
  npx aiox-core install --force

  # Sync IDE
  npm run sync:ide

  # Verify
  npx aiox-core doctor
  ```
</Accordion>

<Accordion title="Git hooks not working">
  **Cause**: Hooks not executable or not installed.

  **Solution**:

  ```bash theme={null}
  # Reinstall hooks
  npx husky install

  # Make executable
  chmod +x .husky/*
  ```
</Accordion>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started in 10 minutes
  </Card>

  <Card title="Core Concepts" icon="book" href="/concepts/architecture">
    Understand AIOX architecture
  </Card>

  <Card title="Agents Overview" icon="users" href="/agents/overview">
    Meet the 11 specialized agents
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Master the command-line interface
  </Card>
</CardGroup>

***

## Need Help?

<CardGroup cols={2}>
  <Card title="Installation Troubleshooting" icon="wrench" href="/guides/installation-troubleshooting">
    Detailed troubleshooting guide
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/SynkraAI/aiox-core/issues">
    Report bugs or request features
  </Card>
</CardGroup>