@teeme/engine Public API

`init({ workspaceDir, teemeJson })`

Returns: Promise<void>

Initialize the engine. Loads all agents from workspaceDir/agents/, reads each agent's config.json, sets up the SQLite database at workspaceDir/data/teeme.db, and wires up cost tracking and circuit breakers. Must be called before any other function.

await init({ workspaceDir: '/my-company', teemeJson: parsedTeemeJson });

`startAll()`

Returns: void

Start heartbeat timers for all agents. Each agent's cron schedule (from config.json) is registered with node-cron. Agents fire independently based on their heartbeat_cron value.

`runAgentCycle(agentSlug)`

Returns: Promise<{ success, taskId?, error?, blocked? }>

Execute one full cycle for the named agent: build context, call LLM, route tool calls, write results, post to channels. Returns blocked: true if the agent is over budget or the circuit breaker is open.

const result = await runAgentCycle('leila');
// { success: true, taskId: 'task_abc123' }

`shutdown()`

Returns: Promise<void>

Gracefully stop all heartbeat timers and close the SQLite database connection. Call on process exit or SIGTERM.

`getStatus()`

Returns: Array<{ slug, name, role, status, currentTask, costToday, lastHeartbeat }>

Snapshot of all agents. status is one of: idle, running, blocked, error. costToday is in USD. lastHeartbeat is an ISO timestamp or null.

`getCosts(opts?)`

Returns: Array<{ agent, model, tokens, cost, period }>

Cost breakdown by agent and model. opts.period accepts 'today', 'week', 'month' (default: 'today'). opts.agent filters to a single agent slug.

`getLogs(agent?, limit?)`

Returns: Array<{ timestamp, agent, action, details }>

Recent activity log. agent is an optional slug filter. limit defaults to 100. Sourced from the agent_logs table in SQLite.

`getEngine()`

Returns: Engine | null

Returns the raw Engine instance for advanced use (direct DB access, event subscriptions, custom middleware). Returns null if init() has not been called.

`getPatternStats()`

Returns: Array<{ agent, task_category, count, avg_tokens, avg_cost }>

Learning stats from the task_patterns table. Shows which agents handle which task categories and the average token and cost footprint per category.

`getRoutingStats()`

Returns: Array<{ task_category, model_id, attempts, success_rate, avg_cost }>

Routing history from the routing_log table. Used by the adaptive router to prefer models with high success rates and lower costs for each task category.

teeme.json Schema

The root configuration file for a Teeme workspace.

{
  "version": "1.0",
  "company": {
    "name": "Inscape Interiors",
    "slug": "inscape",
    "timezone": "Europe/Luxembourg",
    "language": "en"
  },
  "template": "design-build",
  "provider": {
    "default": "openrouter",
    "fallback": "anthropic"
  },
  "channels": {
    "discord": {
      "enabled": true,
      "bot_token_env": "DISCORD_BOT_TOKEN",
      "guild_id": "12345678901234567"
    },
    "slack": { "enabled": false },
    "telegram": { "enabled": false }
  },
  "governance": {
    "global_monthly_budget_usd": 200,
    "alert_email": "[email protected]",
    "require_confirm_for": ["deploy", "email_send", "financial_transfer"]
  },
  "agents": ["nour", "leila", "raph", "zara", "falco", "sami"],
  "engine": {
    "db_path": "workspace/data/teeme.db",
    "log_level": "info",
    "adaptive_routing": true,
    "circuit_breaker_threshold": 3,
    "circuit_breaker_reset_minutes": 30
  }
}

Field	Description
`version`	Schema version — currently `"1.0"`
`company`	Display name, slug, timezone, default language
`template`	Slug of the template this workspace was initialized from
`provider`	Default and fallback LLM provider
`channels`	Communication channel config (Discord, Slack, Telegram)
`governance`	Global budget cap, alert contact, actions requiring confirm
`agents`	List of active agent slugs (must match `agents/` subdirs)
`engine`	DB path, logging level, routing and circuit-breaker settings

Agent config.json Schema

See Templates for the full field reference.

CLI Commands

Command	Syntax	Description
`init`	`teeme init [--template <slug>]`	Scaffold a new workspace, optionally from a template
`new-agent`	`teeme new-agent`	Interactive wizard to add an agent to an existing workspace
`start`	`teeme start`	Start all agent heartbeats (foreground)
`stop`	`teeme stop`	Stop all running heartbeats
`status`	`teeme status`	Show agent status table in terminal
`run`	`teeme run <agent>`	Trigger one cycle for a specific agent immediately
`logs`	`teeme logs [agent] [--limit N]`	Stream or dump recent agent logs
`costs`	`teeme costs [--period today	week
`connect`	`teeme connect --to-cloud`	Link self-hosted workspace to Teeme managed dashboard
`export`	`teeme init --from-cloud`	Export managed workspace to self-hosted format
`publish`	`teeme publish`	Submit workspace as a marketplace template

API Reference

@teeme/engine Public API

init({ workspaceDir, teemeJson })

startAll()

runAgentCycle(agentSlug)

shutdown()

getStatus()

getCosts(opts?)

getLogs(agent?, limit?)

getEngine()

getPatternStats()

getRoutingStats()