TF Code

ToothFairyAI's AI coding agent — a command-line interface that brings AI-powered coding assistance to your terminal with deep ToothFairyAI workspace integration.

Agents

TF Code ships with three built-in agents:

| Agent | Purpose | Key Ability | | --------------- | ----------------------------- | ----------------------------------------------------------- | | Build | Execute and implement | Full read/write access, the default agent | | Plan | Explore and plan | Read-only analysis, writes plans to .tfcode/plans/ | | TF Engineer | Manage ToothFairyAI workspace | Exclusive access to live MCP tools for workspace operations |

Switch between them at any time with Tab or the --agent flag.

Prerequisites

• Node.js 18+
• A modern terminal emulator (WezTerm, Alacritty, Kitty, Ghostty recommended)
• ToothFairyAI API credentials (from Admin → TFCode & API Integration)

Install

npm install -g @toothfairyai/tfcode

Verify:

tfcode --version

Configure

Run the interactive setup to create a profile:

tfcode setup

This prompts for profile name, workspace ID, API key, and region. Alternatively, set environment variables:

export TF_WORKSPACE_ID="your-workspace-id"
export TF_API_KEY="your-api-key"
export TF_REGION="au"

Validate:

tfcode validate

Usage

Interactive session

tfcode

Single command

tfcode run "Explain this codebase"

Plan first, then build

Use Tab to switch to Plan mode, describe what you want, then switch back to Build to implement.

1. Plan — describe the feature, review the plan
2. Build — switch back and ask it to implement

Workspace management

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

Undo changes

/undo

Profiles

Profiles store multiple sets of ToothFairyAI credentials so you can switch between workspaces instantly.

Create

tfcode setup

Non-interactive:

tfcode setup --profile dev --workspace-id dev-ws-456 --api-key dev-key-xxx --region dev --name dev

Switch

tfcode profile prod

Use in commands

tfcode -p prod run "Deploy to production"
TF_PROFILE=prod tfcode run "Force prod workspace"

Regions

| Region | Base URL | Streaming URL | | ------ | ------------------------ | ------------------------- | | dev | ai.toothfairylab.link | ais.toothfairylab.link | | au | ai.toothfairyai.com | ais.toothfairyai.com | | eu | ai.eu.toothfairyai.com | ais.eu.toothfairyai.com | | us | ai.us.toothfairyai.com | ais.us.toothfairyai.com |

Environment Variables

| Variable | Description | | ------------------------- | ----------------------------------------------- | | TF_WORKSPACE_ID | ToothFairyAI workspace ID | | TF_API_KEY | ToothFairyAI API key | | TF_REGION | ToothFairyAI region: dev, au, eu, us | | TF_PROFILE | Profile name to use (overrides default profile) | | TFCODE_SERVER_PASSWORD | HTTP basic auth password for server mode | | TFCODE_SERVER_USERNAME | HTTP basic auth username (default: tfcode) | | OPENCODE_CONFIG | Path to custom config file | | OPENCODE_CONFIG_CONTENT | Inline config content (highest priority) |

CLI Commands

Top-level

| Command | Description | | --------------------- | ----------------------------------- | | tfcode | Start interactive session | | tfcode run <prompt> | Execute a single task and exit | | tfcode serve | Start headless HTTP server | | tfcode web | Start server and open web interface | | tfcode attach <url> | Attach TUI to a running server |

Setup & credentials

| Command | Description | | -------------------------- | ------------------------------------------------------ | | tfcode setup | Interactive credential setup (creates a profile) | | tfcode validate | Validate credentials (--profile <name> for specific) | | tfcode profile | Show current profile and list all | | tfcode profile <name> | Switch to a different profile | | tfcode sync | Sync workspace tools metadata | | tfcode providers list | List available providers | | tfcode models [provider] | List available models (optional provider filter) | | tfcode models --verbose | List models with metadata | | tfcode models --refresh | Refresh the models cache |

MCP

| Command | Description | | ------------------- | ---------------------------------- | | tfcode mcp list | List MCP servers and tools | | tfcode mcp add | Add a local MCP server | | tfcode mcp auth | Authenticate with OAuth MCP server | | tfcode mcp logout | Logout from MCP server |

Chat commands (interactive)

| Command | Description | | ------------------------- | --------------------------------------- | | /compact [instructions] | Compact context with preservation hints | | /help | Show available commands | | /undo | Undo last changes |

Documentation

Full documentation at https://docs.toothfairyai.com/tfcode/intro

License

MIT