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`
`loop`	Create, read, update, and delete loop definitions	`loop`
`tfcode_config`	Read and update config sections (reviewer, model_swap, loops)	`tfcode_config`
`todowrite`	Manage todo lists during sessions	`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`
`render`	Screenshot a page with headless Chrome (vision models only)	`render`
`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`

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

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 read and update top-level config sections without editing JSON manually. It also supports deleting a section.

Sections

Section	Config Key	Description
`reviewer`	`reviewer`	Reviewer model configuration
`model_swap`	`model_swap`	Model swap configuration
`loops_settings`	`loops`	Top-level loops settings (compaction, guards, auto)

note

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

Actions

Action	Description
`read`	Read a config section's current value
`update`	Update a config section (deep-merges existing)
`delete`	Remove a config section from config

Examples

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.

Vision Rendering (`render`)

The render tool screenshots a URL or local HTML file with headless Chrome and attaches the image, letting the agent visually inspect UI work. It is only exposed when the active model supports vision (e.g. models with supportsVision enabled in your workspace).

render("https://localhost:3000")   →  screenshot attached to context

Requirements and tuning:

Chrome/Chromium must be installed (standard macOS/Linux/Windows locations are probed automatically).
Set TF_CHROME_PATH to point at a specific binary.
Window size defaults to 1280×800; pages get a virtual-time budget to settle before capture.

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​

Vision Rendering (render)​

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

Vision Rendering (`render`)

Output Limits

Disable Tools

Per-Agent Overrides