🖥️ TF Code - AI Coding Agent CLI

TF Code is ToothFairyAI's official AI coding agent - a powerful command-line interface that brings AI-powered coding assistance directly to your terminal. It provides full access to ToothFairyAI models, tools, and MCP (Model Context Protocol) servers, enabling you to code with AI assistance in any development environment.

Quick Start

1. Install

npm install -g @toothfairyai/tfcode

2. Configure Credentials

export TF_WORKSPACE_ID="your-workspace-id"
export TF_API_KEY="your-api-key"
export TF_REGION="dev"  # Options: dev, au, eu, us

3. Validate

tfcode providers validate

4. Start Coding

tfcode

Or run a single task:

tfcode run "Explain this codebase"

Configuration

Credentials Setup

TF Code is available to all subscription tiers (Starter, Professional, Business, and Enterprise). To find your credentials, go to Admin → TFCode & API Integration in the ToothFairyAI dashboard. Note that the API Integration section (for programmatic API access beyond TF Code) is available only for Business and Enterprise plans.

There are three ways to configure your credentials:

Option A: Environment Variables (Recommended)

export TF_WORKSPACE_ID="your-workspace-id"
export TF_API_KEY="your-api-key"
export TF_REGION="au"  # Options: au, eu, us

Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.) for persistence.

Option B: Interactive Setup

Run the guided setup command:

tfcode setup

This will prompt for:

• Workspace ID
• API Key
• Region

Credentials are stored in ~/.local/share/opencode/.tfcode/credentials.json.

Option C: Project-Level Configuration

Create .tfcode/opencode.json in your project root:

{
  "provider": {
    "toothfairyai": {
      "type": "api",
      "key": "your-api-key",
      "workspaceId": "your-workspace-id",
      "region": "au"
    }
  }
}

Validate Credentials

After configuration, verify your credentials:

tfcode providers validate

Expected output:

✓ toothfairyai credentials validated
  Workspace: your-workspace-id
  Region: dev
  Models available: 20

Configuration Files

credentials.json

Location: ~/.local/share/opencode/.tfcode/credentials.json

{
  "workspace_id": "your-workspace-id",
  "api_key": "your-api-key",
  "region": "au"
}

Project Configuration

Location: .tfcode/opencode.json (in project root)

{
  "provider": {
    "toothfairyai": {
      "type": "api",
      "key": "your-api-key",
      "workspaceId": "your-workspace-id",
      "region": "au"
    }
  },
  "model": "mystica",
  "agent": "build"
}

Regions

ToothFairyAI has multiple regional endpoints:

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

Choose the region closest to you for best performance.

Overview

Key Features

1. Multi-Model Support: Use any ToothFairyAI model directly from your terminal
2. Tool Integration: Automatic access to ToothFairyAI MCP tools for enhanced capabilities
3. File Operations: Read, write, edit, and search files with AI assistance
4. Code Execution: Execute bash commands and code snippets
5. Git Integration: Automatic git tracking and commit assistance
6. Session Management: Persistent sessions with conversation history
7. Skill System: Load specialised skills for domain-specific assistance

What's Included

• ToothFairyAI Models: Access to all ToothFairyAI serverless models (Mystica, GLM-5, Claude, GPT, etc.)
• ToothFairyAI Tools: Built-in integration with 100+ ToothFairyAI MCP tools
• Teal Branding: Custom ToothFairyAI visual identity
• Centralised Logging: All logs in one place for debugging
• Tool Calling: Full support for MCP tool execution

Installation

Requirements

• Node.js: Version 18 or higher
• Python (optional): Version 3.10+ for ToothFairyAI integration features

Install via npm

npm install -g @toothfairyai/tfcode

Supported Platforms

TF Code is available for all major platforms:

Platform	Architecture	Variant
macOS	Apple Silicon (M1/M2)	darwin-arm64
macOS	Intel	darwin-x64
macOS	Intel (no AVX2)	darwin-x64-baseline
Linux	ARM64	linux-arm64
Linux	ARM64 (Alpine)	linux-arm64-musl
Linux	x64	linux-x64
Linux	x64 (no AVX2)	linux-x64-baseline
Linux	x64 (Alpine)	linux-x64-musl
Linux	x64 (Alpine, no AVX2)	linux-x64-baseline-musl
Windows	ARM64	windows-arm64
Windows	x64	windows-x64
Windows	x64 (no AVX2)	windows-x64-baseline

The correct binary is automatically selected during installation.

Usage

Start Interactive Session

tfcode

This opens an interactive chat interface where you can:

• Ask coding questions
• Request file modifications
• Execute commands
• Use MCP tools

Run Single Commands

Execute a single task and exit:

tfcode run "Explain this codebase"

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

Specify Model

Choose a specific model:

tfcode run "Write a function to parse CSV" --model toothfairyai/mystica

tfcode run "Debug this issue" --model toothfairyai/z/glm-5

Available Models

All ToothFairyAI open-source models are available:

Model ID	Description
sorcerer_15	General purpose coding model
mystica_15	Faster variant of Mystica
z/glm-5	GLM-5 for SOTA coding and agentic capabilities
kimi-k2.5	Kimi 2.5 for advanced reasoning
minimax-2.5	Minimax 2.5 for complex tasks

Integrations

TF Code provides comprehensive integrations with multiple AI providers, MCP servers, and the ToothFairyAI ecosystem.

AI Provider Integrations

TF Code supports multiple AI providers, allowing you to use the best model for your task:

Provider	Integration Type	Features
ToothFairyAI	Native API	Full access to Mystica, GLM-5, Kimi, Minimax, Sorcerer models
OpenAI	API Key	GPT-4, GPT-4o, and other OpenAI models
Google	API Key	Gemini Pro and Gemini Flash models
Anthropic	API Key	Claude 3.5 Sonnet, Claude 3 Opus models
Ollama Cloud	API Key	Self-hosted Ollama models via cloud endpoint

Configuring Multiple Providers

{
  "provider": {
    "toothfairyai": {
      "type": "api",
      "key": "your-api-key",
      "workspaceId": "your-workspace-id",
      "region": "au"
    },
    "anthropic": {
      "type": "api",
      "key": "your-anthropic-key"
    },
    "openai": {
      "type": "api",
      "key": "your-openai-key"
    }
  }
}

Using Different Providers

# Use ToothFairyAI (default)
tfcode run "Explain this code"

# Use Anthropic Claude
tfcode run "Review this PR" --model anthropic/claude-4-5-sonnet-20241022

# Use OpenAI GPT-4
tfcode run "Write tests" --model openai/gpt-4o

MCP (Model Context Protocol) Integration

TF Code provides full MCP support with both remote and local server integration:

Remote MCP Servers

Connect to ToothFairyAI's MCP server for 100+ tools:

• Agent Management: Create, update, delete, list agents
• Function Management: Create agent functions, configure APIs, manage authentication
• Knowledge Base: Create/search documents, manage folders and entities
• Workspace Operations: Manage members, channels, view logs, track costs

# MCP tools are automatically available
tfcode run "List all agents in my workspace"

Local MCP Servers

Add local MCP servers via stdio transport:

# List configured MCP servers
tfcode mcp list

# Add a local MCP server
tfcode mcp add /path/to/server --name my-server

OAuth-Enabled MCP Servers

Connect to OAuth-protected MCP servers:

# Initiate OAuth flow
tfcode mcp connect https://mcp.example.com --oauth

# Browser opens for authentication, then returns to CLI

ToothFairyAI Ecosystem Integration

TF Code provides deep integration with the ToothFairyAI platform:

Workspace Management

• Multi-workspace support: Switch between workspaces
• Regional endpoints: dev, au, eu, us regions
• Credential management: Secure storage of API keys

Model Access

All ToothFairyAI models are available:

Model	Best For
mystica	General purpose coding
mystica_15	Fast coding tasks
z/glm-5	SOTA coding and agentic capabilities
kimi-k2.5	Advanced reasoning
minimax-2.5	Complex tasks
sorcerer	Specialised applications

Tool Integration

TF Code automatically connects to ToothFairyAI's MCP server, providing access to 100+ tools:

tfcode run "Create a new agent called 'DataProcessor' with retriever mode"

The AI will call toothfairy_create_toothfairy_agent with the appropriate parameters.

Git Integration

TF Code integrates with your Git workflow:

• Automatic git tracking: Changes are tracked automatically
• Commit assistance: AI helps write commit messages
• Branch awareness: Understands current branch context
• PR integration: Can help create pull requests

tfcode run "Commit these changes with a descriptive message"

File System Integration

Full file system access with safety controls:

• Read: View any file content
• Write: Create new files
• Edit: Modify existing files with precise string replacement
• Search: Find files and content with glob/grep patterns
• Execute: Run bash commands in a controlled environment

IDE Integration

TF Code works alongside your existing tools:

• VS Code: Use alongside VS Code Copilot or standalone
• JetBrains: Complements JetBrains AI Assistant
• Vim/Neovim: Perfect for terminal-centric workflows
• Emacs: Integrates with your Emacs environment

ToothFairyAI Features

TF Code provides deep integration with ToothFairyAI's core features: Skills, Prompts, Agents, and Hooks.

Skills

Skills are reusable behavioral instructions that guide agents through specific tasks with step-by-step workflows, validation rules, and examples.

Available Skills

TF Code can load and use these ToothFairyAI skills:

Skill	Description
create-agent	Create agents with mode-specific validation (coder requires has_code=True)
update-prompt	Update prompt templates
create-function	Create agent functions/tools with JSON Schema validation
setup-authorisation	Set up API credentials for external integrations
create-scheduled-job	Create scheduled jobs with cron validation
create-document	Create knowledge base documents
create-member	Add workspace members
create-connection	Create AI model connections

Using Skills

# Skills are automatically loaded when needed
tfcode run "Create a new coder agent called 'PythonExpert'"

# The AI will use the create-agent skill with proper validation
# It ensures has_code=True for coder mode, validates temperature range, etc.

Skill Validation Example

The create-agent skill enforces critical constraints:

• Coder agents: MUST have has_code=True, CANNOT have agenticRAG=True
• Voice agents: CANNOT have agenticRAG=True (latency impact)
• Temperature: Must be between 0.001 and 1.0
• JSON output: Requires valid JSON Schema structure

Prompts

Custom prompt templates for consistent agent interactions with dynamic placeholders.

Key Features

• Reusable templates: Save frequently-used instructions
• Dynamic placeholders: Use {} for runtime content injection
• Agent assignment: Prompts are explicitly assigned to specific agents
• Scheduled jobs: Combine with Jobs for automated workflows

Example Prompt Template

Generate a weekly report for {department} including:
- {metrics} analysis
- Key insights and recommendations
- Comparison with previous period

Using Prompts

# Prompts are selected when creating scheduled jobs
tfcode run "Create a scheduled job that runs the 'WeeklyReport' prompt every Monday"

Prompts + Jobs Integration

Combine prompts with scheduled jobs for automation:

1. Daily summaries: Run a prompt every morning at 9 AM
2. Weekly reports: Generate consistent reports every Monday
3. Monitoring alerts: Check conditions and alert on issues

Agents

AI assistants with specialised capabilities and modes.

Agent Types

Type	Mode	Best For	Constraints
Assistant	retriever	RAG, knowledge search	Can enable agenticRAG, charting
Programmer	coder	Code generation, debugging	REQUIRES has_code=True, NO agenticRAG
Operator	chatter	Creative conversations	agenticRAG must be false
Orchestrator	planner	Multi-step workflows, delegation	Coordinates other agents
Voice Agent	voice	Voice interactions	NO agenticRAG (latency)

Creating Agents via TF Code

# Create a retriever agent
tfcode run "Create a retriever agent called 'SupportBot' with access to the 'support' topic"

# Create a coder agent (has_code=True is required)
tfcode run "Create a coder agent called 'PythonDev' with code execution enabled"

# The AI validates constraints automatically via skills

Agent Models

All ToothFairyAI models are available for agents:

Model	Best For
mystica	General purpose coding
mystica_15	Fast coding tasks
z/glm-5	SOTA coding and agentic capabilities
kimi-k2.5	Advanced reasoning
minimax-2.5	Complex tasks
sorcerer	Specialised applications

Structured Output

Enable JSON output for reliable parsing:

tfcode run "Create an agent with structured JSON output for API responses"

The skill ensures valid JSON Schema:

{
  "enable_json_output": true,
  "json_output_structure": {
    "type": "object",
    "properties": {
      "answer": { "type": "string" },
      "confidence": { "type": "number" },
      "sources": { "type": "array", "items": { "type": "string" } }
    }
  }
}

Hooks

Predefined code execution environments for Programmer and Operator agents with Docker images and Python code snippets.

Default Environment

Hooks come with 40+ pre-installed libraries:

Category	Libraries
Data Processing	numpy, pandas, scikit-learn, statsmodels
Visualization	matplotlib, seaborn, plotly, folium
Document Processing	PyPDF2, python-docx, openpyxl, python-pptx
Image Processing	Pillow, pytesseract
Database	psycopg2, mysql-connector-python, pyodbc
Web/HTTP	requests, beautifulsoup4, urllib3

Execution Limits

• Memory: 10 GB
• Runtime: 15 minutes
• Storage: 10 GB

Hook Features

Feature	Description
Secrets Injection	Inject authentication credentials securely
Static Scripts	Execute predefined code without modification
Python Tools	Encapsulate hooks as reusable tools with {{parameter}} injection
Knowledge Hub Files	Reference up to 10 Python files from Knowledge Hub
Environment Variables	Access tf_message_id, tf_workspace_id, tf_chat_id

Using Hooks

# Hooks are automatically selected based on the task
tfcode run "Analyze the CSV files in /data and create a visualization"

# The agent will use an appropriate hook with pandas, matplotlib, etc.

Static Script Example

# Hook code for file processing
import os
from pathlib import Path

workspace_id = os.environ.get('tf_workspace_id')
input_dir = f"/tmp/{workspace_id}/input"
output_dir = f"/tmp/{workspace_id}/output"

# Process files...

Functions (Tools)

Create agent functions for external API calls with full authentication support.

Authentication Types

Type	Use Case
none	Public APIs
bearer	Static bearer tokens
apikey	API key authentication
oauth	OAuth2 client credentials flow

Creating Functions

# Create a function to call an external API
tfcode run "Create a function called 'get_weather' that calls https://api.weather.com/current"

# The AI uses the create-function skill with JSON Schema validation

Function Parameters (JSON Schema)

{
  "type": "object",
  "properties": {
    "location": { "type": "string", "description": "City name" },
    "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
  },
  "required": ["location"]
}

Scheduled Jobs

Automate agent execution with flexible scheduling.

Schedule Frequencies

Frequency	Description
MINUTES	Run every N minutes
HOURLY	Run every N hours
DAILY	Run daily at specific time
WEEKLY	Run on specific day of week
MONTHLY	Run on specific day of month
CUSTOM	Custom cron expression

Creating Jobs

# Create a daily job
tfcode run "Create a job that runs the 'DailyReport' agent every day at 9 AM"

# Create a custom cron job
tfcode run "Create a job with cron expression '*/15 * * * *' for every 15 minutes"

Job Configuration

{
  "name": "Daily Report Generator",
  "agent_id": "agent-123",
  "custom_prompt_id": "prompt-456",
  "schedule": {
    "frequency": "DAILY",
    "hour": 9,
    "minute": 0
  },
  "notification_config": {
    "on_failure": true,
    "email_recipients": ["admin@example.com"]
  },
  "retry_config": {
    "max_retries": 3,
    "retry_interval": 300
  }
}

Commands Reference

Command	Description
tfcode	Start interactive session
tfcode run <prompt>	Execute single task
tfcode setup	Configure credentials interactively
tfcode providers list	List available providers
tfcode providers validate	Validate credentials
tfcode mcp list	List MCP tools
tfcode --help	Show all commands
tfcode --version	Show version

Logging

All logs are centralised in one location:

# View logs
tail -f ~/.local/share/opencode/log/dev.log

# Filter for specific service
tail -f ~/.local/share/opencode/log/dev.log | grep "provider.toothfairyai"

Log Levels

• DEBUG: Detailed information for debugging
• INFO: General operational information
• WARN: Warning messages
• ERROR: Error messages

Run with debug logging:

tfcode --log-level DEBUG

Troubleshooting

Credentials Not Working

# Verify credentials
tfcode providers validate

# Re-run setup
tfcode setup

MCP Tools Not Loading

1. Check credentials are valid
2. Verify network connectivity to MCP server
3. Check logs for connection errors:

   grep "mcp.*error" ~/.local/share/opencode/log/dev.log

Binary Not Found

If installation fails, try:

# Clean install
npm uninstall -g @toothfairyai/tfcode
npm cache clean --force
npm install -g @toothfairyai/tfcode

Permission Errors

On Linux/macOS:

sudo chown -R $(whoami) ~/.npm-local

Updating

Update to the latest version:

npm update -g @toothfairyai/tfcode

Uninstalling

npm uninstall -g @toothfairyai/tfcode

# Optionally remove configuration
rm -rf ~/.local/share/opencode/.tfcode

Best Practices

1. Use Project Configuration: Add .tfcode/opencode.json to each project for consistent settings
2. Validate Credentials: Run tfcode providers validate after setup
3. Check Logs: Use --log-level DEBUG when troubleshooting
4. Choose Right Model: Use mystica for general tasks, z/glm-5 for complex agentic work
5. Leverage MCP Tools: Let the AI use ToothFairyAI tools for workspace operations

Background

TF Code is built on OpenCode, an open-source AI coding agent, customised for ToothFairyAI with enhanced integration, ToothFairyAI agentic AI, and seamless access to the ToothFairyAI ecosystem of models and tools.

Resources

• Documentation: https://toothfairyai.com/developers/tfcode
• NPM Package: https://www.npmjs.com/package/@toothfairyai/tfcode
• ToothFairyAI Dashboard: https://app.toothfairyai.com

Support

For issues and feature requests:

• Email: support@toothfairyai.com
• Documentation: https://docs.toothfairyai.com