Channels

Channels are the user-facing LLM process. One channel per conversation (Discord thread, Slack channel, Telegram DM, etc.). Channels talk to users. They delegate everything else.

What Channels Do

A channel:

Receives messages from users
Maintains conversation personality and context
Responds to simple questions directly
Delegates complex work to branches and workers
Routes follow-up messages to active workers
Displays live status of ongoing work

A channel does NOT:

Execute tasks directly
Search memories itself
Do heavy tool work
Wait for branches or workers to complete
Block on compaction

The channel is always responsive — never blocked by work, never frozen by compaction.

Tools Available to Channels

Channels have a focused set of tools for managing user interaction:

Tool	Purpose
`reply`	Send a message to the user
`branch`	Fork context and think independently
`spawn_worker`	Create a worker to do a task
`route`	Send follow-up to an active worker
`cancel`	Cancel a worker or branch
`skip`	Opt out of responding
`react`	Add emoji reaction to a message

Channels do not have:

memory_recall — delegated to branches
memory_save — delegated to branches
shell, file, exec, browser — delegated to workers

Channel Context

Every turn, the channel’s context includes:

System prompt

Loaded from prompts/CHANNEL.md. Contains personality, identity, and behavioral guidelines.

Identity files

SOUL.md — agent personality and core values
IDENTITY.md — agent capabilities and knowledge domains
USER.md — information about the user

Memory bulletin

A periodically refreshed summary of the agent’s knowledge, generated by the cortex.

// From src/agent/cortex.rs
let bulletin = runtime_config.memory_bulletin.load();

Every channel reads this via ArcSwap — no database queries on the hot path.

Status block

Live status of active branches, workers, and recently completed work.

// From src/agent/status.rs
pub struct StatusBlock {
    pub active_branches: Vec<BranchStatus>,
    pub active_workers: Vec<WorkerStatus>,
    pub completed_items: Vec<CompletedItem>,
}

Conversation history

Persistent message history stored in SQLite, loaded and passed to Rig on each turn.

// From src/agent/channel.rs
let response = agent.prompt(&user_message)
    .with_history(&mut history)
    .await?;

Compaction summaries

When context fills up, old messages are summarized and replaced with summaries. These stack chronologically at the top of history.

Branching for Thinking

When a channel needs to think, search memories, or make a decision, it branches:

// From src/agent/channel.rs
let branch_history = channel_history.clone();

let branch = Branch::new(
    channel_id.clone(),
    description,
    deps.clone(),
    system_prompt,
    branch_history,
    tool_server,
    max_turns,
);

tokio::spawn(async move {
    let conclusion = branch.run(prompt).await?;
    // Send conclusion back to channel via event
});

The branch gets a clone of the channel’s full conversation history. Same context, same understanding. It operates independently — the channel can respond to other messages while the branch thinks.

Creating a branch is literally channel_history.clone(). Branches are git branches for conversations.

Concurrent Branches

Multiple branches can run concurrently per channel:

User A: "what do you know about X?"
    → Channel branches (branch-1)

User B: "hey, can you help with Y?"
    → Channel branches (branch-2)

User C: "how's it going?"
    → Channel responds directly: "Going well! Thinking about X and Y for A and B."

Branch-1 resolves: "Here's what I found about X..."
    → Channel incorporates result

Branch-2 resolves: "For Y, you should..."
    → Channel incorporates result

Next user message triggers channel to synthesize both results

First done, first incorporated. Configurable limit (default 3 concurrent branches).

Spawning Workers

When a channel (or branch) needs heavy lifting done, it spawns a worker:

{
  "name": "spawn_worker",
  "input": {
    "task": "Refactor the authentication module to use dependency injection",
    "worker_type": "interactive",
    "notify_on_complete": true
  }
}

Workers get:

A fresh prompt (no channel context)
Task-appropriate tools (shell, file, exec, browser)
Model routing based on task type (coding workers get stronger models)

See Multi-Agent System for worker details.

Routing to Workers

Interactive workers accept follow-up input:

User: "refactor the auth module"
    → Branch spawns interactive coding worker
    → Branch returns: "Started a coding session for the auth refactor"

User: "actually, update the tests too"
    → Channel routes message to active worker
    → Worker receives follow-up, continues with its existing context

The channel uses the route tool:

{
  "name": "route",
  "input": {
    "worker_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "actually, update the tests too"
  }
}

Status Awareness

Channels see live status updates from all their branches and workers:

// From src/agent/channel.rs
impl Channel {
    fn update_status_block(&mut self, event: &ProcessEvent) {
        self.status_block.update(event);
    }
}

Workers update their status via the set_status tool:

{
  "name": "set_status",
  "input": {
    "status": "analyzing codebase structure (45% complete)"
  }
}

The channel’s next turn includes this in its context, so it can tell the user what’s happening.

Message Coalescing

In fast-moving channels (Discord servers, Slack workspaces), messages arrive in rapid-fire bursts. Spacebot coalesces them:

User A: "hey"
User B: "what's up"
User C: "anyone know about X?"
[all within 500ms]

→ Channel receives one turn with all three messages
→ LLM picks the most interesting thing to engage with
→ Or stays quiet if there's nothing to add

Configurable debounce timing. DMs bypass coalescing automatically.

Retrigger Debouncing

When a branch or worker completes, the channel gets retriggered to incorporate the result. Rapid completions are debounced:

// From src/agent/channel.rs
const RETRIGGER_DEBOUNCE_MS: u64 = 500;
const MAX_RETRIGGERS_PER_TURN: usize = 3;

This prevents retrigger cascades where each retrigger spawns more work, which completes and retriggers again.

Temporal Context

Channels inject temporal context on every turn:

// From src/agent/channel.rs
struct TemporalContext {
    now_utc: DateTime<Utc>,
    timezone: TemporalTimezone,
}

impl TemporalContext {
    fn current_time_line(&self) -> String {
        format!(
            "{}; UTC {}",
            self.format_timestamp(self.now_utc),
            self.now_utc.format("%Y-%m-%d %H:%M:%S UTC")
        )
    }
}

Resolves timezone from:

User’s configured timezone
Agent’s cron timezone
System local time

This powers scheduling, time-aware responses, and cron job coordination.

Lifecycle

Channels are persistent. They exist as long as the conversation exists:

Channel creation

When the first message arrives for a conversation, a channel spawns.

Message handling

Each user message triggers one channel turn (unless coalesced).

Branch/worker management

The channel spawns branches and workers as needed, tracks their state, and incorporates results.

Context compaction

The compactor monitors context size and triggers background compaction. The channel never blocks.

Conversation history

Every turn’s messages are persisted to SQLite asynchronously (tokio::spawn).

Channels shut down gracefully on agent stop or when the messaging platform disconnects.

Error Handling

Channels handle errors gracefully: LLM errors — Logged, user sees a friendly error message Branch errors — Branch returns partial result or error description, channel incorporates it Worker errors — Worker status updates to “failed”, result includes error details Context overflow — Compactor has already handled this (should never reach channel)

Configuration

Channels use process-type defaults from routing config:

[defaults.routing]
channel = "anthropic/claude-sonnet-4"

[defaults.routing.fallbacks]
"anthropic/claude-sonnet-4" = ["anthropic/claude-haiku-4.5"]

See Model Routing for details.

Max Turns

Channels run for a small number of turns per user message:

// From src/agent/channel.rs
agent.prompt(&user_message)
    .with_history(&mut history)
    .max_turns(5)  // Typically 1-3 turns in practice
    .await?

Most channel turns complete in 1-3 iterations. If the channel hits max turns, it likely delegated work and is waiting for results.

Channels should never need many turns. If a channel is hitting max_turns frequently, it’s trying to do work directly instead of delegating.

Next Steps

Branches

Learn how branches fork context and think independently

Workers

Understand how workers execute tasks

Status Block

See how channels track active work

Compaction

Explore how context is managed automatically

Getting Started

Core Concepts

Features

Configuration

Messaging

Deployment

What Channels Do

Tools Available to Channels

Channel Context

Branching for Thinking

Concurrent Branches

Spawning Workers

Routing to Workers

Status Awareness

Message Coalescing

Retrigger Debouncing

Temporal Context

Lifecycle

Error Handling

Configuration

Max Turns

Next Steps

Branches

Workers

Status Block

Compaction

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Features

Configuration

Messaging

Deployment

​What Channels Do

​Tools Available to Channels

​Channel Context

​Branching for Thinking

​Concurrent Branches

​Spawning Workers

​Routing to Workers

​Status Awareness

​Message Coalescing

​Retrigger Debouncing

​Temporal Context

​Lifecycle

​Error Handling

​Configuration

​Max Turns

​Next Steps

Branches

Workers

Status Block

Compaction

Build docs developers (and LLMs) love

What Channels Do

Tools Available to Channels

Channel Context

Branching for Thinking

Concurrent Branches

Spawning Workers

Routing to Workers

Status Awareness

Message Coalescing

Retrigger Debouncing

Temporal Context

Lifecycle

Error Handling

Configuration

Max Turns

Next Steps