ToothFairyAI_Public/tf_code
1
0
Fork 0
mirror of https://gitea.toothfairyai.com/ToothFairyAI/tf_code.git synced 2026-03-29 21:33:54 +00:00
Code Issues Packages Projects Releases Wiki Activity
tf_code/README.md
Gab abdfa7330e feat: initialize tfcode project structure 
- Add README.md as living documentation
- Add tfcode.json schema and config template
- Add FORK_MANAGEMENT.md with mirror-based fork strategy
- Add scripts/rebrand.sh for reapplying branding after upstream merges
- Add packages/tf-sync Python module using official ToothFairyAI SDK
- Add packages/tf-mcp-bridge TypeScript module (stub)
- Multi-region support (AU, EU, US)
- Tool sync: MCP servers, Agent Skills, Database Scripts, API Functions
2026-03-24 13:02:06 +11:00

452 lines
17 KiB
Markdown
Raw Blame History

# 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*
Reference in New Issue View Git Blame Copy Permalink