UFO Documentation
Everything you need to turn your computer into an AI-piloted workspace.
What is UFO?
UFO is a thin communication layer over Claude Code. It lets you dispatch AI agents from a chat interface -- web, mobile, any browser -- while your machine at home does the actual work.
Think of it as a remote control for your development environment. You talk, agents execute. Your existing Claude Code setup -- CLAUDE.md, custom agents, skills -- works without modification.
Why not Telegram or Discord?
Generic chat apps aren't built for AI workflows. No real-time token streaming, no agent management, no file context, no scheduled tasks. UFO is purpose-built for human-AI collaboration -- every design decision came from 6+ months of daily production use.
Key principles
- Your machine, your compute. UFO runs agents on your hardware. We don't host compute.
- Your data stays local. All conversations and files live on your computer. We can't read them.
- Ride with Anthropic. Since UFO is built on Claude Code, every Anthropic improvement automatically makes UFO better.
Installation
Prerequisites
- macOS (Linux support planned)
- Node.js 18+
- Claude Code CLI installed and configured
Install
curl -fsSL ufo.alienz.ooo/install.sh | sh
Configure
ufo install
The installer will walk you through connecting to your Claude Code setup. It detects your existing configuration and uses it as-is.
Run as a service
ufo service install
This registers UFO as a launchd service on macOS. It starts automatically on boot and restarts on crash. Your agents stay online 24/7.
Quick Start
Once UFO is running, open ufo.alienz.ooo from any device and log in.
curl -fsSL ufo.alienz.ooo/install.sh | sh
# 2. Configure
ufo install
# 3. Run as service
ufo service install
# 4. Open from any device
open https://ufo.alienz.ooo
Send your first message
Create a channel and type a message. UFO forwards it to Claude Code running on your machine. Watch the response stream back in real-time.
Architecture
UFO has a deliberately simple architecture. There is no cloud compute. Your machine does everything.
[ Your Browser / Phone ]
|
| WebSocket (messages only)
v
[ UFO Server (relay) ]
|
| Bot API
v
[ Your Computer ]
[ Claude Code + UFO Daemon ]
The server only relays messages. It never sees your code, files, or conversation content. All AI processing happens on your machine.
Components
- UFO Daemon -- runs on your machine, manages Claude Code sessions per channel
- UFO Server -- lightweight relay, handles auth and WebSocket connections
- UFO Client -- web/mobile interface for sending messages and viewing responses
Channels
Channels are the core organizational unit in UFO. Each channel is an independent conversation with its own Claude Code session and context.
One channel, one context
Each channel maintains its own Claude Code session. This means separate conversation history, separate file context, separate working directory. You can have one channel for backend work, another for frontend, another for DevOps -- all running in parallel on your machine.
Channel badges
Badges show the current state of a channel at a glance. For example, which AI model is active, whether it's in a special mode, or if a long task is running.
Agents
Claude Code supports custom agents -- specialized AI personas with specific roles. UFO inherits all of them. Your agents defined in .claude/agents/ work automatically.
Built-in agent examples
- developer -- writes code, fixes bugs, builds and deploys
- designer -- generates UI code using Gemini CLI
- qa-tester -- tests games and apps against sprint contracts
- scout -- market research and trend analysis
These are just examples. You define your own agents based on your workflow.
Claude Code Integration
UFO doesn't replace Claude Code. It extends it with remote access and multi-channel management.
What works automatically
- CLAUDE.md -- your project instructions are loaded as-is
- .claude/agents/ -- custom agents work without changes
- .claude/skills/ -- all skills are available
- .claude/settings.json -- permissions and hooks respected
What UFO adds
- Remote access from any device with a browser
- Multiple simultaneous Claude Code sessions (channels)
- WebSocket-based real-time streaming
- Channel state persistence across reconnections
- Scheduled job execution
No migration needed. If Claude Code works on your machine, UFO works too. Just install and go.
Mobile & Remote Access
UFO's interface is designed to work on phones and tablets. Open ufo.alienz.ooo on your phone, log in, and you have full control over your development machine.
Use cases
- Review code changes while commuting
- Deploy a hotfix from your phone
- Check build status from a cafe
- Dispatch agents while traveling light
Real-Time Streaming
AI responses stream token-by-token through WebSockets. You see the agent thinking and working in real-time, just like watching Claude Code in your terminal.
What streams
- AI text output -- token by token
- Tool calls -- see which files the agent reads, edits, or creates
- Terminal output -- build results, test output, deploy logs
Scheduled Jobs
Set up recurring tasks that run automatically. Your agents work 24/7, even when you're not watching.
Schedule: */5 * * * *
Prompt: Check if there are any failed builds in the pipeline
Common patterns
- Hourly health checks on production services
- Daily report generation
- Periodic dependency updates
- Automated testing on schedule
Multi-AI Support
While Claude Code is the primary engine, UFO can dispatch tasks to other AI providers when it makes sense.
Examples
- Gemini -- for UI generation (via gemini -p CLI)
- GPT -- for analysis tasks via API
- Local models -- for privacy-sensitive operations
- Specialized models -- FLUX for images, Whisper for audio
Your agents decide which AI to use based on the task. You configure the APIs, and agents call them when needed.
Custom Skills
Skills are reusable prompt templates that extend what agents can do. Define them once, invoke them from any channel.
.claude/skills/
deploy/
SKILL.md # name, description, instructions
test/
SKILL.md
review/
SKILL.md
Skills are automatically detected by Claude Code and available in all channels. No UFO-specific configuration needed.
Harness Mode
Harness mode activates a Generator-Evaluator pattern for high-quality output. When you say "make it properly" or "team effort", UFO chains multiple agents in sequence.
Game development harness
|
[creator] <--> [qa-tester] # Code QA loop (max 3 rounds)
|
[designer] <--> [ui-evaluator] # UI quality loop (max 5 rounds)
|
v
Done
Web service harness
|
[designer] <--> [ui-evaluator] # UI quality loop
|
v
Done
Each stage has clear pass/fail criteria. Failed stages loop back with feedback until quality is met or max retries are exhausted.
Privacy & Data
UFO was designed from day one to minimize data on our servers. Here's exactly what happens with your data.
What stays on your computer
- All conversation content
- All files and code
- Claude Code sessions and history
- API keys and credentials
- Agent configurations
What passes through the server
- Text messages (relayed, not stored permanently)
- WebSocket connection metadata
- Authentication tokens
We can't see your code. We can't read your conversations. Honestly, we don't want to -- keeping servers minimal keeps our costs down. Your hardware does the work.
Why this architecture?
It's not just about privacy. Using your compute means zero usage-based cloud bills. The server only relays messages -- it does almost nothing. That's why UFO can stay free.