tfcode

ToothFairyAI's official coding agent

Status: 🟡 Planning Phase | Last Updated: 2026-03-24

---

Product Overview

tfcode is ToothFairyAI's official AI coding agent - a terminal-based coding assistant that integrates seamlessly with your TF workspace tools, MCP servers, agent skills, and database connections.

---

Product Identity

Aspect	Details
Name	tfcode
Positioning	ToothFairyAI's official coding agent
Target Users	Existing TF customers
Config Compatibility	Supports opencode.json for migration

---

Key Features

Core Capabilities

• Terminal-based AI coding assistant
• File read/write/edit operations
• Bash command execution
• Code search (glob, grep)
• Multi-agent support (Tab switching)

ToothFairyAI Integration

• MCP Servers from TF workspace (isMCPServer)
• Agent Skills from TF workspace (isAgentSkill)
• Database Scripts from TF workspace (isDatabaseScript)
• API Functions from TF workspace (requestType)

---

Fork Management

This is a soft fork of the opencode project, managed via a mirror-based strategy.

Repo	Purpose
github.com/anomalyco/opencode	Upstream (official source)
gitea.toothfairyai.com/GitHub/opencode	Mirror (auto-synced)
gitea.toothfairyai.com/ToothFairyAI/tf_code	Development (this repo)

Sync Strategy: Per-release manual PR-based sync from mirror to dev repo.

See FORK_MANAGEMENT.md for full details.

---

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              tfcode                                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                         CORE ENGINE                                  │    │
│  │                                                                      │    │
│  │  • TUI (Terminal UI)                                                 │    │
│  │  • Agent orchestration                                               │    │
│  │  • Tool execution                                                    │    │
│  │  • File operations                                                   │    │
│  │  • Code search                                                       │    │
│  │                                                                      │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                    TOOTHFAIRYAI INTEGRATION                          │    │
│  │                                                                      │    │
│  │   TF WORKSPACE                     TFCODE                           │    │
│  │   ┌──────────────────┐            ┌──────────────────┐             │    │
│  │   │ Tools:           │            │ Synced Tools:    │             │    │
│  │   │                  │            │                  │             │    │
│  │   │ ┌──────────────┐ │            │ ┌──────────────┐ │             │    │
│  │   │ │ MCP Servers  │ │   SYNC     │ │ github-mcp   │ │             │    │
│  │   │ │ (isMCPServer)│ │  ──────▶   │ │ auth: proxy  │ │             │    │
│  │   │ └──────────────┘ │            │ └──────────────┘ │             │    │
│  │   │ ┌──────────────┐ │            │ ┌──────────────┐ │             │    │
│  │   │ │ Agent Skills │ │   SYNC     │ │ code-reviewer│ │             │    │
│  │   │ │(isAgentSkill)│ │  ──────▶   │ │ auth: proxy  │ │             │    │
│  │   │ └──────────────┘ │            │ └──────────────┘ │             │    │
│  │   │ ┌──────────────┐ │            │ ┌──────────────┐ │             │    │
│  │   │ │ DB Scripts   │ │   SYNC     │ │ postgres-main│ │             │    │
│  │   │ │(isDatabase)  │ │  ──────▶   │ │ auth: proxy  │ │             │    │
│  │   │ └──────────────┘ │            │ └──────────────┘ │             │    │
│  │   │ ┌──────────────┐ │            │ ┌──────────────┐ │             │    │
│  │   │ │ API Functions│ │   SYNC     │ │ weather_api  │ │             │    │
│  │   │ │(requestType)│ │  ──────▶   │ │ auth: user   │ │             │    │
│  │   │ └──────────────┘ │            │ └──────────────┘ │             │    │
│  │   └──────────────────┘            └──────────────────┘             │    │
│  │            │                               │                        │    │
│  │            ▼                               ▼                        │    │
│  │       CREDENTIALS                    TOOL CALLS                      │    │
│  │       (Stay in TF)                                                  │    │
│  │                                                                      │    │
│  │            ┌─────────────────────────────────────────────────────┐ │    │
│  │            │                                                       │ │    │
│  │            │   MCP/Skill/DB Tools         API Function Tools       │ │    │
│  │            │            │                         │                │ │    │
│  │            │            ▼                         ▼                │ │    │
│  │            │   ┌─────────────────┐     ┌─────────────────┐       │ │    │
│  │            │   │ TF Proxy        │     │ Direct HTTP      │       │ │    │
│  │            │   │ • Inject creds  │     │ • User api_key   │       │ │    │
│  │            │   │ • Route to tool │     │ • Config-based   │       │ │    │
│  │            │   └─────────────────┘     └─────────────────┘       │ │    │
│  │            │                                                       │ │    │
│  │            └─────────────────────────────────────────────────────┘ │    │
│  │                                                                      │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

Tool Types

From ToothFairyAI Workspace

Type	Flag/Field	Credential Handling
MCP Servers	isMCPServer: true	TF Proxy (secure)
Agent Skills	isAgentSkill: true	TF Proxy (secure)
Database Scripts	isDatabaseScript: true	TF Proxy (secure)
API Functions	requestType enum	User provides in config

requestType Values

enum FunctionRequestType {
  get = "get",
  post = "post",
  put = "put",
  delete = "delete",
  patch = "patch",
  custom = "custom",
  graphql_query = "graphql_query",
  graphql_mutation = "graphql_mutation"
}

---

Configuration

tfcode.json (Primary)

{
  "$schema": "https://toothfairyai.com/schemas/tfcode.json",
  
  "toothfairy": {
    "workspace_id": "{env:TF_WORKSPACE_ID}",
    "api_key": "{env:TF_API_KEY}",
    "region": "au"
  },
  
  "tools": {
    "github-mcp": {
      "type": "mcp_server",
      "isMCPServer": true,
      "auth_via": "tf_proxy"
    },
    
    "code-reviewer": {
      "type": "agent_skill",
      "isAgentSkill": true,
      "auth_via": "tf_proxy"
    },
    
    "postgres-main": {
      "type": "database_script",
      "isDatabaseScript": true,
      "auth_via": "tf_proxy"
    },
    
    "weather_api": {
      "type": "api_function",
      "requestType": "get",
      "url": "https://api.weatherapi.com/v1/current.json",
      "api_key": "{env:WEATHER_API_KEY}"
    }
  }
}

opencode.json (Migration Support)

For users migrating from opencode, tfcode supports the legacy schema:

{
  "$schema": "https://opencode.ai/config.json",
  
  "toothfairy": {
    "workspace_id": "{env:TF_WORKSPACE_ID}",
    "api_key": "{env:TF_API_KEY}",
    "region": "au"
  },
  
  "mcp": {
    "github-mcp": {
      "type": "remote",
      "url": "https://mcp.github.com",
      "auth_via": "tf_proxy"
    }
  }
}

tfcode automatically detects and converts opencode.json to tfcode.json on first run.

---

Installation

# Via curl (recommended)
curl -fsSL https://toothfairyai.com/install/tfcode | bash

# Via npm
npm install -g tfcode

# Via pip
pip install tfcode-cli

# Via brew
brew install toothfairyai/tap/tfcode

---

Quick Start

# Set environment variables
export TF_API_KEY="tf_live_xxx"
export TF_WORKSPACE_ID="your-workspace-uuid"

# Validate credentials
tfcode validate

# Sync tools from TF workspace
tfcode sync

# Start tfcode
tfcode

# Switch agents with Tab
# Use TF tools with @tool-name:operation
> @github-mcp:repo_list owner="myorg"
> @postgres-main:query sql="SELECT * FROM users"

---

CLI Commands

# Credential Management
tfcode validate                    # Test TF credentials
tfcode connect                     # Interactive credential setup

# Tool Sync
tfcode sync                        # Sync all tools from TF
tfcode sync --force                # Force re-sync
tfcode tools list                  # List synced tools
tfcode tools list --type mcp       # List MCP servers
tfcode tools list --type skill     # List agent skills
tfcode tools list --type database  # List DB scripts
tfcode tools list --type function  # List API functions

# API Function Credentials
tfcode tools credentials <name> --set    # Set API key
tfcode tools credentials <name> --show   # Show stored key

# Debug
tfcode tools debug <name>          # Debug tool connection
tfcode tools test <name>           # Test tool call

---

Implementation Phases

Phase 1: Rebrand & Foundation ⏳ IN PROGRESS

Tasks:

• Fork repository structure
• Rebrand opencode → tfcode
  • Replace all string references
  • Replace URLs (opencode.ai → toothfairyai.com)
  • Replace logos and branding assets
  • Update package name to tfcode
• Create new config schema (tfcode.json)
• Add opencode.json → tfcode.json migration
• Define tool type schema
  • isMCPServer detection
  • isAgentSkill detection
  • isDatabaseScript detection
  • requestType enum handling
• Implement credential validation
• Create TF SDK integration layer
• Multi-region support (AU, EU, US)

Phase 2: Tool Sync ⏳ IN PROGRESS

Tasks:

• Implement TF workspace tool listing via SDK
• Build tool type classifier
  • isMCPServer detection
  • isAgentSkill detection
  • isDatabaseScript detection
  • requestType enum handling
• Create tool metadata sync using SDK
• Handle API functions with user credentials
  • isAgentSkill detection
  • isDatabaseScript detection
  • requestType enum handling
• Create tool metadata sync
• Handle API functions with user credentials

Phase 3: TF Proxy Integration

Tasks:

• Build TF Proxy client
• Implement tool call routing
  • MCP/Skill/DB → TF Proxy
  • API Functions → Direct HTTP
• Add tool namespace (@tool-name:operation)
• Implement permission checks

Phase 4: CLI & UX

Tasks:

• Implement tfcode CLI commands
• Build interactive credential setup
• Add tool status reporting
• Create user-friendly error messages

Phase 5: Documentation & Release

Tasks:

• User documentation
• Migration guide (opencode → tfcode)
• Installation scripts
• Package publishing (npm, pip, brew)
• First release

---

Rebrand Checklist

Code References

• opencode → tfcode in all source files
• OPENCODE_ → TFCODE_ in environment variables
• opencode.json support (migration) + tfcode.json (primary)
• Package name: tfcode (npm, pip)

URLs & Branding

• opencode.ai → toothfairyai.com
• github.com/anomalyco/opencode → new repo
• Logo replacement
• Theme colors (toothfairyai palette)
• Command: opencode → tfcode

Config

• Schema URL: toothfairyai.com/schemas/tfcode.json
• Config directory: ~/.config/tfcode/
• Data directory: ~/.local/share/tfcode/
• Support opencode.json for migration

---

Implementation Notes

2026-03-24: Planning & Phase 1 Start

Product Decision:

• Name: tfcode
• Positioning: ToothFairyAI's official coding agent
• Target: Existing TF customers
• Config: tfcode.json primary, opencode.json supported for migration

Fork Management:

• Upstream: github.com/anomalyco/opencode
• Mirror: gitea.toothfairyai.com/GitHub/opencode (auto-synced)
• Development: gitea.toothfairyai.com/ToothFairyAI/tf_code (this repo)
• Sync Strategy: Per-release manual PR-based sync
• Rebrand Script: scripts/rebrand.sh reapplies branding after merges

Scope:

• Full rebrand of codebase
• Tool integration: MCP, Skills, Database, API Functions
• Credentials: TF Proxy for secure types, user-provided for API functions

Architecture:

• Core engine (TUI, agents, file ops)
• TF integration layer (tool sync, proxy routing)

Implementation Progress:

• README created as living document
• tfcode.json schema defined
• Project structure created (packages/tf-sync, packages/tf-mcp-bridge)
• Python SDK integration (using toothfairyai SDK for multi-region support)
• Tool sync module using SDK's agent_functions.list()
• Multi-region URL configuration (AU, EU, US)
• Fork management strategy documented (FORK_MANAGEMENT.md)
• Rebrand script created (scripts/rebrand.sh)
• TypeScript/Node.js bridge module
• MCP proxy client
• CLI commands

Key Technical Decisions:

• Use official ToothFairyAI Python SDK for all TF API interactions
• Multi-region support via Region enum and REGION_URLS config
• Tool types classified by: isMCPServer, isAgentSkill, isDatabaseScript, requestType
• Sync functions are synchronous (SDK handles async internally)

---

Resources

ToothFairyAI

• Developer Portal
• API Documentation
• Functions/Tools

Downloads

• tfcode CLI
• npm package
• PyPI package

---

License

MIT License

---

Living document - Updated: 2026-03-24