Learn — Practical Guide

The key concept

Uneven AI is project-aware. Before it can help, it reads your codebase and builds a local understanding of what's there. You control that with two things:

• knowledge.dirs in uneven.config.ts — the folders you want Uneven to read
• uneven-ai start — starts the agent, which indexes those folders first

Think of it like onboarding a new developer: you walk them through the codebase once, and after that, they know their way around.

Setting up your first project

Step 1 — Run init

In the root of your project, run:

npx uneven-ai init

This creates uneven.config.ts, sets up the .uneven/ directory, and downloads the local model if you chose a local brain. The wizard will ask which brain (LLM provider) you want to use.

Step 2 — Point it at your project

Open uneven.config.ts and set knowledge.dirs to the folders that contain your code. This is the step most users miss.

import { UnevenConfig } from 'uneven-ai'

const config: UnevenConfig = {
  brain: {
    provider: 'local',
    model: 'llama3.2',
  },
  knowledge: {
    dirs: ['./src'],  // ← point this at your project
  },
  watch: {
    terminal: 'npm run dev',
  },
}

export default config

Step 3 — Start

Run the agent. It will index your configured directories and start watching your terminal:

npx uneven-ai start

That's it. Uneven now knows your codebase and is ready to watch, fix, and assist.

Switching to a different project

Finished working on Project A and moving to Project B? Uneven has no global memory — each project is its own context. The workflow is always the same:

Indexing multiple directories

knowledge.dirs accepts multiple paths. If your project spans several folders — a monorepo, shared libraries, or separate packages — list them all:

knowledge: {
  dirs: ['./src', './packages/shared', './libs/core'],
}

All directories are indexed as a single unified context.

What gets indexed

Uneven reads source files, configs, and docs inside the configured directories automatically.

Need to include external URLs, databases, or specific files outside your dirs? See the Configuration reference for all available knowledge options.

Watching your terminal

Once Uneven knows your project, it can watch any command you run — a dev server, a compiler, a test suite — and react to errors in real time.

Set watch.terminal in uneven.config.ts to the command you normally run to start your project:

watch: {
  terminal: 'npm run dev',  // whatever you normally type
  autoFix: false,          // change to true to apply fixes automatically
}

Then run npx uneven-ai start — Uneven launches your command and reads its output. When an error appears, it identifies what went wrong, finds the relevant code, and either fixes it or tells you exactly what to do.

Scanning your project

The scan command checks your entire codebase for security problems — without connecting to any network. Run it any time, no extra configuration needed:

npx uneven-ai scan

Uneven will look for:

• Hardcoded secrets — API keys, passwords, tokens left in the code
• Vulnerable dependencies — packages with known security issues
• Dangerous code patterns — remote shells, obfuscation, credential theft
• OWASP issues — injections, insecure headers, and other common flaws

Each finding includes a severity level and exactly where in your code the problem is. Add --report to export a full HTML report:

# export a full HTML security report
npx uneven-ai scan --report

Analyzing your data

The analyze command lets you ask questions about your data in plain language — no SQL knowledge required. Connect it to a database or point it at local files, then just ask.

With a database

npx uneven-ai analyze --db postgresql://user:pass@localhost/mydb

Once connected, you get an interactive prompt. Just type what you want to know:

you →  How many new users signed up last week?
you →  Show me the top 10 products by revenue this month
you →  Which customers haven't placed an order in 90 days?

Uneven translates your question into a query, shows it to you for approval, runs it, and displays the results. You can export everything to Excel or an HTML dashboard at any point.

With local files

Have a CSV or spreadsheet on your machine? No database needed — just pass the file directly:

npx uneven-ai analyze --db ./data/sales-2026.csv

Protecting sensitive columns

Have columns you never want the AI to see — passwords, salaries, personal IDs? Add them to security.mask in your config. Uneven will replace those values with ***REDACTED*** before any AI processing:

security: {
  mask:  ['password', 'ssn', 'salary', 'credit_card'], // redacted in results
  block: ['secrets', 'api_keys'],                      // entire table hidden from AI
}

Matching is case-insensitive — 'salary' also covers Monthly_Salary, SALARY_USD, and similar column names.