TeaAgent

Governance-first agent harness for autonomous coding tasks. Thin orchestration layer with tool governance, state boundaries, audit logging, and destructive-tool approval.

Golden path (first hour)

One canonical flow for new users. Everything else in this README is advanced — see docs/USAGE.md for the full walkthrough and recovery recipes.

pip install -e .

# 1. Configure workspace (provider + safety defaults)
teaagent setup --root . --provider gpt --permission-mode read-only --write-env

# 2. Inspect readiness without calling a model
teaagent daily "summarize this repo" --dry-run --root . --human

# 3. First read-only task (provider comes from .teaagent/config.json)
teaagent run "summarize the test suite" --permission-mode read-only --root .

Advanced (recovery only): teaagent doctor model, teaagent doctor providers, manual ~/.teaagent/providers_env.zsh, legacy teaagent init, Keychain helpers — docs/USAGE.md#recovery-recipes.

Daily use (after setup)

Read-only cockpit each session:

teaagent daily "what I want to do today" --human
teaagent run "summarize the test suite" --permission-mode read-only

Edit or autonomous modes, TUI, recipes, and context profiles: docs/USAGE.md#daily-use.

Interactive loop: teaagent tui --setup --root ., then daily, preflight, ask, runs, resume.

Start Here

1. Install

pip install -e .

On macOS/Homebrew Python (PEP 668), prefer a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
pip install -e ".[dev]"

Install enhanced TUI editing/history support (optional):

pip install -e ".[tui]"

2. First Run

Same as the golden path above. Prefer --human on daily for readable readiness; omit it when scripting (JSON default).

3. Permission Modes

read-only: blocks destructive tools
workspace-write: allows file writes, blocks shell mutation
prompt: asks for approval on destructive actions
allow: allows destructive tools for the session
danger-full-access: full access for trusted automation only

4. Plan vs Write

Planning/exploration: use --permission-mode read-only
Editing/implementation: use --permission-mode workspace-write or prompt

5. Extensibility

MCP server: teaagent mcp serve
Skills/plugins: documented in docs/tool-authoring.md and docs/provider-authoring.md

6. Docs

Quick start: docs/USAGE.md
CLI/MCP reference: docs/cli.md
Acceptance coverage: docs/acceptance.md
Use-case traceability: docs/use-cases.md
Architecture decisions: docs/adr (including ANP adapter boundary in ADR 0007)

Architecture

CLI / TUI  →  AgentRunner (decision loop)  →  ToolRegistry  →  Workspace Tools
                  ↕                              ↕
           LLM Adapters                  ApprovalPolicy
           (13 providers)                 (5 permission modes)

AgentRunner: Iterates between model decisions and tool executions within budget limits.
ToolRegistry: Single point of tool dispatch with schema validation.
ApprovalPolicy: Enforces permission modes before any destructive tool runs.
AuditLogger: Universal event sink — every decision, execution, and error is recorded.
ModelDecisionEngine: Bridges LLM responses into structured decisions via prompt assembly and JSON parsing.
Workspace Tools: File read/write, shell inspect/mutate, glob search, git status, hash-anchored editing.
Memory Catalog: Three-tier memory system (Project/Personal/Auto-Memory) for persistent context.
Intent Clarification: Deterministic ambiguity scoring before model invocation.
Run Store: Persistent JSONL run history with resumable task replay.
Code Mode: Restricted Python execution with AST validation and pluggable child-process or container backends.
Telemetry: OpenTelemetry spans plus audit-driven metrics sinks for run and tool lifecycle events.
Heartbeat: Background audit events for run liveness monitoring and hang detection.
Daily Brief: Read-only readiness cockpit with recent runs, pending approvals, harness warnings, and token/cost budget.
Hook System: 8-event lifecycle (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop, SubagentStop, SessionEnd) for extensibility.
Plugin System: Four extension points (Commands, Agents, Hooks, MCP Servers) compatible with Claude Code.
Context Compaction: Automatic context compression at 75-92% token usage (Claude Code compatible).
Plan Mode: Read-only exploration mode for safe codebase analysis.
ACP Adapter: Agent Client Protocol integration for VS Code, Zed, and JetBrains IDEs.

See docs/architecture.md for component details, data flow, and extension points.

Install

pip install -e .

On macOS/Homebrew Python (PEP 668), prefer a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
pip install -e ".[dev]"

Or without the console script:

python3 -m teaagent.cli --help

Requires Python >= 3.10. Optional dependency groups enable non-core integrations:

pip install -e ".[graphqlite]"
pip install -e ".[tui]"
pip install -e ".[oauth]"
pip install -e ".[telemetry]"
pip install -e ".[dev]"
pip install -e ".[release]"
pip install -e ".[security]"

graphqlite: GraphQL RAG persistence features.
tui: prompt-toolkit-powered interactive editing/history in teaagent tui.
oauth: OAuth 2.1 / DPoP cryptographic proof validation.
telemetry: OpenTelemetry tracing and metrics exporters.
dev: tests, linting, type checking, and pre-commit.
release: local build and distribution checks.
security: local dependency auditing with pip-audit.

Quick Start

New to TeaAgent? See the Quick Start Guide for a step-by-step walkthrough covering API key setup, agent mode, chat mode, approvals, and troubleshooting.

# 1. Set up API keys (one-time)
cp scripts/providers_env.zsh ~/.teaagent/providers_env.zsh
# Edit the file and fill in your keys, then:
echo 'source ~/.teaagent/providers_env.zsh' >> ~/.zshrc
source ~/.zshrc

# Optional per-project overrides (generated by doctor wizards):
source .teaagent/env

# 2. Verify setup
teaagent doctor model gpt

# 3. Run an inspect-only task
teaagent agent run gpt "Summarize the test suite" --permission-mode read-only

# 4. Start interactive TUI
teaagent tui --chat

Optional: Keychain Mode

If you keep secrets in macOS Keychain, you can keep using ~/.teaagent/provider_keys_keychain.zsh and the helper function teaagent_configure_provider_keys:

cp scripts/provider_keys_keychain.zsh ~/.teaagent/provider_keys_keychain.zsh
source ~/.teaagent/provider_keys_keychain.zsh
teaagent_configure_provider_keys

Recommended load order:

source ~/.teaagent/providers_env.zsh
source ~/.teaagent/provider_keys_keychain.zsh
source .teaagent/env

This keeps global defaults first, then secure keychain-loaded values, then project-specific overrides last.

Workers AI vs AI Gateway:

Workers AI is the model inference endpoint.
AI Gateway is an optional routing/policy layer in front of Workers AI.
WORKERS_AI_BASE_URL can point to either direct Workers AI (.../ai/v1) or AI Gateway workers-ai provider route (https://gateway.ai.cloudflare.com/.../workers-ai/v1).
For AI Gateway unified OpenAI-compatible routing, set AIGATEWAY_BASE_URL=https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/compat and use model names like dynamic/default.

Environment Variables

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=...
export GEMINI_API_KEY=...
export OPENROUTER_API_KEY=...
export OLLAMA_API_KEY=...   # optional for local deployments
export VLLM_API_KEY=...     # optional for local deployments
export OPENCODEZEN_API_KEY=...
export MISTRAL_API_KEY=...
export DEEPSEEK_API_KEY=...
export XAI_API_KEY=...
export CLOUDFLARE_API_TOKEN=...

Features

Permission Modes

Mode	Behavior
`read-only`	Blocks all destructive tools
`workspace-write`	Allows file writes; blocks shell mutation
`prompt`	Destructive tools pause for HITL approval or require an approval token
`allow`	Allows destructive tools for the session
`danger-full-access`	Full access; reserve for trusted automation

Plan Mode

Enable read-only exploration mode to analyze codebases without making changes:

teaagent agent run gpt "Analyze this codebase" --permission-mode read-only

This is useful for:

Understanding unfamiliar code
Planning refactoring approaches
Code review without accidental modifications

Tool Governance

All tools registered through ToolRegistry with name, description, input/output schemas, and annotations.
Destructive tools are blocked unless an approval token is present for that exact call.
Shell commands are split into workspace_run_shell_inspect (safe) and workspace_run_shell_mutate (destructive).
Hash-anchored line editing provides deterministic workspace edits.

Agent Run

# Basic run
teaagent agent run gpt "Inspect this repo and summarize the test suite"

# With routing and workspace write
teaagent agent run gpt "Update README" --permission-mode workspace-write --route-model

# With clarification gate
teaagent agent run gpt "Improve this project" --clarify

# List runs
teaagent agent runs

# Daily readiness + token/cost budget
teaagent agent daily gpt "Summarize the tests" --permission-mode read-only

# Resume a run
teaagent agent resume gpt <run_id>

LSP Code Analysis (P0)

Enable LSP-backed tools for semantic code navigation:

teaagent agent run gpt "inspect src/app.py" --code-analysis

Available tools when enabled:

code_definition
code_references
code_diagnostics
code_symbols

You can also enable this by workspace config:

{
  "code_analysis_enabled": true
}

Streaming (live feedback)

TeaAgent exposes two live streams:

Agent progress — iteration and tool-call lines (progress on in TUI; teaagent agent run … --progress on CLI; default on when stderr is a TTY).
Model text — user-visible answer text only (stream on in TUI; --stream on CLI; filters out structured decision JSON).

For scripts and IDE integrations, use --json-stream to emit normalized NDJSON events (text_delta, tool_call_started, …) on stdout, then attach with teaagent agent attach <run_id> --follow --json-stream.

MCP Server

Expose the workspace tool pack to MCP clients over stdio JSON-RPC or Streamable HTTP:

# stdio (default)
teaagent mcp serve --root /path/to/repo

# Streamable HTTP on loopback (POST /mcp, GET /mcp SSE, DELETE /mcp)
teaagent mcp serve --http --port 7330 --auth-token "$MCP_TOKEN"

initialize issues a fresh Mcp-Session-Id header; every later request must echo it. Pass --allowed-origin (repeatable) to restrict browser callers. See docs/cli.md for full transport details.

MCP Filtering & Sampling

MCP tool calls can be filtered by allow/block lists and configured with sampling parameters:

from teaagent.mcp_client import MCPClientFactory

client = MCPClientFactory.create_http(
    "https://mcp-server.example.com/mcp",
    allowed_tools=["read_file", "search"],
    blocked_tools=["shell", "delete"],
    sampling_max_tokens=4096,
    sampling_temperature=0.7,
)

Skills System

TeaAgent supports skill packages for reusable agent behaviors. Skills are discovered from:

Project: .config/agent/skills/ (highest priority)
Project: .claude/skills/
Project: .opencode/skill/
Project (legacy/plural alias): .opencode/skills/
User: ~/.config/agent/skills/
User: ~/.claude/skills/
User: ~/.config/opencode/skills/

You can override the discovery order in .teaagent/config.json:

{
  "skill_search_dirs": [
    ".config/agent/skills",
    ".claude/skills",
    ".opencode/skill"
  ]
}

You can also choose a source profile:

{
  "skill_source_profile": "default"
}

default: .config/agent, .claude, .opencode
extended: default plus .codex, .gemini, .hermes
custom: requires skill_search_dirs and only uses that list

Built-in skills:

code-review - Code review and quality analysis
git-workflow - Git operations and branch management
testing - Test writing and execution
refactoring - Code refactoring guidance
mcp-integration - MCP server configuration
p0-agent-harness - P0 harness behavior (built-in)

Plugin System

Four extension points for customization:

Type	Description	Example
Commands	Slash commands	`/commit`, `/review`
Agents	Custom subagents	`@code-reviewer`, `@tester`
Hooks	Lifecycle events	PreToolUse, PostToolUse
MCP Servers	External integrations	GitHub, databases

Hook System

8-event lifecycle hooks (Claude Code compatible):

SessionStart - Before session begins
UserPromptSubmit - After user message
PreToolUse - Before tool execution (can veto)
PostToolUse - After tool execution
PreCompact - Before context compaction
Stop - Before session stops
SubagentStop - After subagent completes
SessionEnd - After session ends

from teaagent.hooks import HookRegistry, permission_check_hook, PermissionMode

registry = HookRegistry()
registry.register_pre_hook(permission_check_hook(mode=PermissionMode.AUTO))

Context Compaction

Automatic context compression when token usage exceeds 75-92% (Claude Code traffic light zones):

Green (0-75%): Normal operation
Yellow (75-92%): User hints
Red (92%+): Auto-compaction triggered

teaagent agent preflight and teaagent agent daily expose a token_budget payload before any model call. The report estimates task, memory, context-pack, tool-metadata, recent-run replay, and output-reserve tokens, then labels the planned context as green/yellow/red when the model context window is known.

ACP (Agent Client Protocol)

IDE integration for VS Code, Zed, and JetBrains via JSON-RPC over stdio:

# Run as ACP server
teaagent acp serve

ACP enables TeaAgent to run inside ACP-compatible editors with full tool access.

5-Minute Walkthrough

Run the self-contained end-to-end example (no API keys needed):

python3 examples/full_agent_run.py

It demonstrates the full lifecycle:

Workspace tools — registers read_file, write_file, apply_patch, etc.
Audit + metrics — writes per-run JSONL audit log, collects counters/histograms.
Memory catalog — adds a workspace memory entry.
Budget + approval — caps iterations/tool-calls, enforces write-only permission mode.
Agent runner — a deterministic decide function emits two tool calls then finishes.
Run store — persists the completed run and lists it.
Audit replay — reads back every recorded event from the run log.
Metrics snapshot — prints final counter values.

For a real LLM-driven run:

teaagent agent run gpt "Summarize the tests" --permission-mode read-only

Development

# Run tests
pytest

# Run user-facing acceptance workflows
python3 -m pytest tests/acceptance

# Lint
ruff check .
ruff format --check .

# Type check
mypy teaagent/

See docs/cli.md for full CLI reference, scope docs for P0/P1/P2 feature delineation, and ADRs for architecture decisions.

Additional references:

Name		Name	Last commit message	Last commit date
Latest commit History 240 Commits
.github		.github
.opencode/skill		.opencode/skill
.well-known		.well-known
docs		docs
examples		examples
scripts		scripts
teaagent		teaagent
tests		tests
vscode		vscode
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENT.md		AGENT.md
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
ruff.toml		ruff.toml
setup.py		setup.py
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

TeaAgent

Golden path (first hour)

Daily use (after setup)

Start Here

1. Install

2. First Run

3. Permission Modes

4. Plan vs Write

5. Extensibility

6. Docs

Architecture

Install

Quick Start

Optional: Keychain Mode

Environment Variables

Features

Permission Modes

Plan Mode

Tool Governance

Agent Run

LSP Code Analysis (P0)

Streaming (live feedback)

MCP Server

MCP Filtering & Sampling

Skills System

Plugin System

Hook System

Context Compaction

ACP (Agent Client Protocol)

5-Minute Walkthrough

Development

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages