// Reference

Configuration

Full reference for the uneven.config.ts object. All keys are optional except brain. Use projectRoot if your config file lives outside the project root — all relative paths are resolved from there.

brain

Controls which local or cloud engine powers Uneven AI. Defaults to high-performance native inference — no API key required.

schemaTypeScript
brain: {
  provider: 'local' | 'openai' | 'claude' | 'gemini' | 'ollama'
  model:        string   // e.g. 'native-core', 'gpt-4o', 'claude-3-5-sonnet'
  apiKey?:      string   // required only for external providers
  temperature?: number   // 0.0–1.0, default: 0.3
  maxTokens?:   number   // default: 2048
  local?: {              // hardware settings — local provider only
    threads?:       number // CPU threads (default: 4)
    gpuLayers?:     number // layers offloaded to GPU (default: 32)
    unloadTimeout?: number // minutes before model unloads (default: 10)
  }
}
ProviderModel examplesRequires
localnative-core, optimizedNothing — downloaded at init
openaigpt-4o, o1apiKey only (Zero SDK dependencies)
claudeclaude-3-5-sonnet, claude-3-opusapiKey only (Zero SDK dependencies)
geminigemini-2.5-flash, gemini-2.5-proapiKey only (Zero SDK dependencies)
ollamaany-local-modelOllama running locally

knowledge

→knowledge.dirs is the most important field in this config — it tells Uneven which folders to read and understand. Set it before running start. Switching to a different project? Update dirs and run start (or index) again.

Defines the sources Uneven AI indexes into its local vector store. All fields are optional.

schemaTypeScript
knowledge: {
  dirs?:            string[]  // local directories to index recursively
  files?:           string[]  // specific files to index (e.g. ['./context.md'])
  db?: {
    url:            string    // database connection URL
    allowedTables:  string[]  // allowed tables list (zero-trust whitelist)
  }
  urls?:            string[]  // external URLs to scrape
  externalProject?: string    // path to another local project
}

Supported file types

Code: .ts .tsx .js .jsx .py .go .rs .java .cpp .rb .php
Docs: .md .txt .pdf .docx
Config: .json .yaml .yml .toml

Database connection URLs

examples
# PostgreSQL
postgresql://user:pass@localhost:5432/mydb

# MySQL
mysql://user:pass@localhost:3306/mydb

# SQLite
sqlite://./database.sqlite

# MongoDB
mongodb+srv://user:[email protected]/db

watch

Controls how Uneven AI watches your terminal and reacts to errors.

schemaTypeScript
watch: {
  terminal?:         string   // command to spawn and watch (e.g. 'npm run dev')
  terminals?:        string[] // multiple commands run in parallel
  autoFix?:          boolean  // apply fixes automatically (default: false)
  confirmBeforeFix?: boolean  // ask confirmation before each fix
  alertOnly?:        boolean  // observe and alert only, no fix attempt
  ignorePatterns?:   string[] // glob patterns to skip in file watcher
  dirs?:             string[] // dirs to watch for changes
}
⚠Never set autoFix: true in production. Use alertOnly: true instead — Uneven AI will monitor and log without modifying any files.

pentester

Security analysis engine. See the Pentester Mode page for the full reference.

schemaTypeScript
pentester: {
  enabled:   boolean
  mode:      'static' | 'active'
  target?:   string   // required for active mode
  realtime?: boolean  // continuous analysis during watch
  severity?: 'low' | 'medium' | 'high' | 'critical'
  static?:   StaticAnalysisConfig
  bruteforce?: BruteforceConfig
  firewall?: FirewallConfig
  active?:   ActiveTestConfig
}

log

Controls the structured Markdown log written to .uneven/log.md.

schemaTypeScript
log: {
  path?:             string  // default: './.uneven/logs/main.md'
  append?:           boolean // false = recreate on each session
  includeTimestamp?: boolean // default: true
  includeDiff?:      boolean // include before/after diffs (default: true)
}

security

Data privacy and masking policies applied whenever Uneven queries databases, CSV or Excel files. Sensitive data never reaches the AI.

schemaTypeScript
security: {
  mask?:             string[]  // column names redacted with ***REDACTED*** (case-insensitive)
  block?:            string[]  // table names hidden entirely from the AI
  reportRedactions?: boolean   // include privacy summary in generated reports
}
exampleTypeScript
security: {
  mask:  ['password', 'ssn', 'salary', 'credit_card'], // columns → ***REDACTED***
  block: ['secrets', 'api_keys'],                      // tables hidden from AI entirely
  reportRedactions: true,
}
→mask matches column names case-insensitively. A column named User_Password is redacted by 'password'. Values in matched columns are replaced with ***REDACTED*** before any AI processing.

notifications

Send Uneven alerts to a Slack or Discord channel via an incoming webhook.

schemaTypeScript
notifications: {
  webhookUrl?:   string              // Slack or Discord incoming webhook URL
  minSeverity?:  'error' | 'warning'  // minimum severity to notify (default: 'error')
}
exampleTypeScript
notifications: {
  webhookUrl:  process.env.SLACK_WEBHOOK,
  minSeverity: 'error',
}

remoteShell

Exposes a local HTTP/HTTPS endpoint so any external tool — a Discord bot, Slack bot, or custom script — can send natural-language messages to Uneven and receive JSON responses.

schemaTypeScript
remoteShell: {
  port:    number  // local port to listen on (e.g. 4242)
  secret?: string  // bearer token authentication
  https?: {
    cert: string  // path to TLS certificate file (PEM)
    key:  string  // path to TLS private key file (PEM)
  }
}
exampleTypeScript
remoteShell: {
  port:   4242,
  secret: process.env.REMOTE_SHELL_TOKEN,
}

Once running, POST to /message with { "text": "index my project" } to send commands. Start with uneven start — the server auto-starts when remoteShell is configured.

Full development config

uneven.config.tsTypeScript
export default {
  brain: {
    provider: 'local',
    model: 'native',
    temperature: 0.3,
    local: { gpuLayers: 32, unloadTimeout: 10 },
  },
  knowledge: {
    dirs: ['./src', './docs'],
    files: ['./context.md'],
    db: { 
      url: process.env.DATABASE_URL,
      allowedTables: ['users', 'orders']
    },
    urls: ['https://docs.example.com'],
  },
  watch: {
    terminal: 'npm run dev',
    autoFix: false,
    alertOnly: false,
    dirs: ['./src'],
  },
  pentester: {
    enabled: true,
    mode: 'static',
    static: { owasp: true, secrets: true, dependencies: true },
    severity: 'medium',
  },
  security: {
    mask:  ['password', 'ssn', 'salary'],
    block: ['secrets'],
  },
  notifications: {
    webhookUrl:  process.env.SLACK_WEBHOOK,
    minSeverity: 'error',
  },
  log: {
    path: './.uneven/log.md',
    includeDiff: true,
  },
}
← LearnAPI Reference →