# 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, monitors production APIs and performs active security testing — all configured via a single object.

## Core Capabilities

- Embedded local LLM via Candle (no API key required by default)
- Supports external brain providers: OpenAI, Anthropic Claude, Google Gemini, Ollama
- Knowledge base from local files (MD, TXT, PDF, DOCX, code), databases (PostgreSQL, MySQL, SQLite, MongoDB) and external URLs
- Real-time terminal watcher: reads stdout/stderr of any running process
- Autonomous error detection with file/line/column precision
- Auto-fix: applies surgical corrections directly to source files
- Structured Markdown log at .timoro/log.md with diffs, timestamps and findings
- Pentester mode: static code analysis + active security testing (brute force, port scan, SQL injection, XSS, IDOR, CORS, SSL)
- Production mode: monitoring only, autoFix disabled
- TypeScript support with full type declarations
- CLI: timoro init | start | watch | index | ask | pentest | log | reset
- 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

The full configuration object accepts: brain, knowledge, watch, pentester, log.

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

See full reference at: https://github.com/kreivesler/timoro-llm#configuration

## 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 pentest      — run security analysis
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, mistral | 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 |

## Pentester Mode

Two modes available:

### Static (`mode: 'static'`)
Source code analysis only — 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 against your running app (requires: pentester.target):
- Brute force on authentication endpoints
- Rate limiting bypass
- Port scanning for exposed services
- SQL injection payloads
- Cross-site scripting (XSS)
- Insecure Direct Object References (IDOR)
- CORS misconfiguration
- SSL/TLS analysis

**WARNING**: Use active mode only on systems you own or have explicit authorization to test.

## Log Format

All findings are written to .timoro/log.md with:
- Timestamp (HH:MM:SS)
- Category (error, fix, pentest finding, indexed)
- File path, line, column (when applicable)
- Before/after diff (when autoFix applied)
- Severity: low | medium | high | critical
- Recommendation for fixing

## Architecture

Timoro consists of three layers:

1. **TypeScript Layer** — Public API + CLI (index.ts, cli/index.ts)
2. **napi-rs Bridge** — Native binding to Rust (bridge.ts)
3. **Rust Core** — High-performance engine (crates/timoro-core/)
   - LLM inference via Candle
   - Embeddings generation
   - Vector store (usearch)
   - Terminal spawning and monitoring
   - File system watching
   - Error parsing
   - Auto-fix patching
   - Pentester analysis

## Production vs Development

**Development** (default):
```typescript
watch: { autoFix: true, confirmBeforeFix: false }
```

**Production**:
```typescript
watch: { autoFix: false, alertOnly: true }
```

In production, Timoro monitors and logs issues but does not modify code.

## Technology Stack

### Rust (crates/timoro-core/)
- Candle: LLM inference
- tokenizers: Text encoding
- usearch: Vector database
- tokio: Async runtime
- notify: File watching
- reqwest: HTTP client
- similar: Diff engine
- napi-rs: Node.js bridge

### TypeScript (src/)
- commander: CLI
- knex: Database query builder
- mongodb: NoSQL driver
- undici: HTTP client
- cheerio: Web scraping
- pdf-parse: PDF reading
- mammoth: DOCX reading
- cosmiconfig: Config loading

## 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
- **License**: https://timoro.dev/license
- **Support**: contato@rileysolucoes.com.br