Agents

TF Code ships with three built-in agents. Switch between them with Tab in the TUI or the --agent flag in CLI mode.

Build

The default agent. Full read/write access for executing and implementing.

tfcode run "Add error handling to src/api.ts"

• Full read/write access to files
• Can execute bash commands
• Uses all built-in tools (Bash, Read, Edit, Write, Glob, Grep, WebFetch, etc.)
• Has access to synced workspace content (coder agents, agent skills) but NOT live MCP tools
• Can switch into Plan mode via plan_enter

Action	Permission
Read files	Allowed
Write/edit files	Allowed
Bash commands	Allowed
Read .env files	Ask (requires confirmation)

Plan

Read-only planning agent. Explores your codebase and creates a plan without making changes.

tfcode run --agent plan "Analyze the auth flow and propose improvements"

• Read-only — cannot edit, write, or modify any files
• Writes plans to .tfcode/plans/*.md (the only write exception)
• Can switch to Build via plan_exit
• Injects a system prompt enforcing strict read-only behavior

Action	Permission
Read files	Allowed
Write/edit files	Denied (except .tfcode/plans/)
Bash commands	Allowed (read-only usage)

Workflow: Plan → Build

1. Plan explores and creates a structured plan in .tfcode/plans/
2. When ready, Plan offers to switch to Build
3. Build receives the plan context and begins implementation

TF Engineer

The ToothFairyAI workspace agent. Automatically connected to the ToothFairyAI MCP server with exclusive access to live workspace management tools.

tfcode run --agent "TF Engineer" "Create a retriever agent called SupportBot"
tfcode run --agent "TF Engineer" "Search documents about refund policy"

• Exclusive access to ToothFairyAI MCP tools — no other agent can use them
• Can still read local files and use built-in tools
• Edit and bash commands require confirmation (ask permission)
• Always asks for confirmation before destructive operations
• Connected via SSE to https://mcp.{region}.toothfairyai.com/sse

Action	Permission
Read files	Allowed
Write/edit files	Ask (requires confirmation)
Bash commands	Ask (requires confirmation)
TF MCP tools	Allowed (exclusive)

MCP Connection

TF Engineer automatically connects using your profile credentials. Credentials are injected as an x-api-key header and auto-filled parameters — the model never sees your API key, workspace ID, or region. They are stripped from the tool schema and added server-side.

MCP Tool Categories

Category	Tools	Auth Required
Agent Management	Create, get, update, delete, list, search agents	Yes
Agent Functions/Tools	Create, get, update, delete, list functions	Yes
Authorisations	Create, get, update, delete, list auth configs	Yes
Secrets	Create, delete secrets (AWS Secrets Manager)	Yes
Documents / Knowledge Base	Create, get, update, delete, list, search documents	Yes
Entities	Create, get, update, delete, list, search entities	Yes
Folders	Create, get, update, delete, list, get folder tree	Yes
Chats	Create, get, list, delete chats; list messages; send messages	Yes
Prompts	Create, get, update, delete, list prompt templates	Yes
Members	Create, get, update, delete workspace members	Yes
Channels	Create, get, update, delete, list channels	Yes
Connections	Create, get, delete model connections	Yes
Benchmarks	Create, get, update, delete, list benchmarks	Yes
Benchmark Runs	Run, get, list, cancel, wait for benchmark runs	Yes
Hooks	Create, get, update, delete, list hooks	Yes
Scheduled Jobs	Create, get, update, delete, list scheduled jobs	Yes
Sites	Get, update, delete, list sites	Yes
Fine-Tuning	List trainable models, start/cancel training, generate datasets	Yes
Training Data	Generate training data from chats or files	Yes
Documentation	Search docs, search API endpoints, get agent creation guide	No
Release Notes	List, get, search release notes	No
Skills & Guides	List skills, get skill guide, recommend skill for operation	No
Credential Validation	Validate API key + workspace ID + region	Yes
Billing	Get monthly usage/costs	Yes
Embeddings	Create text embeddings	Yes

Comparison

Feature	Build	Plan	TF Engineer
Purpose	Execute & implement	Explore & plan	Manage ToothFairyAI workspace
File editing	Allowed	Denied	Ask (requires confirmation)
Bash commands	Allowed	Allowed	Ask (requires confirmation)
TF MCP tools	No access	No access	Exclusive access
Default agent	Yes	No	No
Custom system prompt	No	Yes (read-only enforcement)	Yes (MCP-first behavior)

Set Default Agent

{
  "default_agent": "build"
}

Reviewer

The Reviewer lets you attach a stronger AI model to your agents so they can get a second opinion before making decisions. When enabled, agents gain access to a reviewer tool they can call for expert analysis.

{
  "reviewer": {
    "model": "anthropic/claude-opus-4-8",
    "enabled_for": ["build", "tf_engineer", "plan"],
    "temperature": 0.3,
    "max_tokens": 8192
  }
}

The model field uses the same provider/model format — use any provider you have configured. The reviewer is a one-shot call — it doesn't run tools, doesn't loop, and doesn't modify anything.

Focus Areas

Focus	When to use
architecture	Design decisions, structure, patterns
security	Vulnerabilities, auth issues, data exposure
performance	Speed, memory, scaling concerns
correctness	Logic errors, edge cases, test coverage
general (default)	Broad review across all areas

Permissions

The reviewer permission defaults to allow for built-in agents. Override:

{
  "agent": {
    "build": {
      "permission": {
        "reviewer": "ask"
      }
    }
  }
}

To disable for a specific agent, remove it from enabled_for. To disable entirely, remove the reviewer section from config.