Tools

Tools allow the LLM to perform actions in your codebase. TF Code comes with built-in tools and supports MCP servers and custom tools via plugins.

Configure

Use the permission field to control tool behavior — allow, deny, or require approval:

{
  "permission": {
    "edit": "allow",
    "bash": "ask",
    "webfetch": "deny"
  }
}

Wildcard patterns:

{
  "permission": {
    "mymcp_*": "ask"
  }
}

Built-in Tools

Tool	Description	Permission Key
`bash`	Execute shell commands	`bash`
`edit`	Modify files using exact string replacements	`edit`
`write`	Create new files or overwrite existing	`edit`
`read`	Read file contents	`read`
`grep`	Search file contents using regex	`grep`
`glob`	Find files by pattern matching	`glob`
`apply_patch`	Apply patches to files	`edit`
`skill`	Load a skill and return its content	`skill`
`skill_manage`	Create, read, update, and delete local skills	`skill`
`agent`	Create, read, update, and delete local agents	`agent`
`task`	Launch a subagent to handle a multi-step task	`task`
`loop`	Create, read, update, and delete loop definitions	`loop`
`loop_next`	Advance or loop back to a step in the active loop workflow	`loop`
`loop_done`	Stop the active loop workflow early	`loop`
`tfcode_config`	Describe, read, update, and delete any tfcode.json config section	`tfcode_config`
`todowrite`	Manage todo lists during sessions	`todowrite`
`todoread`	Read the current todo list	`todowrite`
`webfetch`	Fetch web content	`webfetch`
`websearch`	Search the web for information	`websearch`
`question`	Ask the user questions during execution	`question`
`lsp`	Interact with LSP servers (experimental)	`lsp`
`tf_tooling`	Call ToothFairyAI workspace tools by writing JavaScript	`tf_tooling`
`browser`	Drive the integrated browser: navigate, screenshot, console, network, DOM (vision models)	`browser`
`computer`	Control the local OS GUI: mouse, keyboard, screen capture	`computer`
`screenshot`	See the user's screen on demand (read-only; vision models)	`screenshot`
`voice_update`	Speak a short message out loud (TTS); requires voice mode	`voice_update`
`plan_enter`	Enter plan mode — read-only except the plan file	`plan`
`plan_exit`	Exit plan mode once the plan is ready for implementation	`plan`
`recall`	Retrieve old tool outputs and messages from earlier in the session	`recall`
`reviewer`	Ask a stronger reviewer model for expert analysis (requires `reviewer` config)	`reviewer`
`model_swap`	Swap to a different model mid-session (requires `model_swap` config)	`model_swap`
`escalate`	Temporarily upgrade to a stronger model for a hard problem (requires `escalate` config)	`escalate`
`kanban`	Manage the local kanban board — boards, lanes, columns, tasks, comments	`kanban`
`channel`	Send and read messages in project channels (TF Manage exclusive)	`channel`
`insight`	Post curated insights (blockers, decisions, follow-ups, progress) to channels	`insight`
`routine`	Create and manage scheduled routines (TF Manage exclusive)	`routine`
`plugin_recommend`	List and recommend built-in plugins to enable	`plugin_recommend`
`tfdesign`	Delegate design work to TF Design (only while the tfdesign CLI is installed)	`tfdesign`
`image_generation`	Generate an image via ToothFairyAI and save it to `images/`	`image_generation`

Note: write and apply_patch are controlled by the edit permission key.

Some tools are conditional: reviewer, model_swap, and escalate only exist when their config section is set; browser only for vision-capable models; channel and routine only for the TF Manage agent (or perk-inherited); tfdesign only while the tfdesign CLI is installed.

Agent Management

The agent tool lets agents create, read, update, and delete local agents stored as markdown files in .tfcode/agent/<name>.md. TF-synced agents (from ToothFairyAI) and native agents are read-only and cannot be modified.

Actions

Action	Description
`list`	List all agents (local, native, and TF-synced) with source labels
`read`	Read a specific agent's full config (frontmatter + prompt)
`create`	Create a new agent markdown file (refuses to overwrite)
`update`	Update an existing local agent's frontmatter and/or prompt
`delete`	Delete a local agent file (refuses for native or TF-synced)

Parameters

Parameter	Type	Required for	Description
`action`	`list \| read \| create \| update \| delete`	all	The CRUD action to perform
`name`	string	read/update/delete	Agent name
`description`	string	—	When to use this agent
`mode`	`subagent \| primary \| all`	—	Agent visibility — `subagent` = hidden from switcher, invocable via `@` and `task`; `primary` = switchable agent; `all` = both. See Agents → Agent modes.
`model`	string	—	Model in `provider/model` format
`hidden`	boolean	—	Hide from @ autocomplete (subagents only)
`color`	string	—	Hex color or theme name
`steps`	number	—	Max agentic iterations
`permission`	object	—	Permission rules (see Permissions)
`temperature`	number	—	Temperature for the agent's model
`top_p`	number	—	Top_p for the agent's model
`variant`	string	—	Default model variant for this agent
`prompt`	string	—	The agent's system prompt (markdown body)

Examples

Create a translator subagent:

{
  "action": "create",
  "name": "translator",
  "description": "Translate content for a specified locale",
  "mode": "subagent",
  "prompt": "You are a professional translator specializing in technical documentation."
}

Update an agent's temperature:

{
  "action": "update",
  "name": "translator",
  "temperature": 0.7
}

note

The model parameter is optional. When omitted, the agent inherits the session's active model — dynamically resolved from your ToothFairyAI workspace. Only set model if the agent should always use a specific model. Use /models in the TUI to discover available models.

List all agents:

{ "action": "list" }

Delete an agent:

{ "action": "delete", "name": "translator" }

Skill Management

The skill_manage tool lets agents create, read, update, and delete local skills stored as SKILL.md files in .tfcode/skill/<name>/SKILL.md. TF-synced skills (from ToothFairyAI, locations starting with tf://) are read-only.

Actions

Same five actions as the agent tool: list, read, create, update, delete.

Parameters

Parameter	Type	Required for	Description
`action`	`list \| read \| create \| update \| delete`	all	The CRUD action to perform
`name`	string	read/update/delete	Skill name
`description`	string	create	Skill description
`content`	string	—	The skill content (markdown body)

Examples

Create a deployment skill:

{
  "action": "create",
  "name": "deploy",
  "description": "Deployment workflows and runbooks",
  "content": "# Deploy Skill\n\nSteps to deploy to production..."
}

Loop Management

The loop tool lets agents create, read, update, and delete loop definitions in the project config. See Loops for full loop documentation.

Actions

Same five actions: list, read, create, update, delete.

Parameters

Parameter	Type	Required for	Description
`action`	`list \| read \| create \| update \| delete`	all	The CRUD action to perform
`name`	string	read/update/delete	Loop name
`description`	string	—	Loop description
`steps`	array of step objects	create	Ordered steps for the loop

Each step object has: name (required), prompt (required), agent, skill, review, model — see Loops → Step.

Example

{
  "action": "create",
  "name": "fix-bug",
  "description": "Read, build, test, review",
  "steps": [
    {
      "name": "read",
      "prompt": "Read and understand the task.",
      "agent": "general"
    },
    { "name": "build", "prompt": "Implement the change." },
    { "name": "test", "prompt": "Run tests. If failing, loop back to build." },
    { "name": "review", "prompt": "Review for correctness.", "review": true }
  ]
}

Config Management

The tfcode_config tool lets agents discover, read, update, and delete any top-level tfcode.json section without editing JSON manually. The section list and per-section schemas are generated live from the config schema, so it always reflects what the current version supports — no stale guesses.

Sections

Any top-level tfcode.json key is a valid section: settings, reviewer, model_swap, escalate, loops, kanban, handoff, tfdesign, office, policies, self_improve_skills, perks, and more. Call describe with no section to list every available section and its description.

note

Loop definitions are managed via the loop tool, not tfcode_config. The loops section here covers only top-level settings (compaction_threshold, compaction_model, max_step_repeats, max_transitions, auto) — definitions are merged, not replaced.

Actions

Action	Description
`describe`	No section → catalog of every section; with a section → full schema + current value
`read`	Read a config section's current value
`update`	Update a config section — schema-aware merge (deep-merges object fields, replaces scalars/arrays)
`delete`	Remove a config section from config

Examples

List every config section the current version supports:

{ "action": "describe" }

Get the full schema and current value for the web app settings:

{ "action": "describe", "section": "settings" }

Read reviewer config:

{ "action": "read", "section": "reviewer" }

Enable model swap with a candidate list:

{
  "action": "update",
  "section": "model_swap",
  "value": {
    "enabled_for": ["build"],
    "models": [
      {
        "id": "toothfairyai/glm-5p2",
        "instruction": "Use for deep reasoning"
      },
      {
        "id": "toothfairyai/glm-5p2",
        "instruction": "Use for quick lookups"
      }
    ]
  }
}

Configure loops compaction settings:

{
  "action": "update",
  "section": "loops_settings",
  "value": {
    "compaction_threshold": 0.6,
    "max_step_repeats": 5
  }
}

Workspace Tooling (`tf_tooling`)

The tf_tooling tool lets agents call your synced ToothFairyAI workspace tools — API functions, agent skills, and database scripts — by writing JavaScript instead of one tool call at a time. This is the fastest way to chain calls, poll, or reshape results.

Prerequisite: run tfcode sync so the tool catalog is cached locally.

How it works

The agent writes JavaScript that runs in a confined sandbox (no filesystem, network, or process access — only the tf namespace and plain JavaScript):

const projects = await tf.tools.get_kanban_projects();
const open = await tf.tools.get_tickets({
  status: "open",
  project: projects[0].id,
});
return open.filter((t) => t.priority === "high");

await tf.tools.<name>({...args}) — call a synced tool by its sanitized name
tf.list() — inspect available tools, types, and descriptions at runtime
The last expression is JSON-serialized back to the agent

Authentication

Credentials never enter the sandbox:

Tools executed by ToothFairyAI (tf_proxy) run through the workspace function core with workspace credentials — the sandbox only ever holds closures.
Tools that expect a user-provided key read it from an environment variable at call time (TF_TOOL_KEY__<TOOL_NAME>) and error with a clear message when unset.

note

mcp_server type workspace tools are not callable from tf_tooling yet — connect them as MCP servers instead.

Integrated Browser (`browser`)

The browser tool drives a shared Chromium session the agent can inspect and interact with — screenshots are a first-class output of every action. It is only exposed when the active model supports vision (e.g. models with supportsVision enabled in your workspace).

The agent uses one persistent browser with a single shared profile, so pages keep their state (cookies, logins) across actions:

browser({ action: "open", url: "http://localhost:3000" })  →  live screenshot + console/network feedback

Actions: open/navigate, screenshot, console, network, evaluate, click, fill, pick, diagnostics, close.

In the web app, every page the agent opens streams into the integrated browser panel — you can watch it work live and pick elements as context for your next prompt.

Requirements and tuning:

Chrome, Chromium, or Edge must be installed on the machine running the server (standard locations are probed automatically).
Set TF_CHROME_PATH to point at a specific binary.
Frames render with GPU compositing for sharp, true-to-browser output.

Output Limits

Tool outputs are bounded at two levels so one runaway call — or many parallel ones — can't flood the context:

Level	Limit	Behavior
Per output	2000 lines / 50KB	Full output saved to disk; the tool returns a preview plus a hint to `Grep`/`Read` the saved file
Per turn	200KB aggregate per assistant turn	Once spent, further outputs in the same turn collapse to small previews (full content still saved to disk)

The turn budget resets on every assistant turn. Tools that manage their own truncation are exempt from the per-output cap but still consume the turn budget.

Disable Tools

Globally:

{
  "tools": {
    "write": false,
    "bash": false
  }
}

Per-Agent Overrides

{
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Agent permissions override global settings.

Configure​

Built-in Tools​

Agent Management​

Actions​

Parameters​

Examples​

Skill Management​

Actions​

Parameters​

Examples​

Loop Management​

Actions​

Parameters​

Example​

Config Management​

Sections​

Actions​

Examples​

Workspace Tooling (tf_tooling)​

How it works​

Authentication​

Integrated Browser (browser)​

Output Limits​

Disable Tools​

Per-Agent Overrides​

Configure

Built-in Tools

Agent Management

Actions

Parameters

Examples

Skill Management

Actions

Parameters

Examples

Loop Management

Actions

Parameters

Example

Config Management

Sections

Actions

Examples

Workspace Tooling (`tf_tooling`)

How it works

Authentication

Integrated Browser (`browser`)

Output Limits

Disable Tools

Per-Agent Overrides