🖥️ 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 requires your ToothFairyAI credentials to access models and tools. There are three ways to configure them:

Option A: Environment Variables (Recommended)

export TF_WORKSPACE_ID="your-workspace-id"
export TF_API_KEY="your-api-key"
export TF_REGION="dev"  # Options: dev, 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": "dev"
    }
  }
}

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": "dev"
}

Project Configuration

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

{
  "provider": {
    "toothfairyai": {
      "type": "api",
      "key": "your-api-key",
      "workspaceId": "your-workspace-id",
      "region": "dev"
    }
  },
  "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

Multi-Model Support: Use any ToothFairyAI model directly from your terminal
Tool Integration: Automatic access to ToothFairyAI MCP tools for enhanced capabilities
File Operations: Read, write, edit, and search files with AI assistance
Code Execution: Execute bash commands and code snippets
Git Integration: Automatic git tracking and commit assistance
Session Management: Persistent sessions with conversation history
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
`mystica`	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
`sorcerer`	Sorcerer model for specialised applications

MCP Tool Integration

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

Agent Management

Create, update, delete agents
List and search agents
Configure agent settings

Function Management

Create agent functions (tools)
Configure external API integrations
Manage authentication

Knowledge Base

Create and search documents
Manage folders and entities
Build custom knowledge

Workspace Operations

Manage members and channels
View request logs
Track usage and costs

Example: Using MCP Tools

tfcode run "List all agents in my workspace"

The AI will automatically call toothfairy_list_toothfairy_agents and present the results.

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

The AI will call toothfairy_create_toothfairy_agent with the appropriate parameters.

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

Check credentials are valid
Verify network connectivity to MCP server

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

Use Project Configuration: Add .tfcode/opencode.json to each project for consistent settings
Validate Credentials: Run tfcode providers validate after setup
Check Logs: Use --log-level DEBUG when troubleshooting
Choose Right Model: Use mystica for general tasks, z/glm-5 for complex agentic work
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

🖥️ TF Code - AI Coding Agent CLI

Quick Start​

1. Install​

2. Configure Credentials​

3. Validate​

4. Start Coding​

Configuration​

Credentials Setup​

Option A: Environment Variables (Recommended)​

Option B: Interactive Setup​

Option C: Project-Level Configuration​

Validate Credentials​

Configuration Files​

credentials.json​

Project Configuration​

Regions​

Overview​

Key Features​

What's Included​

Installation​

Requirements​

Install via npm​

Supported Platforms​

Usage​

Start Interactive Session​

Run Single Commands​

Specify Model​

Available Models​

MCP Tool Integration​

Agent Management​

Function Management​

Knowledge Base​

Workspace Operations​

Example: Using MCP Tools​

Commands Reference​

Logging​

Log Levels​

Troubleshooting​

Credentials Not Working​

MCP Tools Not Loading​

Binary Not Found​

Permission Errors​

Updating​

Uninstalling​

Best Practices​

Background​

Resources​

Support​