Teotl

An autonomous agent framework for Python: planner-worker execution, built-in guardrails, and any LLM provider.

Teotl splits agent work between a planner (a strong model that runs once to write a step-by-step plan) and a worker (a cheaper, faster model that executes each step). Every tool call passes through a policy-based guardrail layer before it runs, and a harness keeps plans, progress, costs, and audit logs on disk so long-running missions can pause, resume, and be inspected.

Status: alpha (v0.2.0). APIs may change between minor versions.

Features

• Planner-worker harness: plan once with a capable model, execute many steps with a cheap one
• Guardrails: minimal / standard / strict policies, bash command analysis, prompt-injection checks, rate and cost limits, progressive trust
• Multi-provider: Anthropic Claude, OpenAI, Google Gemini, Ollama (local), or LiteLLM
• Skills: capabilities defined in SKILL.md files, loaded on demand to save context (filesystem, git, GitHub, web, Claude Code, spec-kit, social media)
• Memory: optional local vector memory with automatic context compaction
• Harness artifacts: PLAN.md, PROGRESS.md, state checkpoints, cost tracking, append-only audit log
• Credentials: OS keyring, encrypted file, or AWS Secrets Manager storage
• CLI and dashboard: interactive chat, onboarding wizard, and a web dashboard for monitoring agents

Installation

pip install "teotl[anthropic]"

Pick the extras you need:

Requires Python 3.11 or newer.

Quick start

Set an API key:

export ANTHROPIC_API_KEY="sk-ant-..."

A single agent

import asyncio

from teotl import Agent
from teotl.core.provider import AnthropicProvider


async def main():
    agent = Agent(
        provider=AnthropicProvider(model="claude-sonnet-5-5"),
        instructions="You are a careful code reviewer.",
        skills=["filesystem", "git"],
        policy="standard",  # or "strict" / "minimal"
    )
    response = await agent.run("Summarize the last 5 commits in this repo.")
    print(response.text)
    print(f"Cost: ${response.cost:.4f}")


asyncio.run(main())

Planner-worker

import asyncio
from pathlib import Path

from teotl.core.provider import AnthropicProvider
from teotl.primitives.harness import PlannerWorkerHarness


async def main():
    harness = PlannerWorkerHarness(
        agent_id="code-quality",
        planner_provider=AnthropicProvider(model="claude-sonnet-5-5"),        # plans once
        worker_provider=AnthropicProvider(model="claude-haiku-4-5"),  # executes each step
        workspace_dir=Path(".teotl/code-quality"),
        worker_skills=["filesystem", "git"],
    )

    plan = await harness.plan(goals="Add type hints and docstrings to public functions in src/.")
    print(f"Plan has {plan.total_steps} steps (see PLAN.md)")

    while not harness.is_complete():
        result = await harness.execute_next_step()
        print(f"Step {result.step.number}: {'ok' if result.success else result.error}")


asyncio.run(main())

The harness writes PLAN.md and PROGRESS.md into the workspace, so you can read, edit, or resume a plan at any point. By default it asks for approval before starting each new execution cycle.

Other providers

from teotl.core.provider import GeminiProvider, OllamaProvider, OpenAIProvider

GeminiProvider(model="gemini-2.5-flash")   # GOOGLE_API_KEY
OpenAIProvider(model="gpt-4.1")            # OPENAI_API_KEY
OllamaProvider(model="llama3.1")           # local, no key

You can mix providers, for example a Claude planner with a local Ollama worker.

Command line

teotl --help
teotl onboard      # interactive setup wizard: provider, skills, policy, planner-worker config
teotl chat         # interactive chat with an agent
teotl security     # manage credentials and security settings

Guardrails

Every tool call is classified and checked against a policy before it executes. This happens outside the model's context, so a prompt can't talk its way past it.

• strict: read-only by default; writes and shell commands need approval
• standard: common development actions allowed; destructive or sensitive actions need approval
• minimal: for trusted sandboxes

Built-in protections include bash command analysis (for example blocking rm -rf / and piping remote scripts to a shell), prompt-injection checks on instructions and incoming messages, per-agent rate and cost limits, and a trust score that grows with repeated safe behavior. See docs/GUARDRAILS.md.

Skills

A skill is a folder containing a SKILL.md file (YAML frontmatter plus instructions). Only each skill's short description sits in context until the agent activates it, which keeps prompts small.

Teotl looks for skills in:

1. the skills bundled with the package
2. ~/.teotl/skills/ (your own skills; the data directory can be moved with TEOTL_HOME)
3. any directories listed in TEOTL_SKILLS_PATH (colon-separated)

See docs/SKILLS_GUIDE.md and docs/CUSTOM_SKILLS_QUICKSTART.md.

Examples

Documentation

• Getting started
• Architecture
• Guardrails and security guide
• Memory
• Model strategy
• Multi-agent guide

Roadmap

• Planner-worker harness
• Guardrails, credential storage, audit log, cost tracking
• Anthropic, OpenAI, Gemini, Ollama, LiteLLM providers
• YAML configuration for multi-agent setups
• Browser automation and social media skills
• Published benchmark results (GAIA and cost comparisons)
• More end-to-end examples (code review, test generation)
• Deeper MCP integration

Contributing

Bug reports, ideas, and pull requests are welcome.

• Questions and ideas: Discussions
• Bugs and feature requests: Issues
• Code: see CONTRIBUTING.md

git clone https://github.com/keithdit4e/teotl
cd teotl
pip install -e ".[dev,anthropic]"
pytest

Report security issues privately. See SECURITY.md.

License

MIT © Keith Foster