Installation Guide

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

System Requirements

Node.js

string

required

Version 18.0.0 or higher (v20+ recommended)

npm

string

required

Version 9.0.0 or higher

Git

string

Required for version control and team collaboration

GitHub CLI

string

Optional, required for team collaboration features

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.

Installation Methods

Method 1: NPX (Recommended)

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

New Project
Existing Project

Create a new project with AIOX:

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

Install AIOX in an existing project:

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

Method 2: Clone and Build

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

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

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

Claude Code (Best Integration)

Setup: Automatic - no configuration needed!Claude Code automatically loads AIOX configuration from .claude/CLAUDE.md.Verification:

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

Codex CLI (Terminal-First)

Setup: AIOX 4.2 includes first-class Codex integration.

The AGENTS.md file at project root is auto-loaded
Generate local skills (recommended for this repo):
```
npm run sync:skills:codex
```

Agent Activation:

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

Or use shortcuts:

@dev
/dev
/dev.md

Validation:

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

Cursor (Popular AI IDE)

Setup: Manual rules configuration required.

Open Cursor settings
Navigate to User Rules
Copy contents from .cursor/global-rules.md
Paste into rules section and save

Agent Activation:

@dev
@qa

Limitations:

❌ No lifecycle hooks
✅ Rules and MCP support
⚠️ Manual context management

Gemini CLI (Google AI)

Setup: Sync agents and hooks.

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:

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

Features:

✅ Native event hooks
✅ Strong automation
✅ Slash commands

AntiGravity (Google Cloud)

Setup: Workflow-based integration.

npm run sync:ide:antigravity

Note: AntiGravity uses workflows rather than lifecycle hooks. Integration is workflow-based, not hook-based.

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

For detailed impact analysis and mitigation strategies, see the IDE Integration guide.

Post-Installation

Verify Installation

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

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

🏥 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:

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

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

Regular updates ensure you have the latest features, bug fixes, and agent improvements.

Platform-Specific Notes

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:

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

Windows

Recommended Installation:

Download Node.js from 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:

node --version
npm --version

Git Bash: AIOX works with Git Bash on Windows.

Linux

Recommended Installation:

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

Ubuntu/Debian:

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.

Troubleshooting

Installation fails with EACCES error

Cause: npm permission issues.Solution: Never use sudo with npm. Fix permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Node.js version too old

Cause: System has Node.js below 18.0.0.Solution: Update Node.js:

# Using nvm (recommended)
nvm install 20
nvm use 20
nvm alias default 20

# Or download from nodejs.org

npx command not found

Cause: npm not properly installed or not in PATH.Solution:

Verify npm installation: npm --version
Reinstall Node.js if needed
Check PATH includes npm binaries

Agent files not found

Cause: Incomplete installation or sync needed.Solution:

# Reinstall
npx aiox-core install --force

# Sync IDE
npm run sync:ide

# Verify
npx aiox-core doctor

Git hooks not working

Cause: Hooks not executable or not installed.Solution:

# Reinstall hooks
npx husky install

# Make executable
chmod +x .husky/*

Next Steps

Quickstart

Get started in 10 minutes

Core Concepts

Understand AIOX architecture

Agents Overview

Meet the 11 specialized agents

CLI Reference

Master the command-line interface

Need Help?

Installation Troubleshooting

Detailed troubleshooting guide

GitHub Issues

Report bugs or request features

Get Started

Core Concepts

Agents

CLI Reference

Workflows

Advanced

Installation

Installation Guide

System Requirements

Installation Methods

Method 1: NPX (Recommended)

Method 2: Clone and Build

Method 3: Team Setup

IDE Configuration

Claude Code (Best Integration)

Codex CLI (Terminal-First)

Cursor (Popular AI IDE)

Gemini CLI (Google AI)

GitHub Copilot

AntiGravity (Google Cloud)

Hook Compatibility Matrix

Post-Installation

Verify Installation

Expected Output

Configure Sync Commands

Updating AIOX

Platform-Specific Notes

Troubleshooting

Next Steps

Quickstart

Core Concepts

Agents Overview

CLI Reference

Need Help?

Installation Troubleshooting

GitHub Issues

Get Started

Core Concepts

Agents

CLI Reference

Workflows

Advanced

Documentation Index

​Installation Guide

​System Requirements

​Installation Methods

​Method 1: NPX (Recommended)

​Method 2: Clone and Build

​Method 3: Team Setup

​IDE Configuration

​Claude Code (Best Integration)

​Codex CLI (Terminal-First)

​Cursor (Popular AI IDE)

​Gemini CLI (Google AI)

​GitHub Copilot

​AntiGravity (Google Cloud)

​Hook Compatibility Matrix

​Post-Installation

​Verify Installation

​Expected Output

​Configure Sync Commands

​Updating AIOX

​Platform-Specific Notes

​Troubleshooting

​Next Steps

Quickstart

Core Concepts

Agents Overview

CLI Reference

​Need Help?

Installation Troubleshooting

GitHub Issues

Installation Guide

System Requirements

Installation Methods

Method 1: NPX (Recommended)

Method 2: Clone and Build

Method 3: Team Setup

IDE Configuration

Claude Code (Best Integration)

Codex CLI (Terminal-First)

Cursor (Popular AI IDE)

Gemini CLI (Google AI)

GitHub Copilot

AntiGravity (Google Cloud)

Hook Compatibility Matrix

Post-Installation

Verify Installation

Expected Output

Configure Sync Commands

Updating AIOX

Platform-Specific Notes

Troubleshooting

Next Steps

Need Help?