Quick Start

Requirements

Step 1 — Install

Install Uneven AI as a dev dependency or globally. The Rust core compiles automatically via napi-rs on first install.

# as a dev dependency
npm install uneven-ai

# or globally
npm install -g uneven-ai

Step 2 — Initialize

Run uneven-ai init in your project root. This will:

• Create uneven-ai.config.ts with sensible defaults
• Create the .uneven-ai/ directory for logs and cache
• Download the default LLM model (~1.5GB, one time only)
• Update .gitignore to exclude models and vectors

npx uneven-ai init

Step 3 — Start

Start the full agent. Uneven AI will index your knowledge base, spawn alongside your dev process and start watching.

npx uneven-ai start

Or watch a specific command directly:

uneven-ai watch --cmd "npm run dev"
uneven-ai watch --cmd "cargo run"
uneven-ai watch --cmd "python app.py"

Minimal Programmatic Setup

Use Uneven AI directly in your code without the CLI:

import { Uneven } from 'uneven-ai'

const ai = new Uneven({
  brain: { provider: 'local', model: 'llama3.2' },
  knowledge: { dirs: ['./src'], db: { url: process.env.DATABASE_URL } },
  watch: { terminal: 'npm run dev', autoFix: true },
  pentester: { enabled: true, mode: 'static' },
  log: { path: './.uneven-ai/log.md' },
})

await ai.init()
await ai.index()   // index knowledge sources
await ai.watch()   // start agent (blocks until stop())

What happens next

Once running, Uneven AI:

• Indexes all files in knowledge.dirs, databases and URLs into the local vector store
• Spawns your dev process and reads stdout/stderr in real time via Tokio async runtime
• Detects errors with file, line and column precision (TypeScript, JavaScript, Python, Rust, Go, Java, PHP, Ruby)
• Applies surgical fixes via Retrieval-Augmented Fix (RAF) — KB semantic search before pattern matching
• Writes every event to .uneven-ai/log.md with diffs and recommendations
• Saves a machine-readable session snapshot to .uneven-ai/session.json

Other useful commands

# scan for malware and compromised deps
uneven-ai scan

# AI data analyst (natural language → SQL)
uneven-ai analyze --db postgresql://localhost/mydb

# headless CI pipeline
uneven-ai ci --github

# query your codebase
uneven-ai ask "how does the auth service work?"