Quick Start

Requirements

Step 1 — Install

Install Timoro as a dev dependency or globally. The Rust core compiles automatically via napi-rs on first install.

# as a dev dependency
npm install timoro

# or globally
npm install -g timoro

Step 2 — Initialize

Run timoro init in your project root. This will:

• Create timoro.config.ts with sensible defaults
• Create the .timoro/ directory for logs and cache
• Download the default LLM model (~1.5GB, one time only)
• Update .gitignore to exclude models and vectors

npx timoro init

Step 3 — Start

Start the full agent. Timoro will index your knowledge base, spawn alongside your dev process and start watching.

npx timoro start

Or watch a specific command directly:

timoro watch --cmd "npm run dev"
timoro watch --cmd "cargo run"
timoro watch --cmd "python app.py"

Minimal Programmatic Setup

Use Timoro directly in your code without the CLI:

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()   // index knowledge sources
await ai.watch()   // start agent (blocks until stop())

What happens next

Once running, Timoro:

• Indexes all files in knowledge.dirs, databases and URLs into the local vector store
• Spawns your dev process and reads stdout/stderr in real time via Tokio async runtime
• Detects errors with file, line and column precision (TypeScript, JavaScript, Python, Rust, Go, Java, PHP, Ruby)
• Applies surgical fixes via Retrieval-Augmented Fix (RAF) — KB semantic search before pattern matching
• Writes every event to .timoro/log.md with diffs and recommendations
• Saves a machine-readable session snapshot to .timoro/session.json

Other useful commands

# scan for malware and compromised deps
timoro scan

# AI data analyst (natural language → SQL)
timoro analyze --db postgresql://localhost/mydb

# headless CI pipeline
timoro ci --github

# query your codebase
timoro ask "how does the auth service work?"