Harnesses
Agent-native apps run inside a harness — a host environment that provides the AI agent and displays the app UI side by side.
CLI Harness (Local)
- Open source, ships with
@agent-native/harness-cli - Runs locally — xterm.js terminal on the left, your app iframe on the right
- Supports multiple AI coding CLIs — switch between them from the settings panel
- Auto-installs missing CLIs on first use
- Per-CLI launch flags and settings, persisted to localStorage
- Auto-detects when the agent finishes generating and notifies the app
- Great for local use — individuals, development, and testing
Quick start:
# In your agent-native monorepo
pnpm dev:harnessSupported CLIs
| CLI | Command | Key Flags |
|---|---|---|
| Claude Code | claude | --dangerously-skip-permissions, --resume, --verbose |
| Codex | codex | --full-auto, --quiet |
| Gemini CLI | gemini | --sandbox |
| OpenCode | opencode | — |
| Builder.io | builder | — |
Switch between CLIs at any time from the settings panel. The harness restarts the terminal with the selected CLI and loads its saved launch options.
Builder.io Cloud Harness
- Runs in the cloud
- Real-time collaboration — multiple users can watch/interact simultaneously
- Visual editing, roles and permissions
- Parallel agent execution for faster iteration
- Great for team use
Feature Comparison
| Feature | CLI Harness | Builder.io Cloud Harness |
|---|---|---|
| Local development | Yes | Yes |
| Cloud/remote | No | Yes |
| Multi-CLI support | Yes (5 CLIs) | Yes |
| Real-time collaboration | No | Yes |
| Visual editing | No | Yes |
| Parallel agents | No | Yes |
| Agent chat bridge | Yes | Yes |
| File watcher (SSE) | Yes | Yes |
| Script system | Yes | Yes |
| Open source | Yes | No |
How It Works
Both harnesses support the same core agent-native protocol. The framework provides type-safe APIs so you never deal with raw messaging:
- Agent chat — use
sendToAgentChat()to send messages to the agent - Generation state — use
useAgentChatGenerating()to track when the agent is running - File watching — SSE endpoint keeps UI in sync when the agent modifies files
- Script system —
pnpm script <name>dispatches to callable scripts
Your app code is identical regardless of which harness or CLI you use.