ToothFairyAI_Public/tf_code
1
0
Fork 0
mirror of https://gitea.toothfairyai.com/ToothFairyAI/tf_code.git synced 2026-03-30 05:43:55 +00:00
Code Issues Packages Projects Releases Wiki Activity
tf_code/README.md
Gab 4380efd658 feat: tfcode beta
2026-03-24 14:01:32 +11:00

586 lines
21 KiB
Markdown
Raw Blame History

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