figaro: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Figaro is a NATS-based orchestration system for managing Claude agent workers running in containerized desktop environments. Workers execute browser automation tasks via the claude-agent-sdk, with live desktop streaming through Apache Guacamole (guacd + guacamole-common-js). A supervisor agent handles task optimization and delegation. A channel-agnostic gateway service routes messages to/from external channels (Telegram, etc.) for human-in-the-loop interactions.

All services communicate via NATS (pub/sub + JetStream for durable task events). The UI connects to NATS via WebSocket (nats.ws) for both real-time events and mutations (request/reply). HTTP endpoints are minimal: GET /api/config (NATS URL discovery), GET /api/guacamole/token (encrypted connection tokens), and WS /guacamole/webSocket (Guacamole WebSocket tunnel via guapy).

Long-Running Task Design

This system is built for tasks that run for minutes to hours. Browser automation with Claude agents is inherently long-running — a single task may involve navigating dozens of pages, filling forms, waiting for page loads, and interacting with complex web applications. All timeouts, subscriptions, and communication patterns must account for this.

Key principles:

• Never use fixed wall-clock timeouts for task execution. Use inactivity-based timeouts that reset on worker progress. A task actively streaming messages is healthy regardless of how long it's been running.
• NATS request/reply timeouts are for API calls, not task lifecycles. The request() timeout (default 10s, UI 30s) covers orchestrator round-trips, NOT how long a task takes. Task progress is tracked via JetStream subscriptions, not request/reply.
• JetStream provides durable delivery. Task events (messages, completion, errors) go through JetStream so they survive reconnections. Core NATS is only for ephemeral operations (registration, heartbeats, API calls).
• Supervisor delegation is blocking but progress-aware. waitForDelegation() in supervisor/tools.ts subscribes to figaro.task.{id}.message and resets its inactivity timer on every worker message. The DELEGATION_INACTIVITY_TIMEOUT (600s) is a silence detector, not a task duration limit.
• Help requests have their own timeouts. Human-in-the-loop requests wait independently (default 300s) and don't affect the task execution timeout.
• Use Core NATS subscriptions for waiting on task events in the worker/supervisor. JetStream ephemeral push consumers (js.subscribe() in nats.js v2) are unreliable — they can fail silently or throw during setup, causing tools like delegate_to_worker to return immediately instead of blocking. Since JetStream publishes also deliver to Core NATS subscribers on the same subject, use nc.subscribe() instead (same pattern as HelpRequestHandler). Both are ephemeral and behave identically for DeliverPolicy.New use cases.