// Getting Started

Quick Start

Get Uneven AI running in 3 steps. No cloud, no API keys required.

Requirements

RAM4GB minimum · 8GB+ recommended
Disk~2GB for the default LLM model
OSLinux · macOS · Windows 11 (Native)

Step 1 — Install

Install Uneven AI globally using our automated network bootstrap or standard package manager.

terminal
# Linux / macOS
curl -fsSL https://uneven.dev/install.sh | bash

# Windows (PowerShell)
irm https://uneven.dev/install.ps1 | iex

Step 2 — Initialize

Run uneven init in your project root. This will:

  • Create uneven.config.ts with sensible defaults
  • Create the .uneven/ directory for logs and cache
  • Download the default LLM model (~1.5GB, one time only)
  • Update .gitignore to exclude models and vectors
terminal
uneven init
→Before starting, open uneven.config.ts and set knowledge.dirs to the folders you want Uneven to understand. This is how it knows your project. Not sure how? See the Learn guide.

Step 3 — Start & Interact

Now that your project is initialized, choose the workflow that fits your style best:

Option A — The Conversational Shell

Prefer a friendly interactive environment over typing strict CLI flags? Simply run the base command without any subcommands to enter the Conversational Control Room:

terminal
uneven

Inside this shell, you can ask direct questions about your codebase, or trigger project tasks using natural language prompts (e.g. "watch my app", "create src/routes/user.ts", or "explain this file").

Option B — Terminal Dev Watcher

Start the automated background dev process watcher directly to catch dev server and compiler errors in real time:

terminal
uneven watch

Or specify dev command parameters directly to override config settings:

terminal
uneven watch npm run dev
uneven watch cargo run
uneven watch python app.py

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 high-performance async runtime
  • Detects errors with file, line and column precision across multiple supported languages
  • Applies surgical fixes via Retrieval-Augmented Fix (RAF) — KB semantic search before pattern matching
  • Writes every event to .uneven/log.md with diffs and recommendations
  • Saves a machine-readable session snapshot to .uneven/session.json

Other useful commands

terminal
# scan for malware and compromised deps
uneven scan

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

# headless CI pipeline
uneven ci --github

# query your codebase
uneven ask "how does the auth service work?"
Learn →