Claude Code

Agent teams and channels

Teams, event channels, permission relay, coordination, costs, and Passion8 boundaries.

Teams and channels extend Claude beyond waiting for a single prompt, but serve different purposes.

Capability	Purpose	Use
Agent teams	Sessions coordinate, message, and claim tasks	Complex reviews and cross-module research
Channels	MCP pushes external events into a running session	CI, alerts, chat, webhooks
Permission relay	Forward approval requests and decisions	Remote approval from a trusted device

These add concurrent token usage, permissions, and event sources. Check gateway support for the actual model/tool/cache features your workflow uses.

#When to use teams

Teams are independent cooperating Claude instances, not another name for subagents. The experimental feature is enabled with:

~/.claude/settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Teammate display can use teammateMode or --teammate-mode auto. Split panes require tmux or iTerm2's it2 CLI; in-process mode is simpler for ordinary collaboration.

Aspect	Subagent	Team
Context	Separate, result returned to caller	Separate teammates communicating
Coordination	Main agent assigns/collects	Shared claimable task list
Communication	Reports to caller	Direct teammate messages
Cost	Usually smaller focused delegations	Full sessions per teammate
Use	Focused research/review	Broad coordinated work

Spawn 3 teammates: one for security review, one for performance review, and one for test coverage. Have them report separately, then cross-check each other's findings.

#Lead, teammates, and mailbox

Component	Role
Lead	Starts teammates and coordinates direction
Teammates	Independent task execution
Task list	Shared claims/completion
Mailbox	Questions, findings, coordination

Give each teammate its role, inputs, severity criteria, checks, and non-editable files.

#Permissions and quality gates

Begin with research/review roles where appropriate.
Restrict writes by approval or directory.
Isolate writers with worktrees.
Use hooks for meaningful quality gates.
Wait for results before the final synthesis.

#Channels

Ordinary MCP is called by Claude; a channel pushes an event when an external system has something to report.

Source	Event
CI/CD	Failed jobs, logs, deployment state
ChatOps	Slack/Discord/Teams messages
Monitoring	Alerts, recovery, anomalies
Webhook	Issue/PR/ticket/incident changes

Events enter context as channel content. Instructions determine whether to reply, use tools, or await approval.

#Channel entry points

Channel	Prerequisites	Use
Fakechat	Supported login and Bun	Local event/reply testing
Telegram	Bot, plugin, paired sender	Mobile tasks and replies
Discord	Bot, message-content intent, server invitation	Team bridge
iMessage	macOS and required Messages/AppleScript/disk permissions	Personal Apple-device access
Custom webhook	MCP SDK, stdio server, HTTP listener	CI/monitoring events

Start an installed channel:

claude --channels plugin:fakechat@claude-plugins-official

Development preview:

claude --dangerously-load-development-channels server:webhook

A server's presence in .mcp.json alone does not authorize channel events; it must be selected at launch and permitted by policy.

#Channel server contract

Field	Purpose
capabilities.experimental["claude/channel"]	Channel notification support
capabilities.experimental["claude/channel/permission"]	Optional approval relay
capabilities.tools	Reply tools for two-way channels
instructions	Event interpretation and reply behavior

Payload field	Purpose
content	Event body
meta	Routing attributes such as chat_id, sender, severity

Use identifier-safe metadata names, preferably snake_case; punctuation/hyphens may cause keys to be discarded.

#Webhook architecture

Step	Behavior
Declare capability	Register claude/channel
Connect	Claude starts the stdio server
Receive	HTTP listener, bot, or polling receives an event
Notify	notifications/claude/channel sends content/meta
Reply optionally	Expose a reply tool
Relay optionally	Register permission support for trusted senders

Notifications have no end-to-end acknowledgement. A successful transport write does not prove Claude processed the event; use a reply tool if acknowledgement matters.

<channel source="webhook" severity="high" run_id="1234">
build failed on main: https://ci.example.com/run/1234
</channel>

#Permission relay

Approval requests can be forwarded to a trusted remote channel and returned as approve/deny decisions.

Field	Meaning
request_id	Short request identifier; return unchanged
tool_name	Bash, Write, Edit, etc.
description	Description of the proposed action
input_preview	Usually truncated arguments

Sender authorization is essential. A public webhook must not be able to approve production commands.

#Enterprise controls

Setting/control	Recommendation
channelsEnabled	Set explicitly
allowedChannelPlugins	Reviewed plugins only
Managed settings	Consistent team policy
MCP allowlist	Restrict servers/tools
Hooks	Additional checks for sensitive actions

#Cache and cost

Action	Effect
Create team	Each teammate builds a separate session cache
Teammate messages	Enter recipient history
Channel events	Append new context and can refresh TTL
Long gaps between alerts	Default short TTL may be cold
Approval relay	Approval itself usually has no model call; tool result enters context

Keep events concise. Link long logs and fetch needed sections rather than pushing every full log.

#Passion8 boundaries

Question	Check
Does a teammate use Passion8?	Its actual inherited endpoint/credential environment
Does event data reach the model?	It normally becomes session context
Is the gateway compatible?	Required tool, usage, and cache passthrough
Does cloud inherit local config?	No automatic inheritance
Chat/CI data handling	Review each service's permissions and retention separately