# Claude Code Agent teams and channels

> Claude Code: Teams, event channels, permission relay, coordination, costs, and Passion8 boundaries.

URL: https://docs.passion8.cc/en/docs/claude-code/agent-teams-channels
Language: en
Publisher: Passion8

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:

```json title="~/.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 |

```text
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

1. Begin with research/review roles where appropriate.
2. Restrict writes by approval or directory.
3. Isolate writers with worktrees.
4. Use hooks for meaningful quality gates.
5. 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:

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

Development preview:

```bash
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.

```text
<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 |

## Official references

- [Teams](https://code.claude.com/en/docs/en/agent-teams.md)
- [Channels](https://code.claude.com/en/docs/en/channels.md)
- [Channel reference](https://code.claude.com/en/docs/en/channels-reference.md)
- [Parallel agents](https://code.claude.com/en/docs/en/agents.md)
- [Agent View](https://code.claude.com/en/docs/en/agent-view.md)
- [Workflows](https://code.claude.com/en/docs/en/workflows.md)

## Related pages



- [Parallel agents and workflows](https://docs.passion8.cc/en/docs/claude-code/parallel-agents): Subagents, background work, batch, fork, goals, and workflows.
- [MCP](https://docs.passion8.cc/en/docs/claude-code/mcp): Transports, authentication, tool search, and permissions.
- [Permissions](https://docs.passion8.cc/en/docs/claude-code/permissions): Rules, modes, and managed policy.
- [Adoption and communications](https://docs.passion8.cc/en/docs/claude-code/adoption-communications): Include remote approval and channels in rollout guidance.