uneven-ai

Autonomous local development agent for Node.js.

Runs on your machine. Meets Maria, your autonomous senior engineer. She indexes your codebase, watches running terminals in real time, autonomously fixes errors, scans for malicious code, performs security testing, and manages your project via a conversational shell.

Use your own API key or run 100% offline with Maria (Standard or Pro). No telemetry. No cloud lock-in.

Features

• 💬 Maria Shell — Run uneven-ai to talk with Maria, your local senior agent. She understands your intent and dispatches commands automatically.
• 🧠 Local Sovereignty — Powered by Maria, our built-in offline brain. Choose between Maria Standard (Llama 3.2 — fast & light) or Maria Pro (Llama 4 Scout — high performance).
• ⚡ Selective Knowledge Retrieval — New Knowledge Map Strategy for massive projects. The AI identifies relevant files from a compact project map before reading content, reducing token costs by up to 90% and eliminating "context noise".
• 🔍 Semantic Knowledge Base — Scalable indexing for codebase, databases, and docs. Optimized for surgical context delivery in v1.1.1.
• 👀 Terminal Watcher — Monitors your dev workflow and catches execution errors in real time.
• 🤖 Autonomous Correction — Diagnoses errors using your project's context and applies surgical fixes.
• 🦠 Security Shield — Detects malicious patterns, supply chain attacks, and compromised dependencies.
• 📊 Intelligence Analyst — Natural-language data exploration with secure executive report exports.
• 🔐 Privacy Pentester — Scoped security assessment with strict authorization enforcement.
• 🚦 CI/CD Automation — Headless validation pipeline for production readiness.
• 📝 Forensic Logging — Detailed activity review with secure timestamps and code diffs.
• ⚡ GPU Acceleration — Automatically detects your GPU on init and installs the optimized binary. No manual steps.

Free vs Pro

| Feature | Free | Pro | |---|:---:|:---:| | Conversational shell | ✅ | ✅ | | ask — query your codebase | ✅ | ✅ | | index — index knowledge base | ✅ | ✅ | | explain — explain any file | ✅ | ✅ | | docs — generate documentation | ✅ | ✅ | | scan — malware & supply chain | ✅ | ✅ | | log / undo / info | ✅ | ✅ | | watch — terminal error watcher | ✅ | ✅ | | watch — auto-fix errors | — | ✅ | | askf — AI writes/edits files | — | ✅ | | review — AI code review | — | ✅ | | pentest — security testing | — | ✅ | | analyze — data analyst | — | ✅ | | ci — CI/CD pipeline | — | ✅ |

Free users using their own API key can chat freely in the shell — including receiving code in responses — with no interaction limits. askf (writing files to disk) requires Pro.

Requirements

Requirements vary depending on the brain provider you choose.

API providers (OpenAI, Claude, Gemini)

| Item | Minimum | Notes | |---|---|---| | Node.js | v18 (ESM required) | v20+ recommended | | RAM | 256 MB | Only embeddings model loaded (~300 MB peak) | | Disk | 200 MB | Embeddings model only | | OS | Linux, macOS, Windows 11 | |

Ollama (local via Ollama daemon)

| Item | Minimum | Notes | |---|---|---| | Node.js | v18 (ESM required) | v20+ recommended | | RAM | 512 MB (Uneven AI) | Ollama manages model memory separately | | Disk | 200 MB + model size | Ollama stores models in its own directory | | OS | Linux, macOS, Windows 11 | |

Local brain (LLaMA — no API, no cloud)

| Item | Minimum | Recommended | |---|---|---| | Node.js | v18 (ESM required) | v20+ | | RAM | 4 GB | 8 GB+ | | Disk | 200 MB (embeddings) | 2 GB+ (local LLM) | | OS | Linux, macOS, Windows 11 | Linux / macOS |

ESM package — Uneven AI uses "type": "module". Your project must use ESM (import/export) or dynamic import('uneven-ai') in CommonJS.

Installation

npm install -g uneven-ai

Or via npx:

npx uneven-ai init

Quick Start

# 1. Initialize — choose brain, download models, auto-detect GPU
uneven-ai init

# 2. Index your knowledge base
uneven-ai index

# 3. Open the conversational shell (natural language interface)
uneven-ai

# 4. Ask questions about your code
uneven-ai ask "What does the authenticateUser function do?"

# 5. Start the autonomous agent (watch + auto-fix) [Pro]
uneven-ai start

# 6. Scan for malware and supply chain attacks
uneven-ai scan

# 7. Run a code review [Pro]
uneven-ai review

# 8. Analyze data [Pro]
uneven-ai analyze --db postgresql://localhost/mydb

# 9. Run security analysis [Pro]
uneven-ai pentest

# 10. Run CI pipeline [Pro]
uneven-ai ci

Provider Setup

uneven-ai init walks you through selecting a provider and downloading required models:

• Maria (Local) — Downloads an optimized offline model. Detects GPU automatically. Choose Maria Standard (Llama 3.2) for speed or Maria Pro (Llama 4) for advanced reasoning.
• Ollama — Connects to your existing Ollama infrastructure.
• Cloud providers — Requires environment API keys:

  export ANTHROPIC_API_KEY=sk-ant-...   # Claude
  export OPENAI_API_KEY=sk-...          # OpenAI
  export GOOGLE_API_KEY=AI...           # Gemini

Conversational Shell

Run uneven-ai with no arguments to open the interactive shell:

  ◈  Uneven AI  v1.1.9
  ────────────────────────────────────────────────────────────
  Olá! O que posso fazer por você hoje?
  (Escreva sua mensagem ou "sair" para encerrar)

  ›

Type in any language. Your configured brain understands your intent and responds conversationally — then executes the right command automatically.

Examples:

› explain the auth middleware
› is there anything suspicious in my dependencies?
› what does the payment service do?
› write a unit test for the UserService class   ← needs Pro (askf)

The shell uses your configured brain (maxTokens from uneven.config.ts) so responses are never truncated. Free users can receive full code snippets in chat — the Pro gate applies only to askf (writing files to disk).

GPU Acceleration

uneven-ai init automatically detects your hardware and installs the optimal binary:

| Hardware | What happens | |---|---| | NVIDIA GPU (Linux / Windows) | CUDA-accelerated binary downloaded and installed silently | | Apple Silicon (macOS) | Metal + Accelerate already bundled in the npm package | | CPU only | Optimized CPU binary (bundled in npm) — no extra steps |

No manual compilation required. If your GPU is detected after a fresh npm install, just run uneven-ai init again.

Configuration

Create uneven.config.ts in your project root:

import { UnevenConfig } from 'uneven-ai'

const config: UnevenConfig = {
  brain: {
    provider: 'local',          // 'local' (Maria) | 'openai' | 'claude' | 'gemini' | 'ollama'
    model: 'maria-standard',    // 'maria-standard' (Llama 3.2) | 'maria-pro' (Llama 4)
    apiKey: process.env.AI_KEY, // cloud providers only
    temperature: 0.3,
    maxTokens: 2048,
    local: {
      threads: 4,
      gpuLayers: 35,            // set by init based on your VRAM
    },
  },
  knowledge: {
    dirs: ['./src', './docs'],
    files: ['./README.md'],
    db: {
      url: process.env.DATABASE_URL, // PostgreSQL, MySQL, SQLite, MongoDB
      tables: ['products', 'faq'],
    },
    urls: ['https://docs.example.com'],
  },
  watch: {
    terminal: 'npm run dev',
    autoFix: true,
    confirmBeforeFix: false,
  },
  pentester: {
    enabled: false,
    mode: 'static',             // 'static' | 'active'
    target: 'http://localhost:3000',
  },
  log: {
    path: './.uneven/log.md',
  },
}

export default config

Low-memory / API mode

const config: UnevenConfig = {
  brain: {
    provider: 'gemini',
    model: 'gemini-2.5-flash',
    apiKey: process.env.GOOGLE_API_KEY,
    maxTokens: 1024,
  },
  knowledge: {
    dirs: ['./src'],
  },
  watch: {
    terminal: 'npm run dev',
    autoFix: true,
  },
}

In API mode Uneven AI stays well under 512 MB — only the local embeddings model is loaded for semantic search.

CLI Commands

Shell & Knowledge

uneven-ai                         # Open conversational shell (natural language interface)
uneven-ai init                    # Initialize project (interactive setup + model download)
uneven-ai index                   # Index knowledge base (codebase, docs, DBs, URLs)
uneven-ai ask "query"             # Single-turn question about your codebase
uneven-ai explain <file>          # Explain a file in plain English
uneven-ai docs <file>             # Generate Markdown documentation for a file
uneven-ai log                     # View Uneven activity history
uneven-ai undo                    # Undo last applied fix
uneven-ai restore                 # Restore file from backup
uneven-ai reset                   # Clear cache and re-index
uneven-ai info                    # Show system info (GPU, version, model)

Watch & Fix

uneven-ai start                   # Start full agent (watch + auto-fix) [Pro]
uneven-ai watch "npm run dev"     # Watch terminal — log errors only (Free) / auto-fix (Pro)
uneven-ai watch "cmd1" "cmd2"     # Watch multiple processes simultaneously
uneven-ai askf "create a login endpoint"   # AI writes/edits files for the task [Pro]
uneven-ai review                  # AI code review of latest commit [Pro]
uneven-ai review --staged         # Review staged changes
uneven-ai review --from <ref>     # Review from a git ref

Malware Scanner

uneven-ai scan                  # Scan project files and dependencies
uneven-ai scan --report         # Generate HTML + Markdown report
uneven-ai scan --json           # JSON output for CI integration

Detects:

• Reverse shells — /dev/tcp, nc -e, bash -i >&
• Obfuscation — eval(atob()), Buffer.from(..., 'base64'), String.fromCharCode arrays
• Crypto mining — stratum+tcp URLs, xmrig/cryptonight references
• Supply chain attacks — network downloads in postinstall scripts
• Credential theft — SSH keys, /etc/passwd, ~/.aws/credentials access
• Persistence — crontab writes, systemd units, shell profile modification
• Typosquatting — package names within edit-distance 2 of popular packages
• Data exfiltration — credential harvesting + external network upload patterns

Data Analyst [Pro]

uneven-ai analyze --db postgresql://localhost/mydb
uneven-ai analyze --db sqlite://./data.db
uneven-ai analyze --db mongodb://localhost/mydb
uneven-ai analyze --db mysql://user:pass@localhost/mydb --package-exe

Interactive workflow:

1. Connects and introspects real schema (read-only)
2. Shows security policy (blocked columns + tables)
3. Describe what you want in plain English
4. Uneven AI generates SQL — you [A]pprove, [E]dit, or [S]kip
5. Query executes — sensitive data auto-redacted in results
6. Export to Excel and/or HTML dashboard

3-layer data protection:

| Layer | What it does | |---|---| | 1. Schema Filter | Automatically removes sensitive tables and columns from the schema before the AI analyzes it. | | 2. Semantic SQL Audit | Actively blocks suspicious queries or attempts to access unauthorized data patterns. | | 3. Live Result Redaction | Dynamically masks sensitive values (Passwords, JWTs, AWS keys) in real-time before they reach your screen. |

Pentester [Pro]

uneven-ai pentest                         # Static analysis
uneven-ai pentest --mode active           # Active testing (requires scope declaration)
uneven-ai pentest --declare-scope         # Declare authorization scope
uneven-ai pentest --report html           # Generate HTML report
uneven-ai pentest --report both           # HTML + Markdown

Active mode requires explicit authorization:

? Who authorized this test? John Doe
? Target(s): 192.168.1.0/24, dev.myapp.com
? Duration (hours): 8
? Type I AUTHORIZE to confirm: I AUTHORIZE
✓ Scope declared. Expires in 8h. Integrity-signed.

• Only in-scope IPs/hostnames can be tested
• Public internet IPs blocked unless explicitly in scope
• DoS tools, mass scans, and destructive flags blocked at the engine level

CI/CD [Pro]

uneven-ai ci                        # Full pipeline
uneven-ai ci --skip-security        # Skip malware scan step
uneven-ai ci --skip-tests           # Skip test suite step
uneven-ai ci --strict-security      # Fail on medium findings (default: high+)
uneven-ai ci --github               # Write GitHub Actions step summary
uneven-ai ci --output ./ci-out.json # Custom output path

Pipeline steps: TypeScript typecheck → malware scan → test suite. Exit code 0 = pass.

Programmatic API

import { Uneven } from 'uneven-ai'

const ai = new Uneven({
  brain: { provider: 'local', model: 'llama-3.2-1b-q8' },
  knowledge: { dirs: ['./src'] },
  watch: { terminal: 'npm run dev', autoFix: true },
})

await ai.init()
await ai.index()
await ai.watch()

ai.on('error-detected', (event) => console.log('Error:', event.data))
ai.on('fix-applied', (event) => console.log('Fixed:', event.data))
ai.on('pentest-finding', (event) => console.log('Security:', event.data))
ai.on('indexed', (event) => console.log('Indexed:', event.data))

await ai.stop()

Supported Languages

| Language | Error Parsing | Auto-Fix | |---|:---:|:---:| | TypeScript / JavaScript | ✅ | ✅ | | Python | ✅ | ✅ | | Rust | ✅ | ✅ | | Go | ✅ | ✅ | | Java | ✅ | ✅ | | PHP | ✅ | ✅ | | Ruby | ✅ | ✅ | | COBOL | ✅ | ✅ | | Assembly (x86/ARM) | ✅ | ✅ |

Knowledge Sources

| Source | Details | |---|---| | Local files | .ts .js .py .rs .go .java .php .rb .md .txt .json .yaml .toml | | Spreadsheets | Excel (.xlsx, .xls) and CSV | | Documents | PDF (.pdf) and Word (.docx) | | Databases | PostgreSQL, MySQL, SQLite, MongoDB | | URLs | Any web page or documentation site |

Brain Providers

| Provider | Config | Requires | |---|---|---| | Local (default) | provider: 'local' | Nothing — model downloads via init | | OpenAI | provider: 'openai' | OPENAI_API_KEY env var | | Anthropic Claude | provider: 'claude' | ANTHROPIC_API_KEY env var | | Google Gemini | provider: 'gemini' | GOOGLE_API_KEY env var | | Ollama | provider: 'ollama' | Ollama running locally |

Security & Privacy

Privacy is not a feature — it's the foundation.

✅ Absolute sovereignty — 100% local execution available
✅ Privacy Sanity — Development environment paths automatically stripped from distribution binaries
✅ No telemetry — zero usage tracking or analytics
✅ Forensic Audit Logs — Detailed activity history with secure timestamps and auditable code diffs
✅ 3-layer data protection — Sensitive schema and results are dynamically filtered and redacted
✅ Scope-enforced pentester — Active mode requires explicit authorization and digital scope signing
✅ Ethical safety guard — Built-in protection against generating malicious payloads or exploits
✅ GPU acceleration — Automatic, transparent, and completely private hardware utilization

Production Mode

const config: UnevenConfig = {
  watch: {
    terminal: 'node dist/server.js',
    autoFix: false,     // never auto-fix in production
    alertOnly: true,
  },
  pentester: {
    enabled: true,
    severity: 'low',
  },
}

In alertOnly mode, Uneven AI is a monitoring agent — it detects issues but never modifies code.

Log Format

All findings are written to .uneven/log.md:

## [10:32:14] Error Detected

**File:** src/services/auth.service.ts
**Line:** 42 | **Column:** 18
**Message:** TypeError: Cannot read properties of undefined

## [10:32:15] Fix Applied

**File:** src/services/auth.service.ts

**Before:**
return user.id

**After:**
return user?.id ?? null

## [10:45:00] Security Finding

**Severity:** HIGH
**Category:** obfuscation
**File:** scripts/deploy.js
**Line:** 12

eval(atob('aGVsbG8gd29ybGQ='))

Disclaimer

Uneven AI uses artificial intelligence models that may produce incorrect, incomplete, or misleading results. AI-generated outputs — including code fixes, security findings, SQL queries, and diagnoses — must be reviewed by a qualified professional before being applied to any production system.

KR Riley Soluções is not liable for:

• Damages caused by incorrect or incomplete AI-generated suggestions
• Data loss, system failures, or security incidents resulting from automated fixes
• Misuse of security testing features against systems without explicit authorization
• Any direct, indirect, incidental, or consequential damages arising from use of this software

You are solely responsible for validating AI outputs and ensuring compliance with applicable laws and regulations.

License & Ownership

Uneven AI is proprietary software. All intellectual property rights — including source code, design, and documentation — are owned exclusively by KR Riley Soluções.

Business Source License 1.1 (BSL)

✅ Free for: personal projects, learning, non-commercial use
❌ Requires license for: commercial production use
✅ Converts to Apache 2.0 on 2056-04-19

Read the full LICENSE file.

This is not an open-source project. Contributions, forks, and redistributions are subject to the terms of the BSL license above.

Testing Guide

New to Uneven AI? Follow the step-by-step guide to verify each feature works correctly:

TESTING_GUIDE.md — covers init, indexing, shell, ask, error detection, malware scanner, data analyst, pentest, CI pipeline, log review, and reset.

Support & Issues

• 🐛 Report issues
• 📧 Email support
• 💬 Discussions

© 2025 KR Riley Soluções. All rights reserved.

Uneven AI is developed and owned by KR Riley Soluções — a software engineering consultancy in Brazil.

• 🌐 uneven.dev
• 📧 [email protected]
• 🐙 GitHub

Made with ❤️ for developers who want AI that respects their privacy.