# timoro

> Autonomous local development agent for Node.js. Runs 100% on the user's machine with no cloud dependencies. Embeds a local LLM, indexes knowledge sources (files, databases, external URLs), watches running terminals, auto-fixes errors, scans for malware and supply chain attacks, runs an AI data analyst with shareable reports, performs scoped security testing, and runs a headless CI pipeline — all configured via a single object.

## Core Capabilities

- Embedded local LLM via Candle (LLaMA 3.2 1B Q8) — no API key required by default
- Supports external brain providers: OpenAI, Anthropic Claude, Google Gemini, Ollama
- Knowledge base from local files (code, MD, PDF, DOCX), databases (PostgreSQL, MySQL, SQLite, MongoDB) and external URLs
- Retrieval-Augmented Fix (RAF): semantic KB search grounded error fixes before pattern-match fallback
- Real-time terminal watcher — reads stdout/stderr of any running process
- Autonomous error detection and fix: TypeScript, JavaScript, Python, Rust, Go, Java, PHP, Ruby
- Auto-fix: applies surgical corrections directly to source files with snapshot/rollback
- Structured Markdown log at .timoro/log.md with diffs, timestamps and findings
- Malware scanner: reverse shells, obfuscation, crypto mining, supply chain attacks, typosquatting, credential theft, persistence mechanisms
- Data analyst: natural language → SQL → Excel export → HTML dashboard → optional portable .exe
- 3-layer data security: schema filter, SQL audit, result masking — sensitive data never reaches LLM or output
- Pentester mode: OWASP static analysis + active testing with SHA-256 signed authorization scope
- CI/CD command: headless typecheck → scan → test pipeline with GitHub Actions integration
- Security report generator: HTML + Markdown reports from findings
- Production mode: monitoring only, autoFix disabled
- TypeScript support with full type declarations
- BSL 1.1 license: free for personal use, paid license for commercial use

## Installation

```bash
npm install timoro
```

Or globally:

```bash
npm install -g timoro
timoro init
```

## Quick Start

```typescript
import { Timoro } from 'timoro'

const ai = new Timoro({
  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: './.timoro/log.md' },
})

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

## Configuration Object

```typescript
interface TimoroConfig {
  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

```
timoro init                   — initialize timoro in current project
timoro start                  — start the full agent
timoro watch                  — start terminal watcher
timoro index                  — index all knowledge sources
timoro ask "query"            — query the knowledge base directly
timoro scan                   — scan for malware and compromised deps
timoro analyze --db <url>     — AI data analyst REPL
timoro pentest                — run security analysis
timoro ci                     — headless CI pipeline
timoro log                    — display current log
timoro reset                  — clear vector store and re-index
```

## 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

## Brain Providers

| Provider | Model | Requires |
|---|---|---|
| local | llama3.2 | nothing |
| openai | gpt-4, gpt-4o | openai package + API key |
| claude | sonnet, opus | @anthropic-ai/sdk + API key |
| gemini | pro, flash | @google/generative-ai + API key |
| ollama | any local model | ollama running locally |

## Malware Scanner

```
timoro 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

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

Interactive REPL: natural language → LLM-generated SQL → human approval → execute → Excel/dashboard export.
Security: 3-layer defense (schema filter → SQL audit → result masking). LLM never sees sensitive tables or columns.
--package-exe: bundles HTML dashboard as a self-contained .exe (win-x64, win-arm64, macos-x64, macos-arm64, linux-x64). Fully offline, Chart.js inlined.

## Pentester Mode

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

### Active (mode: 'active')
Real attack testing — requires declared authorization scope:
- Scope declaration with SHA-256 integrity and "I AUTHORIZE" confirmation
- CIDR matching for target validation — public IPs blocked without explicit scope
- DoS tools blocked at command level (hping3, slowloris, loic, hoic)
- Mass scans blocked (/16+ CIDR)
- 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

```
timoro 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.

## Data Security (3-layer)

Layer 1 — Schema Filter: removes blocked tables/columns before LLM generates SQL.
Layer 2 — SQL Audit: blocks INSERT/UPDATE/DELETE/DROP/GRANT/EXEC, references to sensitive tables.
Layer 3 — Result Masking: redacts values matching sensitive patterns (bcrypt, argon2, JWT, AWS keys, CPF, private keys).
Default blocks 42 column patterns and 11 table patterns.

## Session State Protocol

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

## Write Lock Protocol

Prevents race conditions between external LLM agent writes and Timoro'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 | Timoro |
| Surgical corrections to existing files | Timoro |
| Security analysis and vulnerability patching | Timoro |
| Diff approval | User |

## Architecture

Three layers:
1. TypeScript Layer — Public API + CLI (src/)
2. napi-rs Bridge — Native Rust binding (no subprocess overhead)
3. Rust Core — LLM inference (Candle), embeddings (1024-dim), vector store (usearch HNSW), terminal spawning (tokio), file watching (notify), error parser (7 languages), auto-fix (similar crate), pentester

## Technology Stack

### Rust
Candle, tokenizers, usearch, tokio, notify, reqwest, similar, napi-rs, thiserror

### TypeScript
commander, knex, mongodb, undici, cheerio, pdf-parse, mammoth, exceljs, pkg, cosmiconfig, chalk, ora

## License

Business Source License 1.1
- Free for personal and non-commercial use
- Commercial use requires a paid license from KR Riley Soluções
- Converts to Apache 2.0 on 2029-01-01

## Links

- **npm**: https://www.npmjs.com/package/timoro
- **GitHub**: https://github.com/kreivesler/timoro-llm
- **Documentation**: https://timoro.dev/docs
- **Support**: contato@rileysolucoes.com.br