openagent/CLAUDE.md

Open Agent – Project Guide

Open Agent is a managed control plane for OpenCode-based agents. The backend does not run model inference or autonomous logic; it delegates execution to an OpenCode server and focuses on orchestration, telemetry, and workspace/library management.

Architecture Summary

• Backend (Rust/Axum): mission orchestration, workspace/container management, MCP registry, Library sync.
• OpenCode Client: src/opencode/ and src/agents/opencode.rs (thin wrapper).
• Dashboards: dashboard/ (Next.js) and ios_dashboard/ (SwiftUI).

Core Concepts

• Library: Git-backed config repo (skills, commands, agents, tools, rules, MCPs). src/library/. The default template is at github.com/Th0rgal/openagent-library-template.
• Workspaces: Host or container environments with their own skills, tools, and plugins. src/workspace.rs manages workspace lifecycle and syncs skills/tools to .opencode/.
• Missions: Agent selection + workspace + conversation. Execution is delegated to OpenCode and streamed to the UI.

Scoping Model

• Global: Auth, providers, MCPs (run on HOST machine), agents, commands, rules
• Per-Workspace: Skills, tools, plugins/hooks, installed software (container only), file isolation
• Per-Mission: Agent selection, workspace selection, conversation history

MCPs are global because they run as child processes on the host, not inside containers. Skills and tools are synced to workspace .opencode/skill/ and .opencode/tool/ directories.

Design Guardrails

• Do not reintroduce autonomous agent logic (budgeting, task splitting, verification, model selection). OpenCode handles execution.
• Keep the backend a thin orchestrator: Start Mission → Stream Events → Store Logs.
• Avoid embedding provider-specific logic in the backend. Provider auth is managed via OpenCode config + dashboard flows.

Common Entry Points

• src/api/routes.rs – API routing and server startup.
• src/api/control.rs – mission control session, SSE streaming.
• src/api/mission_runner.rs – per-mission execution loop.
• src/workspace.rs – workspace lifecycle + OpenCode config generation.
• src/opencode/ – OpenCode HTTP + SSE client.

Local Dev

# Backend
export OPENCODE_BASE_URL="http://127.0.0.1:4096"
cargo run --release

# Dashboard
cd dashboard
bun install
bun dev

Frontend workflow: the Next.js dashboard runs locally and points at the remote backend in Settings. No remote deploy needed for frontend changes.

Testing

Backend testing must happen on Linux (desktop MCP). Deploy as root on 95.216.112.253 with SSH key cursor. Always use debug builds for speed (never release). Frontend stays local.

# from macOS
rsync -az --delete \
  --exclude target --exclude .git --exclude dashboard/node_modules \
  /Users/thomas/conductor/workspaces/open_agent/vaduz-v1/ \
  root@95.216.112.253:/opt/open_agent/vaduz-v1/

# on host
cd /opt/open_agent/vaduz-v1
cargo build --bin open_agent
# restart services when needed:
# - OpenCode server: `opencode.service`
# - Open Agent backend: `open_agent.service`

Notes to avoid common deploy pitfalls:

• Always include the SSH key in rsync: -e "ssh -i ~/.ssh/cursor" (otherwise auth will fail in non-interactive shells).
• The host uses rustup; build with source /root/.cargo/env so the newer toolchain is on PATH.

Debugging Missions

Missions are persisted in a SQLite database with full event logging, enabling detailed post-mortem analysis.

Database location: ~/.openagent/missions/missions.db (or missions-dev.db in dev mode)

Retrieve events via API:

GET /api/control/missions/{mission_id}/events

Query parameters:

• types=<type1>,<type2> – filter by event type
• limit=<n> – max events to return
• offset=<n> – pagination offset

Event types captured:

• user_message – user inputs
• thinking – agent reasoning tokens
• tool_call – tool invocations (name + input)
• tool_result – tool outputs
• assistant_message – agent responses
• mission_status_changed – status transitions
• error – execution errors

Example: Retrieve tool calls for a mission:

curl "http://localhost:3000/api/control/missions/<mission_id>/events?types=tool_call,tool_result" \
  -H "Authorization: Bearer <token>"

Code entry points: src/api/mission_store/ handles persistence; src/api/control.rs exposes the events endpoint.

Notes

• OpenCode config files are generated per workspace; do not keep static opencode.json in the repo.
• Container workspaces require root and Ubuntu/Debian tooling (systemd-nspawn).