Teeme turns any company into an AI-native organization. You define your mission, hire AI agents into an org chart, and they execute real work — autonomously, on schedule, with full governance.

This guide covers everything from first install to advanced features.

1. Getting Started (CLI)

Install and scaffold a workspace in under two minutes:

npx teeme init                    # Interactive: pick template, name company, set API keys
teeme run                         # Start engine + all agents
teeme status                      # Check agent health
teeme new-agent slug name role    # Add an agent to the org chart
teeme validate                    # Check workspace structure for errors
teeme goals                       # View goal tree (mission → goals → projects → tasks)
teeme cost                        # View LLM spending by agent and model
teeme logs [agent]                # View agent logs (all agents or a specific one)
teeme import-team path            # Import an external team via BYOA protocol
teeme dashboard                   # Local web dashboard (coming v1.1)

Example: create a restaurant workspace

npx teeme init
# → Pick template: restaurant-hospitality
# → Company name: Chez Marcel
# → LLM provider: openrouter (default)
# → API key: sk-or-v1-xxx
# Workspace created at ./chez-marcel

cd chez-marcel
teeme run
# ✓ Engine started on port 4700
# ✓ General Manager — next heartbeat in 4h
# ✓ Operations Manager — next heartbeat in 6h
# ✓ Marketing Lead — next heartbeat in 8h

2. Workspace Structure

After running teeme init --template restaurant-hospitality, you get:

my-restaurant/
├── teeme.json          # Workspace config (company, provider, governance, agent registry)
├── .env                # API keys (chmod 600, gitignored)
├── package.json        # { dependencies: { "@teeme/engine": "^1.0.0" } }
├── company/
│   ├── mission.md      # Company mission statement
│   └── goals/          # Strategic goals with KPIs
├── agents/
│   └── {slug}/         # One directory per agent
│       ├── SOUL.md     # Identity, decision rules, escalation triggers
│       ├── SKILLS.md   # Domain knowledge (injected at runtime)
│       ├── TOOLS.md    # Permitted tools with risk levels
│       ├── HEARTBEAT.md # Scheduled cycle protocol
│       ├── config.json # Model, budget, cron, reporting line
│       └── prompts/    # system.md, task.md, report.md
├── data/tasks.db       # SQLite — engine source of truth
└── logs/               # Agent activity logs

Key files explained

teeme.json — The workspace manifest. Defines the company name, default LLM provider, governance settings, and the full agent registry. The engine reads this on startup.

.env — Stores API keys (OPENROUTER_API_KEY, OPENAI_API_KEY, etc.). Automatically set to chmod 600 and added to .gitignore during init. Never committed.

SOUL.md — Each agent's identity document. Contains who they are, how they make decisions, when they escalate, and what they never do. This is the single most important file per agent — it shapes every LLM call.

config.json — Per-agent settings: which model to use, monthly budget cap, cron schedule, and who they report to in the org chart.

data/tasks.db — SQLite database in WAL mode. Stores all tasks, proposals, cost records, and pattern memory. The engine is the only writer — agents interact through the engine, never directly.

3. Agent Lifecycle

Every agent runs on a heartbeat cycle. Here is exactly what happens each time:

The Heartbeat (step by step)

Cron fires. The agent's schedule triggers (e.g., every 4 hours for a General Manager, every 6 hours for an Operations Manager).
Policy engine checks gates. Before anything runs, the engine verifies:
- Circuit breaker: is the agent healthy? (tripped after 3 consecutive failures)
- Budget: has the agent exceeded its monthly spend limit?
- Tier gate: does the agent have permission for pending actions?
- Rate limit: has the agent been called too recently?
If any gate fails, the heartbeat is skipped and the reason is logged.
Task selection. The engine queries SQLite for the next task from the backlog. Tasks are ranked by priority + age — high-priority tasks go first, but old tasks get boosted so nothing rots in the queue.
Atomic claim. The engine claims the task in a single SQL transaction. This prevents two agents from executing the same task if heartbeats overlap.
Prompt assembly. The engine builds the full prompt by combining:
- SOUL.md — agent identity and decision rules
- SKILLS.md — domain knowledge
- Goal context — the mission, goal, and project this task belongs to
- Task details — title, description, delegation context
- Past patterns — what worked last time on similar tasks
LLM call. The assembled prompt is sent to the LLM via the router (OpenRouter by default). The engine selects the model from the agent's config.json, or uses adaptive routing if enabled.
Tool-calling loop. The LLM can request tools (up to 15 rounds per task). For each tool call:
- Engine checks the tool's risk level against governance tiers
- If permitted: executes the tool, returns results to the LLM
- If blocked: returns a rejection message, LLM must find another approach
Completion. Task is marked done. The engine records:
- Cost (input tokens, output tokens, USD)
- Duration
- Tools used
- Success or failure
- Pattern data for future learning
Circuit breaker update. On success: breaker resets. On failure: failure count increments. After 3 consecutive failures: breaker trips and the agent is paused until manually reset or auto-recovery kicks in.

4. Governance Model (5 Tiers)

Every tool in Teeme has a risk level. The policy engine enforces these in code, before the LLM call. The LLM cannot bypass governance — it never even sees tools it's not allowed to use.

Tier	What Happens	Example
AUTO	Execute silently, no approval needed	Read database, check supplier prices, run health checks
AUTO+	Execute and notify the reporting channel	Draft an email, update a tracker, create a task for a team member
PROPOSE	Execute with a 15-minute rollback window	Send a client email, deploy to staging, publish a blog post
CONFIRM	Wait for human approval (board emoji reaction)	Production deploys, contract changes, large purchases
BLOCK	Hardcoded rejection — never executes, ever	Financial transfers, legal filings, credential changes

How PROPOSE works in practice

1. Agent wants to send an email to a supplier
2. Engine sees the send-email tool is tier PROPOSE
3. Engine executes the action but starts a 15-minute rollback timer
4. Notification posted to the channel: "📋 Proposal: Send email to Supplier X re: invoice #4521"
5. If human reacts with ❌ within 15 minutes → action is rolled back
6. If no reaction → action auto-commits after 15 minutes
7. If human reacts with ✅ → action commits immediately

How CONFIRM works

1. Agent wants to deploy to production
2. Engine sees deploy-production is tier CONFIRM
3. Engine posts to channel: "🔒 Awaiting approval: Deploy v2.3 to production"
4. Nothing happens until a human reacts with ✅
5. Human approves → engine executes
6. Human rejects with ❌ → task is cancelled

The governance tiers are defined in each agent's TOOLS.md and enforced by the engine. You configure them once and they apply to every heartbeat, every task, every tool call.

5. Goal Cascade

Every task in Teeme traces back to the company mission. This gives agents context about not just WHAT to do, but WHY they're doing it.

Company Mission: "Become the best farm-to-table restaurant in Luxembourg"
  │
  └── Goal: Operational Excellence
      │   KPI: customer satisfaction > 4.5/5
      │
      └── Project: Supplier Quality Improvement
          │   Deadline: Q2 2026
          │
          └── Task: "Audit top 5 supplier invoices for price anomalies"
              → Assigned to: Operations Manager
              → Prompt includes: mission + goal + project + task

When the Operations Manager agent processes this task, its prompt contains:

You are the Operations Manager at Chez Marcel.
Company mission: Become the best farm-to-table restaurant in Luxembourg.
Current goal: Operational Excellence (target: customer satisfaction > 4.5/5).
Project: Supplier Quality Improvement.
Your task: Audit top 5 supplier invoices for price anomalies.

This cascading context means agents make decisions aligned with company strategy, not just task-level instructions.

Manage goals with the CLI:

teeme goals
# Mission: Become the best farm-to-table restaurant in Luxembourg
# ├── Operational Excellence (4.2/5 → target 4.5/5)
# │   ├── Supplier Quality Improvement (3/7 tasks done)
# │   └── Kitchen Workflow Optimization (1/4 tasks done)
# └── Revenue Growth (€42k/mo → target €55k/mo)
#     └── Catering Service Launch (0/5 tasks done)

6. Pattern Memory (Self-Improving Agents)

Teeme agents learn from their own history. After each completed task, the engine stores what worked:

What gets recorded

Task category: reporting, email-triage, content-creation, data-analysis, etc.
Approach: the strategy the agent used (e.g., "compared invoices against 3-month rolling average")
Tools used: which tools were called and in what order
Cost: total tokens and USD spent
Outcome: success or failure, with details

How patterns are reused

Before executing a new task, the engine searches for past patterns with matching categories:

New task: "Audit supplier invoices for Q1"
Engine finds pattern from last month:
  Category: data-analysis
  Approach: "Pull invoices from tracker, compare against rolling average, flag >10% variance"
  Tools: [read-tracker, calculate-variance, create-report]
  Cost: $0.04
  Outcome: success — found 2 anomalies

→ Pattern injected into prompt:
  "In a similar past task, you successfully used this approach: ..."

The agent reuses the proven approach instead of reasoning from scratch. The result: 30-50% fewer tokens on recurring tasks, and more consistent quality over time.

7. Inter-Agent Delegation

When a manager agent creates a task for a team member, full context travels with it. No information is lost between agents.

Example: General Manager delegates to Operations Manager

{
  "title": "Review supplier invoices for price anomalies",
  "assigned_to": "operations-manager",
  "delegation_context": {
    "reasoning": "Invoice from Supplier X is 23% above last quarter average",
    "data": {
      "supplier": "Ferme du Nord",
      "current_invoice": 2840,
      "last_quarter_avg": 2309,
      "variance_pct": 23,
      "threshold_pct": 10
    },
    "recommended_approach": "Compare with Suppliers Y and Z for the same product categories",
    "constraints": [
      "Don't switch suppliers without board approval (CONFIRM tier)",
      "Maintain relationship — this is our primary organic produce source"
    ]
  }
}

The Operations Manager receives not just the task title, but the full reasoning: why it matters, what data triggered it, how to approach it, and what guardrails apply.

This delegation chain can go multiple levels deep: General Manager → Operations Manager → a specific task, each level adding context.

8. Cost Tracking

Every LLM call is metered. Nothing runs untracked.

What gets recorded per call

Agent slug (who made the call)
Model used (e.g., openai/gpt-4o, anthropic/claude-sonnet-4-20250514)
Input tokens, output tokens
Cost in USD
Task ID (what it was for)

Budget controls

Each agent has a monthly budget in config.json:

{
  "model": "openai/gpt-4o",
  "monthly_budget_usd": 15.00,
  "budget_alert_pct": 80
}

At 80% of budget: engine posts a warning to the agent's channel
At 100% of budget: agent is auto-paused until next month or budget is increased
Budget resets on the 1st of each month

Adaptive model routing

The engine tracks which model performs best (success rate, cost) for each task category. Over time, it routes tasks to the cheapest model that still gets the job done:

Complex analysis → stays on GPT-4o or Claude Sonnet
Simple reporting → downgraded to a faster, cheaper model
Pattern-matched tasks with proven approaches → smallest effective model

CLI cost view

teeme cost
# Agent              This Month    Budget    Usage
# general-manager    $3.42         $20.00    17%
# operations-mgr    $1.87         $15.00    12%
# marketing-lead    $5.21         $15.00    35%
# ─────────────────────────────────────────────
# Total              $10.50        $50.00    21%

9. BYOA Protocol (Bring Your Own Agent)

External agent systems can join a Teeme company's org chart via heartbeat HTTP calls. Any agent that can send an HTTP POST can be "hired" into the team.

How it works

Import the external team definition:

teeme import-team ./klawty-team.json

The external agent sends periodic heartbeats to the Teeme engine:

POST /api/heartbeat
Content-Type: application/json

{
  "agent_id": "atlas",
  "team_id": "klawty-team-dcode",
  "status": "running",
  "current_task": "Deploying staging build",
  "cost_this_cycle": 0.003,
  "result_summary": "Deployed commit abc123 to staging"
}

The engine tracks the external agent just like a native one — it appears in teeme status, its costs are recorded, and it shows up in the org chart.

What external agents get

Visibility in the Teeme dashboard and CLI
Cost tracking alongside native agents
Ability to receive delegated tasks from Teeme agents
Governance enforcement (the engine validates tool tiers for delegated work)

What external agents keep

Their own runtime (they run wherever they already run)
Their own model and provider
Their own execution loop

The BYOA protocol is intentionally minimal — one HTTP endpoint, one JSON schema. If your agent can POST JSON, it can join a Teeme boardroom.

10. Two Ways to Use Teeme

Self-hosted (free, forever)

npx teeme init
teeme run

You get the full engine, all templates, unlimited agents. You manage infrastructure, API keys, and uptime. Perfect for developers and teams who want full control.

You need: A machine that stays on (Mac, Linux server, VPS), an LLM API key (OpenRouter, OpenAI, Anthropic, or Google).

Managed (paid plans)

Plan	Price	What's Included
Starter	€99/mo	Up to 3 agents, 1 workspace, email support
Growth	€249/mo	Up to 8 agents, 3 workspaces, priority support, advanced analytics
Enterprise	€449/mo	Unlimited agents, unlimited workspaces, dedicated support, custom templates

Managed flow:

Sign up and complete the onboarding wizard
Pick a template or describe your company
Agents are deployed and configured for you
Manage everything from the web dashboard
No CLI, no server, no DevOps

LLM costs are separate — you bring your own API key or use Teeme's pooled access (usage-based billing).

Quick Reference

Command	What it does
`teeme init`	Create a new workspace from a template
`teeme run`	Start the engine and all agents
`teeme status`	Show agent health and next heartbeat times
`teeme new-agent ops-mgr "Operations Manager" operations`	Add a new agent
`teeme validate`	Check workspace for structural errors
`teeme goals`	Display the goal cascade tree
`teeme cost`	Show LLM spending breakdown
`teeme logs marketing-lead`	View logs for a specific agent
`teeme import-team ./team.json`	Import external agents via BYOA

For template examples and API reference, see the Teeme documentation.

How It Works