Skip to content

Agents and groups

New to tclaude?

The tutorial Run a team through a lead walks through a first team step by step.

An agent is a conversation registered with the agentd daemon: it has a stable identity, belongs to groups, and can exchange mail with its peers and the operator. This page covers the daemon in brief, how identity works, what groups are, and how messaging behaves. Spawning new agents and managing their lifecycle is on Spawning and lifecycle; the permission model those features gate on is on Permissions and audit.

The agentd daemon

tclaude agent is a thin client. Everything it does — identity resolution, permission gating, message delivery, spawning — routes through tclaude agentd, a long-running daemon that owns the SQLite database at ~/.tclaude/data/db.sqlite and the tmux nudges into agent panes. Nothing under tclaude agent works without it: the CLI deliberately refuses to fall back to direct database access when the daemon is down, so killing the daemon never bypasses authorization. Fail-closed is the design, not an accident.

Start it in a non-sandboxed shell (it needs the tmux socket and the database):

tclaude agentd serve

It also ships as a standalone binary, tclaude-agentd, with the same code and flags (go install . ./cmd/... builds both). Keep tclaude on PATH next to it — the daemon forks tclaude session new to spawn agents. The daemon runs in the foreground; restart it after upgrading tclaude, because the CLI and daemon share an evolving request schema and an old daemon silently drops request fields it does not know.

Agents reach the daemon over a Unix socket, canonically ~/.tclaude/api/agentd-socket/agentd.sock — kept outside ~/.tclaude/data/ so sandbox profiles can deny the private data tree while leaving the socket reachable. The human additionally gets a loopback HTTP listener on a random port for the dashboard and human-approval popups (--dashboard-port pins it; a taken configured port fails startup rather than falling back).

The CLI is resilient to daemon restarts: connections retry with backoff, and mutating requests carry a stable request ID that the daemon records in a request-outcome ledger, so a retried request replays the completed response instead of mutating twice.

Daemon-side configuration lives under agent.* keys in ~/.tclaude/data/config.json.

For the full architectural model — what state lives where and how the pieces relate — see Architecture.

Identity: who is calling

The daemon authenticates every request without tokens for agents. It reads the connecting process's PID from the kernel (Unix socket peer credentials), then walks the host process tree looking for a recognized harness runtime — any registered harness binary (claude, codex, opencode, copilot, gemini, pi) or Claude Code's node. Recognition uses the process name or the kernel-reported executable path (/proc/<pid>/exe), because argv[0] and the comm name are spoofable.

Every request lands on one of three verdicts:

  • Agent — a harness ancestor was found. The daemon resolves which conversation the process belongs to and maps it to a stable agent id (agt_…) that survives /clear conversation rotation and reincarnation. Agent requests pass through the permission model.
  • Human — no harness ancestor, plus a valid operator token (or the cookie-authenticated dashboard). The human bypasses every permission gate.
  • Refused — anything else. There is no "assume human" path.

The operator token (tclo_ prefix) is minted fresh at each daemon start, held in memory only, and by default printed only when both stdout and stderr are real terminals; you export it as TCLAUDE_HUMAN_TOKEN. There is nothing durable for an agent to steal, and a harness ancestor always beats a token: an agent that somehow obtains the operator token still authenticates as an agent (the daemon also strips the variable from sessions it spawns). Opt-in persistence exists (a 0600 ~/.tclaude/data/operator_token file the CLI auto-reads, or the OS keychain), but the default is ephemeral.

agentd serve --print-human-token=auto|always|never controls the startup banner and the --tui dashboard sign-in link. The default auto hides secrets when either output stream is redirected. never suppresses them even in a terminal; the legacy --no-print-human-token is an alias for never and conflicts with always. always explicitly prints even to redirected output: under systemd this puts the bearer token in the journal, where local users may read it. Token generation and authentication are unaffected.

TCLAUDE_SESSION_ID is a routing key, never authentication.

tclaude agent whoami          # print your resolved identity
tclaude agent lookup <name>   # resolve a name or ID prefix to its agt_ id
tclaude agent ls              # list agents reachable to you (your groups)

Wherever a command takes an agent selector, you can pass the agt_ id (preferred — immune to conversation rotation), a full conversation id, an 8+-character conversation-id prefix, a global head alias, or the display title.

Exit codes

tclaude agent commands that talk to the daemon exit with a code a script can branch on:

Code Meaning
0 Success.
1 Not found: no agent, group, message or other target matched.
2 Ambiguous: a selector matched more than one target.
3 Invalid argument.
4 I/O failure: the daemon is unreachable, or it failed for another reason.
5 Refused: an identity failure, a permission denial, or any other HTTP 403 from the daemon whose code does not map to 1–3 above.

A permission denial exits 5. Earlier versions exited 4, the same as an I/O failure, so a script could not tell "you may not do this" from "the daemon is down". A script that retried on 4 should not retry on 5: a retry will not grant a permission.

Becoming an agent

There are two paths into agenthood:

  • Spawn — the daemon launches a fresh session directly into a group, with a briefing. See Spawning and lifecycle.
  • Promote — enroll an existing plain conversation as an agent:
tclaude agent promote <selector>

Promote also reinstates a retired agent. Cross-agent promotion is gated (agent.promote, or the group-scoped manager equivalent — see the manager pattern).

Groups

A group is the allow-list of who can talk to whom, plus shared settings: startup context, a default directory, a default spawn profile, a common spawn environment, and a member cap. Reads (ls, members, owners) are open to any agent; mutations gate on groups.* permission slugs.

tclaude agent groups create myteam --context-file brief.md
tclaude agent groups add myteam <selector> --role reviewer
tclaude agent groups members myteam

create can bootstrap members inline (--member name=..,role=..,descr=..,cwd=..). Beyond the roster verbs (add, remove, move, update-member, rename, rm), groups carry a family of settings verbs — set-context, set-default-dir, set-default-profile, set-environment, set-descr, set-max-members, set-notifications, set-owner-scopes, set-remote-control — plus archive/unarchive, clone, bulk stop/resume/retire, rebrief, export/import (human-only by default; groups.export and groups.import), persistent attachment reference links, and nest (dashboard tree cosmetics only — nesting inherits nothing). A group's default spawn profile applies to every spawn into the group, including the workers of its triggers, schedules and processes. An agent may only set a default profile whose grants it could confer itself: one that sets permission overrides, or names roles with grants, takes permissions.grant and grants no wider than the agent's own. A profile that makes its spawns owners takes groups.owners.manage for the group. Owning the group is not enough for either. Editing what a profile or role confers takes the same authority; see spawn profiles and roles. Membership transfers are recorded in the audit trail.

For reusable team blueprints, scheduled check-ins, and mission-framed deployments built on top of groups, see Teams at scale.

Ownership

Owners (grant-owner / revoke-owner) can message members without being members themselves, and ownership structurally contributes permissions: the group-scoped groups.* roster and settings slugs plus the groups.members.<verb> manager slugs for the owned group, and unscoped human.notify and process.runs.read. It never confers slugs that mutate shared configuration. groups set-owner-scopes lets you narrow what owning a particular group confers (it only takes reach away). Details on Permissions and audit.

Group startup context

groups set-context (or --context/--context-file at create) stores shared context that is delivered as part of every spawned member's startup briefing — the standing brief every member of the team should start with. A single spawn can opt out with --no-group-context, and spawn profiles carry an include_group_default_context field.

Re-injection after compaction and /clear

A harness compaction summarizes the first turn, where the startup briefing lives, and /clear drops it. On either boundary tclaude queues an ordinary inbox message (on every harness that reports the boundary) re-injecting what the summary may have lost:

  • after a compaction: the agent's identity (name, role, groups, spawner, worktree), the group startup context as it reads now, the profile/role startup context it was spawned with, and a pointer to the original briefing message and task link — never the full brief;
  • after /clear: the identity only.

The group used is the spawn group while the agent is still in it, otherwise its oldest-joined group. That group's Re-inject after compact setting (Group settings dialog, or groups set-reinject) chooses contexts (the default, as above), identity (identity only after a compaction too), or off:

tclaude agent groups set-reinject myteam identity

Only the agent's own compaction counts, not one by an in-harness subagent. Claude Code's compaction hooks look the same for both, so while a subagent is running tclaude holds the message until the agent's next turn event and sends it only if the main transcript recorded a compaction. If the transcript can't be read it sends the message anyway.

Claude Code, Codex, OpenCode, pi and Copilot all report compactions. Gemini CLI does not, so a Gemini agent gets nothing after one; see Startup-context re-injection.

The rest of tclaude waits for the same answer. A compaction that might be a subagent's skips the pre-compact guard and the "compacting" status. The agent's context figures and nudge state are reset only once the compaction is proven to be the agent's own, and at that point any standing orders triggered by the compaction are delivered as messages rather than hook context.

Group spawn environment

The dashboard's consolidated Group settings dialog edits the default directory, startup context, default spawn and sandbox profiles, environment, policies, and persistent link together. The CLI equivalent for environment is:

tclaude agent groups set-environment myteam \
  --env APP_ENV=development --env FEATURE_FLAG=on

Omit every --env to clear the group environment. Resolution lives in the daemon, so the same settings reach dashboard, CLI, and agent-to-agent spawns. Existing agents pick up the current group environment after restart, stop/resume, clone, or reincarnation; their already-running process is not modified in place. The group's web terminal also inherits these values when its persistent tmux session is first created; an existing terminal keeps its original environment.

Moving an agent between groups

tclaude agent groups move old-team <selector> new-team \
  [--keep-permissions] [--keep-sandbox] [--keep-environment]

Dragging a member onto another group's box in the dashboard does the same. The confirm dialog has one checkbox per group-sourced setting, all ticked by default, each reading "Switch to new-team's …"; unticking one keeps that setting on the group the agent leaves. The agent keeps its role and description, and its per-agent permissions, explicit sandbox profile and per-agent environment overrides are kept either way.

  • Permissions apply immediately: new-team's group permissions apply now, and old-team's stop. --keep-permissions (unticking the box) keeps old-team's group permissions too, still bound to old-team (a grant that only acts on old-team's members keeps acting only there) and following its later edits. It is operator-only. The agent sees kept groups in tclaude agent whoami, and tclaude agent groups members old-team lists who still holds old-team's permissions this way. tclaude agent groups drop-kept-permissions old-team <selector> ends them, as do deleting the group, retiring the agent, or the agent rejoining and leaving it again.
  • Sandbox profile and environment apply from the agent's next resume or restart; the running process is not changed in place. --keep-sandbox and --keep-environment leave either on the group it left, still following that group's later edits, until that group is deleted.

The agent receives a message describing the move. A move between groups on another node works the same when that node trusts this one unrestricted; otherwise (or on an older node) the dashboard falls back to adding and removing the membership, which switches everything to the new group, and refuses a move with an unticked box.

The move is gated like the remove and add it replaces: groups.members.remove on the source group and groups.members.add on the target.

Default directory and auto-join

groups set-default-dir pre-fills the spawn form, is substituted server-side when a spawn leaves the working directory blank (so agent spawn without --cwd lands there rather than in your current directory), and powers directory auto-join: a bare tclaude launched in a directory that exactly matches an active group's default dir (after absolute/clean/symlink resolution) spawns into that group through the same daemon spawn orchestration as any other spawn.

cd ~/work/myrepo   # a group's default dir
tclaude            # joins that group as a new member

Per launch, --auto-join-group=false disables it and --auto-join-or-create-group creates a group named after the directory basename; the config keys are session.auto_join_group and session.auto_join_or_create_group (tclaude config get|set shows and changes them). Solo-only flags such as --label keep a launch solo, with a notice; see Sessions. groups ls --json includes each group's default_cwd (to a human caller). When several groups share a default dir, the tie is broken by a default group marked in the dashboard's group settings menu (there is no CLI verb for that mark).

Max members

groups set-max-members sets a hard cap: a spawn that would exceed it is refused with 409 group_full, and the cap binds the human too — it is a structural limit, not an agent-only guardrail. 0 (the default) means unlimited.

groups link add <from> <to> creates a directed edge that lets members of the from group message members of the to group without co-membership. The owner of the from group can create the link without holding the link slug. groups why-can-i-message <target> explains which path — shared group, ownership, or link — authorizes a given send.

Messaging

tclaude agent message <target> "short note"
tclaude agent message <target> --file brief.md --subject "task"
tclaude agent message group:myteam "stand-up in 5"
tclaude agent reply <id> "done"

Composing a group multicast from the dashboard — sender, live membership tick-list, and a role filter

Composing a group multicast from the dashboard — sender, live membership tick-list, and a role filter

message (aliases msg, send) takes the body as positional text, --body, --stdin, or --file — exactly one; --file sidesteps shell quoting, including backticks. --subject and repeatable --cc behave as you would expect; --gen pins a send to a specific past generation of the target.

Direct sends are authorized by a shared group, ownership of a group containing the target, or an inter-group link. The message.direct slug is the off-group escape hatch, not granted by default.

Durable first, nudge second

Delivery is durable-first: the message row lands in SQLite before any attempt to notify the target. The tmux nudge — a line injected into the target's pane — is only a best-effort notifier on top. For an online target, the nudge worker resolves the target's current generation, waits while the pane's input is blocked (a nudge is never injected into a permission prompt), retries transient tmux failures, and picks inline versus pointer delivery. For an offline target, notification attempts for regular messages are discarded — no burst of stale nudges on resume — while the unread inbox row stays durable; lifecycle, process, and scheduler nudges stay queued instead.

Short printable bodies (up to agent.message_inline_max_chars, default 2000 runes) are delivered inline in the nudge and their inbox copy marked read. Longer or control-character-bearing bodies get a pointer nudge telling the agent to run inbox read <id>. Harnesses driven over an API channel rather than keystrokes are notified over that channel, with no keystroke fallback.

Backpressure: each target holds at most 10 unprocessed regular messages. A direct send to a full target is rejected with queue_full and no row is written; group and CC sends warn per full recipient and continue.

Multicast

Target group:<name> (or group:<id>, or bare group: when you are in exactly one group) writes one message row per member other than the sender. The sender must be a member or owner; --role R restricts delivery to members with that role tag.

The inbox

tclaude agent inbox ls --unread
tclaude agent inbox read <id>
tclaude agent inbox sent
tclaude agent inbox prune

Reading a task brief from the inbox — the Reply-Cmd header tells the agent exactly how to answer

Reading a task brief from the inbox — the Reply-Cmd header tells the agent exactly how to answer

inbox (aliases mailbox, mail) lists, reads (RFC-822-shaped headers: From, To, Group, Subject, Date, Replyable, Reply-To, Reply-Cmd), shows your outbox (sent), waits interactively for the next message (watch — an arriving inline message releases the watcher), and deletes old mail (prune). Reading another agent's inbox (ls --target) needs agent.inbox-watch or group ownership. reply <id> sends to the message's Reply-To and inherits Re: <subject>.

notify-human

notify-human is the agent-to-human channel: the message lands in the dashboard's Messages tab. It is permission-gated on the human.notify slug — granted by default to no one, held by trusted coordinators — and any group owner passes the gate too (that owner bypass is suppressible with an explicit deny). An agent with neither can ask per-call with --ask-human <timeout>, which raises an approval popup for the human.

tclaude agent notify-human "PR is ready for review" \
  --attach out.png --attach report.md

--attach (repeatable, files or directories) works on notify-human. agent message and agent reply take --attach too, for files you can read: at most 4 files and 512 KiB in all, images, text, data and PDF, to a local agent or a remote member@peer, not to a group. The recipient gets its own copy, stored where no sandboxed agent can reach it. The message names the file, and tclaude agent inbox attachment <id> saves it (-o picks the path), for the recipient or the sender only. On notify-human, up to 20 files arrive as separate downloads; more than 20, or a directory, become a single zip (--zip, --separate, and --name control the shape). The body may be omitted when --subject and --attach are both present.

Repeat --option to put a decision to the human instead of only telling them something:

tclaude agent notify-human -s "Which layout?" "Mock attached." \
  --option Tabs --option Sidebar --recommend 2 --attach mock.png

A decision takes 2 to 6 single-line options, and --recommend marks the one the agent suggests. The human answers with a button in the companion window or the Messages reader, and the agent gets the pick as an inbox message starting Decision: <option>, queued for it if it is offline. Only the first answer counts.

What a spawned agent receives

A freshly spawned agent's first-turn welcome and inbox briefing are assembled by the daemon from, in order:

  1. The [system: …] welcome — who the agent is, which group it is in, and the tclaude agent command surface.
  2. The role brief, when spawned with --role-ref or a template role.
  3. The spawn profile's startup_context section, if any.
  4. The group shared context (groups set-context), unless the spawn opted out.
  5. The task brief (--initial-message / --file / template spec).
  6. The reply-to: the spawner by default, so the new agent's first reply reaches its coordinator; --reply-to overrides, and human spawns default to none.

The briefing is always saved as an inbox row; when it fits under agent.spawn_inline_max_chars (default 2000 runes) it is also inlined into the launch prompt with the inbox copy pre-marked read, otherwise the welcome points the agent at its inbox. Worktree path and branch ride the welcome when the worktree lives outside the launch directory.

Note

This spawn briefing is unrelated to Claude Code startup-context trimming (--context-features), which removes items from Claude Code's own startup context and is covered in Utilities.

Agents learn this command surface from bundled skills: tclaude setup --install-agent-skills installs the agent-coord, agent-lifecycle, human-notify, and related skills into ~/.claude/skills, shared ~/.agents/skills, and $CODEX_HOME/skills (default ~/.codex/skills). Claude Code reads its own directory; Codex, Gemini, Copilot, OpenCode and pi read the shared directory. Re-run setup after upgrading the binary. OpenCode's OPENCODE_DISABLE_EXTERNAL_SKILLS disables shared-directory discovery; remove that override to use the installed bundle.

Managed skills and rules

Operators can keep instructions in a tclaude-managed group or user library:

tclaude skills import release --group builders --path ./release-skill
tclaude rules add conventions --user --path ./rules.md
tclaude skills ls --group builders
tclaude skills show release --group builders
tclaude skills show release --group builders --path scripts/check.sh
tclaude rules show conventions --user
tclaude rules rm conventions --user

add and import both read an explicitly supplied directory (skills) or UTF-8 file (rules). Existing names require --overwrite. A skill directory must contain SKILL.md and can include supporting files; symlinks, special files and suspected credentials are refused. Limits are 1 MiB per stored item and 16 MiB per agent's effective set. Library changes apply at the next launch or resume. Only the human can change the library; agents can read user items and their own groups' items.

Managed instructions never automatically install into ~/.claude/skills, ~/.codex, ~/.agents/skills, project instruction files or global harness config. Each managed agent launch gets a private instruction directory with read-only files and an explicit sandbox read grant. The tclaude sandbox mounts it read-only; harness-native enforcement follows that harness's filesystem policy. Claude Code loads its skills as the tclaude-managed plugin when the installed CLI supports --plugin-dir. pi loads the launch directory as a command-line package, so a managed skill shadows a same-named ambient one, and appends the rules to its system prompt. All harnesses receive skill paths in their startup briefing as on-demand instructions. Rules are included in the briefing and re-applied after compaction or clear. The launch snapshot stays frozen even when the library changes. Group context opt-outs do not remove managed operator rules.

Group skills override same-named user skills. Different versions of the same skill in multiple groups refuse launch and name the conflicting groups. Rules are additive, deduplicated by content, and never grant permissions. Ambient harness instruction files are untouched and are not automatically imported.

Managed items travel with an agent in PAF hashed attachments. The receiving agent gets its own overlay; the receiver's rules remain additive and authoritative, and carried skills override same-named library skills for that agent only. Cloning creates an independent overlay, and reincarnation refreshes the next launch without deleting the predecessor's files before it stops. A harness that cannot bind a no-copy clone's identity refuses that operation with managed items; use a history-copy clone. Claude Code and OpenCode can (OpenCode's clone takes the id its managed server mints). On OpenCode the standing guidance arrives over the managed server, as the agent's first turn of the launch, on resume and clone too. One-shot runs with managed items refuse explicitly; use an ordinary worker.

Older receivers are refused only when managed items actually travel. A human can explicitly omit them using --omit-managed-instructions on export, share, move, teleport or import. Legacy v1 archives cannot carry them. Arrived items remain agent-scoped; there is no adoption into the library in v1.

Scripts, executable files and skill hooks always require the receiving human's approval for each transfer. Import preview lists the files and script text, and returns managed_instruction_digest. After inspection, pass that exact value with --approve-managed-scripts DIGEST when applying a PAF or incoming agent bundle. A changed digest refuses; agent callers cannot approve. Peer auto-admission does not skip this step. Alternatively, a human may omit the carried items; receiver rules still apply. No automatic library or user-global install occurs.