# uneven-ai

> Autonomous local development agent for Node.js. Runs on your machine with no telemetry and no cloud lock-in. Indexes your codebase, watches running terminals, auto-fixes errors, audits security, runs an AI data analyst with shareable reports, performs scoped security testing, and features a conversational shell — all configured via a single TypeScript object.

## Core Capabilities

- Conversational shell — run `uneven-ai` with no arguments; type in any language and Uneven routes your intent to the right command (free tier)
- Embedded local LLM (LLaMA 3.2 1B) — fully offline, no API key required; GPU auto-detected and optimised on first run (NVIDIA CUDA, Apple Metal)
- External brain providers: OpenAI, Anthropic Claude, Google Gemini, Ollama — bring your own key, no Pro upgrade required
- Knowledge base from local files (code, MD, PDF, DOCX, XLSX), databases (PostgreSQL, MySQL, SQLite, MongoDB) and external URLs
- Semantic search over indexed codebase for context-grounded answers and fixes
- Real-time terminal watcher — reads stdout/stderr of any running process
- Autonomous error detection and fix: TypeScript, JavaScript, Python, Rust, Go, Java, PHP, Ruby, COBOL, Assembly
- Surgical corrections applied as minimal diffs with snapshot/rollback support
- New in v1.0.8: `explain <file>` (plain-language file explanation), `docs <file>` (Markdown documentation generator), `review` (AI code review — Pro), `askf` (AI writes/edits files — Pro)
- Structured activity log with diffs, timestamps and findings — stored locally, never transmitted
- Malware scanner: reverse shells, obfuscation, crypto mining, supply chain attacks, typosquatting, credential theft, persistence mechanisms
- Data analyst: natural language → SQL → Excel export → HTML dashboard
- 3-layer data security: schema filter, SQL audit, result masking — sensitive data never reaches the LLM
- Pentester mode: OWASP static analysis + active testing with signed authorization scope
- CI/CD command: headless typecheck → scan → test pipeline with GitHub Actions integration
- Security report generator: HTML + Markdown output
- License system: free / Pro / Team tiers with per-machine activation and offline grace period
- BSL 1.1 license: free for personal use, paid license for commercial use (Pro R$49/mo, Team R$479/mo)

## Installation

```bash
npm install uneven-ai
```

Or globally:

```bash
npm install -g uneven-ai
uneven-ai init
```

## Quick Start

```typescript
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/log.md' },
})

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

## Configuration Object

```typescript
interface UnevenConfig {
  brain: BrainConfig           // LLM configuration
  knowledge?: KnowledgeConfig  // Knowledge sources to index
  watch?: WatchConfig          // Terminal watching + auto fix
  pentester?: PentesterConfig  // Security analysis
  log?: LogConfig              // Logging settings
}
```

## CLI Commands

```
uneven-ai                        — open conversational shell (free)
uneven-ai init                   — initialize project, download LLM, auto-detect GPU
uneven-ai start                  — start the full agent
uneven-ai watch                  — start terminal watcher
uneven-ai index                  — index all knowledge sources
uneven-ai ask "query"            — query the knowledge base (unlimited, all plans)
uneven-ai explain <file>         — explain a file in plain language (free)
uneven-ai docs <file>            — generate Markdown documentation for a file (free)
uneven-ai askf "task"            — AI writes or edits files for the described task (Pro)
uneven-ai review                 — AI code review of latest commit (Pro)
uneven-ai scan                   — scan for malware and compromised deps
uneven-ai analyze --db <url>     — AI data analyst REPL (Pro)
uneven-ai pentest                — run security analysis (active mode: Pro)
uneven-ai ci                     — headless CI pipeline (Pro)
uneven-ai remote-shell           — start local HTTP/HTTPS server for bots and external tools
uneven-ai license activate <key> — activate Pro license key
uneven-ai license status         — show license tier and expiry
uneven-ai license deactivate     — remove this machine from seat count
uneven-ai log                    — display current log
uneven-ai reset                  — clear knowledge base and re-index
```

## Free vs Pro

| Feature | Free | Pro |
|---|:---:|:---:|
| Conversational shell | ✅ | ✅ |
| Local offline LLM | ✅ | ✅ |
| API providers (own key) | ✅ | ✅ |
| ask — unlimited queries | ✅ | ✅ |
| explain, docs | ✅ | ✅ |
| index, scan, log, watch | ✅ | ✅ |
| Terminal auto-fix | — | ✅ |
| askf — AI file writing | — | ✅ |
| review — AI code review | — | ✅ |
| Active pentest | — | ✅ |
| Data analyst (analyze) | — | ✅ |
| CI/CD pipeline (ci) | — | ✅ |

## Events

```typescript
ai.on('error-detected', handler)    // Error found in terminal
ai.on('fix-applied', handler)       // Automatic fix was applied
ai.on('pentest-finding', handler)   // Security issue found
ai.on('indexed', handler)           // Indexing completed
```

## Knowledge Sources

- **Local files and directories**: dirs[], files[]
- **Databases**: db.url (PostgreSQL, MySQL, SQLite, MongoDB)
- **External URLs and documentation**: urls[]
- **External project as context**: externalProject

Supported file types: `.ts .tsx .js .jsx .py .go .java .cpp .c .rb .php .md .txt .json .yaml .toml .pdf .docx .xlsx .csv`

## Brain Providers

| Provider | Model | Requires |
|---|---|---|
| local | llama3.2 | nothing — fully offline |
| openai | gpt-4, gpt-4o | API key |
| claude | sonnet, opus | API key |
| gemini | pro, flash | API key |
| ollama | any local model | Ollama installed locally |

## Malware Scanner

```
uneven-ai scan [--report] [--json]
```

Categories detected: remote-shell, data-exfiltration, obfuscation, supply-chain, credential-theft, persistence, crypto-mining, typosquatting.
Risk levels: none | low | medium | high | critical.
Exit code 1 on critical/high findings (CI-compatible).

## Data Analyst

```
uneven-ai analyze --db <database-url> [--package-exe]
```

Interactive REPL: natural language → generated SQL → human approval → execute → Excel/dashboard export.
Security: 3-layer defense (schema filter → SQL audit → result masking). Sensitive data never reaches the LLM or output.
--package-exe: bundles HTML dashboard as a self-contained offline executable.

## Pentester Mode

### Static (mode: 'static')
Source code analysis — no network calls:
- OWASP Top 10 patterns
- Hardcoded secrets (API keys, tokens, passwords)
- Vulnerable dependencies
- Injection vulnerabilities (SQL, XSS, path traversal)
- Insecure HTTP headers

### Active (mode: 'active')
Real attack simulation — requires declared authorization scope:
- Scope declaration with integrity hash and explicit confirmation
- Target validation — public IPs blocked without explicit scope
- DoS tools blocked at command level
- Brute force, port scan, SQL injection, XSS, IDOR, CORS, SSL/TLS

**WARNING**: Active mode requires explicit authorization. Use only on systems you own or have written permission to test.

## CI/CD Pipeline

```
uneven-ai ci [--skip-security] [--skip-tests] [--strict-security] [--github]
```

Steps: TypeScript typecheck → malware scan → test suite.
Exit code 0 = pass, 1 = fail. GitHub Actions step summary via $GITHUB_STEP_SUMMARY.

## Remote Shell

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. Same classify + execute pipeline as the interactive shell.

### Config

```typescript
remoteShell: {
  port:   4242,
  secret: 'your-token',   // optional — sent as Authorization: Bearer <secret>
  https: {                // optional — omit for plain HTTP
    cert: './certs/cert.pem',
    key:  './certs/key.pem',
  }
}
```

### Endpoints

```
POST /message    { "text": "index my project" }
GET  /health     → { "status": "ok", "version": "..." }
```

Optional headers:
- `Authorization: Bearer <secret>` — required when secret is configured
- `x-session-id: <channel-id>` — keeps conversation history per caller (e.g. one Discord channel)

### Response

```json
{ "action": "index", "message": "Indexing complete.", "output": "...", "status": "ok" }
```

`status`: `"ok"` | `"error"` | `"async"` (watch and askf fire detached and return immediately)

### Usage

```
uneven-ai remote-shell    — standalone server mode
uneven-ai start           — server auto-starts when remoteShell is configured
```

## Session State Protocol

Uneven AI writes a machine-readable session snapshot at `.uneven/session.json` on every `uneven-ai start`.
Key fields: mode, autoFix, knowledge.staleness, writeLock.active, pendingDiffs.

## Write Lock Protocol

Prevents race conditions between external LLM agent writes and Uneven AI's auto-fix engine.
When writing files: check writeLock.active, acquire lock with UUID, write, release in finally block.
Lock auto-releases after timeoutMs (default: 30s).

## LLM Agent Division of Labor

| Responsibility | Owner |
|---|---|
| New code, features, logic | LLM agent |
| Runtime and compile-time error detection | Uneven AI |
| Surgical corrections to existing files | Uneven AI |
| Security analysis and vulnerability patching | Uneven AI |
| Diff approval | User |

## Links

- **npm**: https://www.npmjs.com/package/uneven-ai
- **Documentation**: https://uneven-ai.com/docs
- **Support**: contato@rileysolucoes.com.br