Agent Backends

Agent backends power Colony’s AI-driven development. We use HumanLayer’s hld daemon as the agent execution layer, which manages Claude Code sessions via JSON-RPC over Unix socket. The architecture supports future integrations with other agent backends.

Overview

Agent execution flow:

1. User triggers agent via Bloom UI or API
2. Mycelium connects to the hld daemon via Unix socket
3. hld launches a Claude Code session with the given instruction
4. Mycelium subscribes to session events (JSON-RPC streaming)
5. Events broadcast to Bloom via WebSocket
6. Bloom’s agent panel displays real-time updates

Agent execution is asynchronous and non-blocking. Multiple agents can run concurrently across different colonies, with cost guardrails limiting parallel sessions per brood.

HumanLayer hld Daemon

Colony delegates agent execution to HumanLayer’s hld daemon — a local process that manages Claude Code sessions with approval workflows, cost tracking, and session persistence.

Why hld instead of direct CLI:

• Session management — hld tracks sessions, enables continue/interrupt, and provides cost metadata
• Streaming events — Subscribe to real-time events without parsing stdout
• Cost tracking — Per-session cost reporting in USD
• Approval workflows — HumanLayer’s core feature for production agent use

Architecture

Colony (Mycelium)
    |
    | JSON-RPC over Unix socket
    v
hld daemon (~/.humanlayer/colony/daemon.sock)
    |
    | Manages Claude Code sessions
    v
Claude Code (API calls to Anthropic)

Colony runs its own isolated hld instance at ~/.humanlayer/colony/ so it doesn’t interfere with personal CodeLayer installations.

Configuration

Colony’s hld instance uses dedicated paths:

Setting	Default
Socket	~/.humanlayer/colony/daemon.sock
Database	~/.humanlayer/colony/daemon.db
HTTP Port	7779

Override via environment variables: HUMANLAYER_DAEMON_SOCKET, HUMANLAYER_DATABASE_PATH, HUMANLAYER_DAEMON_HTTP_PORT.

Start the daemon:

make hld-start
# or directly:
./scripts/run-hld.sh

Agent Lifecycle

When a colony receives an Instruct message:

1. Connect — Open Unix socket to hld daemon
2. Launch — Send launchSession JSON-RPC request with instruction, workdir, and config
3. Subscribe — Open a second connection and call Subscribe with include_history=true
4. Stream — Receive events in active mode until session completes
5. Finalize — Fetch session state for cost/turn metadata via getSessionState
6. Report — Send InstructComplete back to colony actor with the AgentResult

For continuing existing sessions, Colony sends continueSession with the parent session ID, enabling multi-turn conversations within a colony.

Agent States

State	Meaning
Idle	No active session
Working(instruction)	Agent executing a task
Done(result)	Session completed successfully
Failed(error)	Session failed

Cost Guardrails

Colony enforces cost limits per brood:

• Max 20 total sessions per brood lifetime
• Max 3 parallel sessions at any time per brood
• Queued colonies retry every 5 seconds when a slot opens

Agent Events

During execution, hld streams events that Colony broadcasts to Bloom via WebSocket.

text_delta

Agent text output (incremental).

{
  "type": "agent_event",
  "colony_id": "abc123",
  "event_type": "text_delta",
  "content": "I'll implement the login feature by...",
  "timestamp": 1708123456789
}

tool_use

Agent invoking a tool.

{
  "type": "agent_event",
  "colony_id": "abc123",
  "event_type": "tool_use",
  "content": "Read: /src/auth.ts",
  "timestamp": 1708123457123
}

tool_result

Tool execution result.

{
  "type": "agent_event",
  "colony_id": "abc123",
  "event_type": "tool_result",
  "content": "Read: export function authenticate...",
  "timestamp": 1708123457456
}

status

Session status change (e.g., completed, failed, interrupted).

{
  "type": "agent_event",
  "colony_id": "abc123",
  "event_type": "status",
  "content": "completed",
  "timestamp": 1708123460000
}

Agent Panel (Bloom)

Bloom’s agent preview tab (AgentPreview.tsx) displays streaming events in real-time.

Event Feed

Scrollable list with event-type styling:

• Text — Agent’s reasoning and output
• Tool Use — Tool name with truncated input summary
• Tool Result — Tool output with error indication
• Status — Session lifecycle transitions

Status Indicator

Badge showing current agent state:

State	Color	Meaning
Working	Green pulse	Agent executing
Done	Green solid	Session completed
Failed	Red	Execution failed
Idle	Gray	No active session

Auto-Scroll

The event feed auto-scrolls to keep the latest event visible. Scroll up to review history.

Brood System

Broods orchestrate multiple colonies toward a shared objective.

How It Works

1. Create brood with an objective, repo URL, and branch
2. Planning agent decomposes the objective into per-colony tasks
3. Colonies spawn with allocated port ranges and specific task assignments
4. Agents execute tasks in parallel (within cost guardrails)
5. State derives from colony agent statuses

Brood Creation

curl -X POST http://localhost:8000/api/broods \
  -H "Content-Type: application/json" \
  -d '{
    "name": "build-saas-mvp",
    "objective": "Build a SaaS MVP with auth, billing, and dashboard",
    "repo_url": "https://github.com/user/saas-app",
    "branch": "main",
    "model": "claude-sonnet-4-5"
  }'

Two Creation Modes

Simple mode — Provide just an objective. The planning agent decomposes it into tasks and spawns colonies automatically.

Advanced mode — Provide explicit colony specs with names, tasks, and service definitions. Skips the planning phase.

Execution Modes

Each colony task can use one of two execution modes:

• Agent execution — Claude Code session via hld (default)
• Script execution — Deterministic shell commands (no API cost)

Script execution is useful for setup steps like npm install or git checkout that don’t need AI.

Brood States

Pending -> Planning -> Running -> Completed
               |           |
            Failed      Failed

State is derived from constituent colony agent statuses:

• All agents Done -> Brood Completed
• Any agent Failed or colony Failed -> Brood Failed
• Any agent Working -> Brood Running

Inter-Colony Awareness

Colonies within a brood can share context via the awareness system. Events from sibling colonies (file changes, test results, errors) are logged and can be injected into agent prompts for coordination.

Agent Configuration

Configure agent behavior per colony or brood:

AgentConfig(
  model: Some("claude-sonnet-4-5"),   // Model to use
  max_turns: Some(50),                // Max conversation turns
  allowed_tools: None,                // Tool whitelist (None = all)
  disallowed_tools: None,             // Tool blacklist
  system_prompt: None,                // Custom system prompt
  append_system_prompt: None,         // Append to default prompt
)

Defaults: Sonnet model, 50 max turns, all tools allowed.

Debugging

Check hld Status

# Health check
curl http://localhost:7779/health

# Or via make
make hld-status

View Agent Events

Watch real-time events in Bloom’s agent tab, or stream colony logs:

curl http://localhost:8000/api/colonies/{id}/logs/stream

Common Issues

Symptom	Cause	Fix
”hld daemon not running”	hld not started	make hld-start
”Agent timed out (30min)“	Long-running task	Increase timeout or break task down
Session limit reached	20 sessions per brood	Create a new brood
No events streaming	Subscribe race condition	hld uses include_history=true to replay missed events

Best Practices

1. Use specific instructions — “Add JWT auth with refresh tokens” beats “improve auth”
2. Monitor cost — Check session costs in brood detail view
3. Use script mode for setup — npm install, git clone don’t need AI
4. Break large objectives — Smaller tasks = better agent performance
5. Review agent output — Agents can make mistakes; always verify

Next Steps

• Explore the Bloom dashboard — See agent events in real-time
• Read the architecture guide — Understand the full system
• Check the FAQ — Common questions about agents and pricing

Agents are Colony’s intelligence layer. Master them to build fully autonomous development environments.