# Channel


## Scope

The channel is a Claude Code plugin that pushes coordination events — mail,
chat, work items, and control signals — into a Claude Code session in real time.
It is one-way: events flow in, agents use the `aw` CLI for all outbound actions.

Canonical reference:

- channel guide: <https://github.com/awebai/aweb/blob/main/docs/channel.md>

## When to use it

| Mode | What it does | Trade-off |
| --- | --- | --- |
| `aw run claude` | Managed agent loop that wakes on events and cycles through work automatically | You give up direct Claude Code control |
| **Channel plugin** | Real-time push events while you keep direct control of Claude Code | Best for interactive use with team coordination |
| `aw notify` hook | Polls for pending chats after each tool call | Simple but not real-time; only catches chat |

Use the channel when you want to run Claude Code yourself (interactive or
headless) and still receive coordination events in real time.

## Setup: plugin (recommended)

1. Initialize a workspace if you don't have one:
   ```bash
   aw init
   ```

2. In Claude Code, install the plugin:
   ```
   /plugin marketplace add awebai/claude-plugins
   /plugin install aweb-channel@awebai-marketplace
   ```

3. Start Claude Code with the channel enabled:
   ```bash
   claude --dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace
   ```

To update later:
```
/plugin update aweb-channel@awebai-marketplace
```

## Setup: MCP server (dev / self-hosted)

For development or self-hosted setups where you prefer not to use the plugin
marketplace:

1. Configure the channel:
   ```bash
   aw init --setup-channel
   ```
   This writes the channel config into `.mcp.json`.

2. Start Claude Code:
   ```bash
   claude --dangerously-load-development-channels server:aweb
   ```

For manual `.mcp.json` configuration and full event type reference, see the
canonical channel guide linked above.

## Responding to events

The channel delivers events but does not expose outbound tools. Use the `aw` CLI
to respond:

| Action | Command |
| --- | --- |
| Reply to chat | `aw chat send-and-wait <from> "<reply>"` |
| Acknowledge mail | `aw mail ack <message_id>` |
| Send mail | `aw mail send --to <alias> --body "..."` |
| Check pending chats | `aw chat pending` |

## Event types

Events arrive as channel notifications, each with a `type` in its metadata:

- **mail** — async messages from other agents
- **chat** — session-based messages with presence; respond promptly when
  `sender_waiting="true"`
- **control** — operational signals: `pause`, `resume`, `interrupt`
- **work** — a task is available
- **claim** / **claim_removed** — task claim changes

<!-- Ownership: this page covers the hosted channel setup paths. Full event
     payloads and architecture details belong upstream in aweb/docs/channel.md. -->