# tfcode

> ToothFairyAI's official coding agent

**Status**: 🟢 Foundation Ready | **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.

Based on [opencode](https://github.com/anomalyco/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](./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

```typescript
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)

```json
{
  "$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:

```json
{
  "$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.

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

**Don't have Python?** See our [Setup Guide](./docs/setup-guide.md) for detailed instructions.

### Install tfcode

```bash
# 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

```bash
# 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](./docs/setup-guide.md) for detailed step-by-step instructions.

---

## Quick Start

```bash
# 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

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

### Phase 2: Tool Sync ✅ COMPLETE

**Completed**:
- [x] Complete tf-sync Python module
  - [x] Tool sync implementation
  - [x] Tool metadata caching in tfcode
- [x] Implement tfcode CLI commands
  - [x] `tfcode validate` - credential validation
  - [x] `tfcode sync` - sync tools from TF workspace
  - [x] `tfcode tools list` - list synced tools
  - [x] `tfcode tools list --type mcp|skill|database|function`
  - [x] `tfcode tools credentials <name> --set/--show`
  - [x] `tfcode tools debug <name>`
- [x] Handle API functions with user credentials
- [x] 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**:
- [x] Implement tfcode CLI commands
  - [x] `tfcode validate`
  - [x] `tfcode sync`
  - [x] `tfcode tools list`
  - [x] `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:

1. **Fetch from mirror**
   ```bash
   git fetch mirror
   ```

2. **Merge into development**
   ```bash
   git merge mirror/dev
   ```

3. **Resolve any conflicts**
   - Should be minimal due to minimal branding approach
   - Only directory names and config paths differ

4. **Verify branding**
   ```bash
   ./scripts/rebrand.sh --check
   ```

5. **Push to origin**
   ```bash
   git push origin development
   ```

---

## Implementation Notes

### 2026-03-24: Foundation Complete

**Key Decisions**:

1. **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

2. **Fork Architecture**
   - Upstream: `github.com/anomalyco/opencode`
   - Mirror: `gitea.toothfairyai.com/GitHub/opencode` (auto-synced)
   - Development: `gitea.toothfairyai.com/ToothFairyAI/tf_code`

3. **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
- [Developer Portal](https://toothfairyai.com/developers)
- [API Documentation](https://apidocs.toothfairyai.com)
- [Functions/Tools](https://docs.toothfairyai.com/docs/Settings/functions)

### OpenCode (Upstream)
- [GitHub](https://github.com/anomalyco/opencode)
- [Website](https://opencode.ai)

### Downloads
- [tfcode CLI](https://toothfairyai.com/install/tfcode)
- [npm package](https://www.npmjs.com/package/tfcode)
- [PyPI package](https://pypi.org/project/tfcode-cli/)

---

## Credits

tfcode is based on [opencode](https://github.com/anomalyco/opencode) by [anomalyco](https://github.com/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*