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.

Based on opencode - an excellent AI coding tool. We credit and thank the opencode team for their outstanding work.

Product Identity

Aspect	Details
Name	tfcode
Positioning	ToothFairyAI's official coding agent
Target Users	Existing TF customers
Config Files	`tfcode.json` (primary), `opencode.json` (migration support)
Config Directory	`.tfcode/`

Key Features

Core Capabilities (from opencode)

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

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.

Branding Strategy

Minimal Branding Approach

We use a minimal branding approach to ensure clean upstream merges:

Aspect	Branding	Reason
CLI binary	`tfcode`	User-facing
Package name	`tfcode`	User-facing
Config directory	`.tfcode/`	User-facing
Internal code	`opencode`	Easy merges
Workspace packages	`@opencode-ai/*`	Low priority
Config file names	`opencode.json`	Low priority

What This Means

Changed (user-facing):

Binary: packages/tfcode/bin/tfcode
Package: packages/tfcode/package.json → name: tfcode
Config: .tfcode/ directory

Unchanged (internal):

All code references to "opencode" in source files
@opencode-ai/* workspace package names
Internal flags like OPENCODE_*
Provider IDs, model references

Result: When merging upstream changes, only directory names and a few config paths differ. Git can handle merges automatically.

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.

Project Structure

tf_code/
├── packages/
│   ├── tfcode/              # Core engine (renamed from opencode)
│   │   ├── bin/tfcode       # CLI binary
│   │   ├── src/             # All source code
│   │   └── package.json     # name: tfcode
│   ├── tf-sync/             # Python TF SDK sync layer
│   │   └── src/tf_sync/
│   │       ├── config.py    # TFConfig, multi-region URLs
│   │       ├── tools.py     # Tool sync using SDK
│   │       ├── mcp.py       # MCP server sync
│   │       └── agents.py    # Agent sync (future)
│   ├── tf-mcp-bridge/       # TypeScript MCP proxy bridge
│   └── tf-config-loader/    # Config loader (stub)
├── .tfcode/                 # Config directory
├── scripts/
│   └── rebrand.sh           # Reapply branding after upstream merge
├── tfcode.json              # Config template
├── schemas/
│   └── tfcode.schema.json   # JSON schema
├── README.md                # This file
└── FORK_MANAGEMENT.md       # Fork sync strategy

Installation

Requirements

Python 3.10+ is required on your machine for ToothFairyAI integration.

# Check Python version
python3 --version  # Should be 3.10 or higher

Don't have Python? See our Setup Guide for detailed instructions.

Install tfcode

# Via npm (recommended)
npm install -g tfcode

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

# Via pip
pip install tfcode-cli

# Via brew
brew install toothfairyai/tap/tfcode

The postinstall script will automatically install the ToothFairyAI Python SDK.

First-Time Setup

# Show quick start guide
tfcode quickstart

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

# Validate connection
tfcode validate

# Sync tools
tfcode sync

See Setup Guide for detailed step-by-step instructions.

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: Foundation ✅ COMPLETE

Completed:

Fork repository structure
Merge opencode codebase from mirror
Apply minimal tfcode branding
- Rename packages/opencode → packages/tfcode
- Rename binary opencode → tfcode
- Rename config directory .opencode/ → .tfcode/
- Update package.json name to tfcode
- Update config path references
- Keep internal code as "opencode" for easy upstream merges
Create tfcode.json schema
Define tool type schema
- isMCPServer detection
- isAgentSkill detection
- isDatabaseScript detection
- requestType enum handling
Implement credential validation (in tf-sync)
Create TF SDK integration layer
Multi-region support (AU, EU, US)
Document fork management strategy
Push to development branch

Phase 2: Tool Sync ✅ COMPLETE

Completed:

Complete tf-sync Python module
- Tool sync implementation
- Tool metadata caching in tfcode
Implement tfcode CLI commands
- tfcode validate - credential validation
- tfcode sync - sync tools from TF workspace
- tfcode tools list - list synced tools
- tfcode tools list --type mcp|skill|database|function
- tfcode tools credentials <name> --set/--show
- tfcode tools debug <name>
Handle API functions with user credentials
Tool cache persistence (~/.tfcode/tools.json)

Pending (Phase 3):

Test tool sync with real TF workspace
Build tf-mcp-bridge TypeScript module
MCP proxy client implementation
Tool refresh/reload

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

Completed:

Implement tfcode CLI commands
- tfcode validate
- tfcode sync
- tfcode tools list
- tfcode tools credentials

Tasks:

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

Upstream Sync Process

When a new opencode release is available:

Fetch from mirror
```
git fetch mirror
```
Merge into development
```
git merge mirror/dev
```
Resolve any conflicts
- Should be minimal due to minimal branding approach
- Only directory names and config paths differ
Verify branding
```
./scripts/rebrand.sh --check
```
Push to origin
```
git push origin development
```

Implementation Notes

2026-03-24: Foundation Complete

Key Decisions:

Minimal Branding Strategy
- Initially tried bulk rename (1141 files modified)
- Realized this would cause massive merge conflicts
- Reverted to minimal branding (608 files, mostly renames)
- Only changed user-facing surfaces, kept internal code as "opencode"
- Result: Clean upstream merges
Fork Architecture
- Upstream: github.com/anomalyco/opencode
- Mirror: gitea.toothfairyai.com/GitHub/opencode (auto-synced)
- Development: gitea.toothfairyai.com/ToothFairyAI/tf_code
Tool Integration Approach
- Use official ToothFairyAI Python SDK
- MCP/Skills/DB tools: Credentials stay in TF, route via TF Proxy
- API Functions: User provides credentials in config

Current State:

a8b73fd75 refactor: apply minimal tfcode branding
8bcbd40e9 merge: initial merge from opencode mirror
abdfa7330 feat: initialize tfcode project structure

What's Ready:

✅ Clean codebase with minimal branding
✅ TF SDK integration layer (Python)
✅ Tool sync module complete
✅ CLI commands implemented (validate, sync, tools)
✅ Multi-region support
✅ Config schema defined
✅ Documentation structure

What's Next:

Test with real TF workspace
Build tf-mcp-bridge TypeScript module
Implement TF Proxy client for tool call routing

Resources

ToothFairyAI

OpenCode (Upstream)

Downloads

Credits

tfcode is based on opencode by anomalyco.

We thank the opencode team for creating an excellent AI coding tool and for making it open source.

License

MIT License

Living document - Updated: 2026-03-24

Languages

TypeScript 54%

MDX 41.3%

CSS 3.2%

Rust 0.5%

JavaScript 0.3%

Other 0.6%