# 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](./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

```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.

---

## Installation

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

```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: Rebrand & Foundation ⏳ IN PROGRESS

**Tasks**:
- [x] 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`
- [x] Create new config schema (`tfcode.json`)
- [ ] Add opencode.json → tfcode.json migration
- [x] Define tool type schema
  - [x] `isMCPServer` detection
  - [x] `isAgentSkill` detection
  - [x] `isDatabaseScript` detection
  - [x] `requestType` enum handling
- [x] Implement credential validation
- [x] Create TF SDK integration layer
- [x] Multi-region support (AU, EU, US)

### Phase 2: Tool Sync ⏳ IN PROGRESS

**Tasks**:
- [x] Implement TF workspace tool listing via SDK
- [x] Build tool type classifier
  - [x] `isMCPServer` detection
  - [x] `isAgentSkill` detection
  - [x] `isDatabaseScript` detection
  - [x] `requestType` enum handling
- [x] 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**:
- [x] README created as living document
- [x] tfcode.json schema defined
- [x] Project structure created (packages/tf-sync, packages/tf-mcp-bridge)
- [x] Python SDK integration (using toothfairyai SDK for multi-region support)
- [x] Tool sync module using SDK's agent_functions.list()
- [x] Multi-region URL configuration (AU, EU, US)
- [x] Fork management strategy documented (FORK_MANAGEMENT.md)
- [x] 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](https://toothfairyai.com/developers)
- [API Documentation](https://apidocs.toothfairyai.com)
- [Functions/Tools](https://docs.toothfairyai.com/docs/Settings/functions)

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

---

## License

MIT License

---

*Living document - Updated: 2026-03-24*