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

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

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

Existing Project

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

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

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

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

Gemini CLI

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

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

AntiGravity

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:

1. Verify npm installation: npm --version
2. Reinstall Node.js if needed
3. 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