---
title: "Agents — Canopy docs | UniverLab"
source: "https://univerlab.org/canopy/docs/agents/"
---

[← Canopy](/canopy/)Documentation

# Agents

Last updated 2026 · Sol 287 · 18:20 UTC (2026-10-14T18:20Z)

Canopy manages three kinds of agents.

## Interactive agents

Each interactive agent runs your chosen AI CLI in a dedicated pseudo-terminal with full vt100 emulation, 24-bit color and cursor positioning — anything that works in a terminal works inside canopy.

## Background agents

Background agents run unattended, triggered by:

*   **Cron schedules** — an event-driven Tokio scheduler computes precise wake-up times and sleeps until needed; near-zero CPU when idle.
*   **File events** — create/modify/delete/move events via the `notify` crate, with configurable debouncing and recursive directory monitoring.

They support configurable timeouts, automatic retries, execution logging (5 MB rotation) and per-run status tracking. Prompts support template variables: `{{TIMESTAMP}}`, `{{TASK_ID}}`, `{{LOG_PATH}}`, `{{FILE_PATH}}`, `{{EVENT_TYPE}}`.

Background agents are managed from the TUI or by other agents through the [agent MCP tools](/canopy/docs/mcp-tools/) (`agent_add`, `agent_watch`, `agent_run`, `agent_status`, …).

### Send to a session

A background agent can deliver its prompt into a _live interactive session_ instead of running a CLI headlessly. Set `action` to `send_to_session` and give a target session — by **name** is recommended, because a name survives session recovery where an id changes. Every time the agent’s cron or watch trigger fires, canopy enqueues the prompt as a scheduled send to that session, and the TUI delivers it on its next refresh tick. Delivery happens when a TUI is open: a message that fires while no TUI is running waits for the next TUI — it is not lost. If a fire is already waiting for the same target, a new fire replaces that message rather than piling up a second one.

Cron example (MCP call):

    {"tool":"agent_add","arguments":{"id":"hourly-orchestrator-nudge","schedule":"0 * * * *","action":"send_to_session","target_session_name":"orchestrator","prompt":"Check the release board and report anything blocked."}}

Watch example:

    {"tool":"agent_watch","arguments":{"id":"spec-changed-nudge","path":"/abs/path/to/specs","events":["modify","create"],"action":"send_to_session","target_session_name":"orchestrator","prompt":"A spec changed; re-read it and update the plan."}}

Omit both target fields to target the calling session. Use `agent_run` to deliver once now.

## Terminal sessions

Raw shell sessions with per-session command history (TOML-backed), cross-session autocomplete search and a Warp-like input mode.

## Seed nursery

The **seed nursery** is a collaborative workspace for creating new seed identities. When you select “Plant New Seed” in the TUI, Canopy creates a temporary directory containing:

*   A draft `identity.toml` with empty/default fields.
*   An instruction file (`AGENTS.md`, `GEMINI.md`, etc., per the platform registry) with gardener instructions that guide the selected CLI to interview the user about the seed’s name, directives, and traits.

Once the agent finishes the interview and writes the final `identity.toml`, the nursery validates it (name uniqueness, field constraints, 4 KB size cap) and moves it to `~/.canopy/seeds/<id>/`. The temporary directory is cleaned up automatically.

## Seed identities

A **seed** is a persistent, evolvable agent identity stored as structured TOML at `~/.canopy/seeds/<id>/identity.toml`:

    name = "Quercus"
    created_at = "2026-01-01T00:00:00Z"
    
    [directives]
    general = [
        "Prioritize type-safety",
        "Explain structural changes before executing"
    ]
    
    [traits]
    tone = "Concise, Technical"
    focus = "Refactoring, Architecture"

*   Each seed has a unique name (case-insensitive), behavioral directives and personality traits; identities are capped at 4 KB and validated.
*   Sessions bound to a seed receive its prompt injection automatically.
*   The `evolve_identity` MCP tool lets agents refine their own identity over time; `create_seed`, `list_seeds` and `remove_seed` manage the nursery.

## Context transfer

Conversation context, prompts and output can be transferred between agents while preserving session state and scrollback history — from the TUI or as part of automated flows.