// Reference

API Reference

Full programmatic API for the Timoro class — methods, events and TypeScript types.

Constructor

typescript
import { Timoro } from 'timoro'

const ai = new Timoro(config: TimoroConfig)

Methods

init()

Initializes the Timoro engine: loads the native Rust binding, starts the event loop and indexes the knowledge base. Must be called before any other method.

signature
ai.init(): Promise<void>

watch()

Starts the terminal watcher and autonomous agent. Spawns the configured process and reads stdout/stderr in real time. Blocks until stop() is called.

signature
ai.watch(): Promise<void>

ask(query)

Queries the knowledge base and returns an LLM response grounded in your indexed project context.

signature
ai.ask(query: string): Promise<string>

// Example
const answer = await ai.ask('How does the auth service work?')

pentest()

Runs the security analysis engine. Behavior depends on pentester.mode in config.

signature
ai.pentest(): Promise<void>

index()

Re-indexes all configured knowledge sources. Use when you've added new files, updated the database or changed the config.

signature
ai.index(): Promise<void>

stop()

Stops all watchers, releases the Rust native binding and shuts down gracefully.

signature
ai.stop(): Promise<void>

isInitialized() / isRunning()

signature
ai.isInitialized(): boolean
ai.isRunning(): boolean

if (!ai.isInitialized()) await ai.init()
if (!ai.isRunning()) await ai.watch()

getLogger()

Returns the logger instance for writing custom entries to .timoro/log.md.

example
const logger = ai.getLogger()

await logger.info('Deployment started')
await logger.securityFinding(
  'high', 'SQL Injection',
  'src/db.ts', 28,
  'String concatenation in query',
  'Use parameterized queries'
)

Events

All events are emitted during watch() and pentest().

exampleTypeScript
ai.on('error-detected', (e) => {
  // e.file, e.line, e.column, e.message, e.stackTrace
  console.log(`Error in ${e.file}:${e.line}`)
})

ai.on('fix-applied', (e) => {
  // e.file, e.line, e.before, e.after, e.diff
  console.log(`Fixed ${e.file}`)
})

ai.on('pentest-finding', (e) => {
  // e.severity, e.type, e.file, e.description, e.recommendation
  console.log(`[${e.severity}] ${e.type}`)
})

ai.on('indexed', (e) => {
  // e.totalDocuments, e.totalChunks, e.diskSize
  console.log(`Indexed ${e.totalDocuments} documents`)
})

Full example

server.tsTypeScript
import { Timoro } from 'timoro'
import config from './timoro.config'

const ai = new Timoro(config)

ai.on('error-detected', (e) => {
  console.log(`✗ ${e.file}:${e.line} — ${e.message}`)
})

ai.on('fix-applied', (e) => {
  console.log(`✓ Fixed ${e.file}`)
})

ai.on('pentest-finding', (e) => {
  console.log(`[${e.severity.toUpperCase()}] ${e.description}`)
})

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

// graceful shutdown
process.on('SIGINT', async () => {
  await ai.stop()
  process.exit(0)
})
← ConfigurationPentester Mode →