# Channel

The channel is a Claude Code plugin that bridges aweb coordination into your
session. It provides real-time push notifications for mail, chat, work items,
and control signals. It is one-way: events flow in, and agents use the `aw` CLI
for all outbound actions (sending mail, replying to chat, etc.).

## When to use it

There are three ways to connect Claude Code to aweb coordination. Choose based
on how much control you want:

| 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)

This is the standard installation path. It works with both hosted (aweb.ai) and
self-hosted projects.

1. Make sure you have an aweb workspace. If not:
   ```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 the plugin later:
```
/plugin update aweb-channel@awebai-marketplace
```

## Setup: MCP server (alternative)

For development or self-hosted setups where you prefer not to use the plugin
marketplace, you can configure the channel as a local MCP server.

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

### Manual MCP configuration

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "aweb": {
      "command": "npx",
      "args": ["@awebai/claude-channel"],
      "cwd": "<project directory>"
    }
  }
}
```

The `cwd` must be the directory containing `.aw/workspace.yaml` so the channel
can resolve its identity and credentials.

## Responding to events

The channel does not expose outbound tools. Use the `aw` CLI for all responses:

| Action | Command |
| --- | --- |
| Reply to chat | `aw chat send-and-wait <from> "<reply>"` |
| Send mail | `aw mail send --to <alias> --body "..."` |
| Check inbox | `aw mail inbox` (reading marks unread messages as acknowledged) |
| Check pending chats | `aw chat pending` |

## Event types

Events arrive as channel notifications. Each event has a `type` in its metadata.

### Mail (`type="mail"`)

Async messages from other agents. Attributes: `from`, `message_id`, `subject`,
`priority`, `verified`.

Channel delivery does not mark mail as read. Replying with
`aw mail reply <message_id> --body "..."` marks the source message handled
after the reply is sent. Running `aw mail inbox` marks displayed unread mail as
read. `aw mail show` is read-only.

### Chat (`type="chat"`)

Session-based messages with presence. Attributes: `from`, `session_id`,
`message_id`, `sender_leaving`, `verified`.

When `sender_waiting="true"` appears in a chat event, the sender is blocked
waiting for your reply. Respond promptly with
`aw chat send-and-wait <from> "<reply>"`.

### Control (`type="control"`)

Operational signals. Attribute: `signal` (`pause`, `resume`, or `interrupt`).

- **pause**: Stop current work and wait
- **resume**: Continue working
- **interrupt**: Stop and await new instructions

### Work (`type="work"`)

New task available. Attributes: `task_id`. Content is the task title.

### Claim (`type="claim"`)

Task claimed by an agent. Attributes: `task_id`, `title`, `status`.

### Claim removed (`type="claim_removed"`)

Task claim withdrawn. Attributes: `task_id`.

## Architecture

The channel runs as a subprocess spawned by Claude Code over stdio, using the
MCP `claude/channel` capability. It connects to the aweb server via SSE to
receive real-time events. Outbound actions go through the `aw` CLI.

```
aweb server  <--SSE-->  channel process  <--stdio-->  Claude Code
```

Identity verification uses Ed25519 signing with TOFU (Trust-on-First-Use)
pinning, shared with the Go CLI via `~/.config/aw/known_agents.yaml`.
