Skip to content

Commit 884add3

Browse files
0xsline0xsline
committed
docs: add channel event notification documentation
1 parent 277fd0b commit 884add3

1 file changed

Lines changed: 161 additions & 0 deletions

File tree

‎docs/advanced/channel.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Channel — Platform Event Notifications
2+
3+
Push real-time platform events into your active AI coding session. When something happens on a platform (new tweet, new email, new post), opencli notifies your current Claude Code session automatically.
4+
5+
## How It Works
6+
7+
```
8+
Platform (Twitter, V2EX, GitHub...)
9+
↓ polling / webhook
10+
opencli channel server (MCP stdio)
11+
↓ notifications/claude/channel
12+
Claude Code session ← you see the notification here
13+
```
14+
15+
The channel server runs as an MCP server with the `claude/channel` experimental capability. It monitors configured platforms and pushes events into your active session via the MCP protocol.
16+
17+
## Quick Start
18+
19+
### 1. Configure sources
20+
21+
Create `~/.opencli/channel.yaml`:
22+
23+
```yaml
24+
sources:
25+
# Poll V2EX hot posts every 60 seconds
26+
- command: v2ex/hot
27+
type: polling
28+
interval: 60
29+
enabled: true
30+
31+
# Poll Twitter notifications every 90 seconds
32+
- command: twitter/notifications
33+
type: polling
34+
interval: 90
35+
enabled: true
36+
37+
webhook:
38+
enabled: true
39+
port: 8788
40+
token: "" # optional auth token, supports $ENV_VAR
41+
```
42+
43+
### 2. Register MCP server
44+
45+
Add to `~/.claude.json` under `mcpServers`:
46+
47+
```json
48+
{
49+
"opencli-channel": {
50+
"command": "npx",
51+
"args": ["tsx", "/path/to/opencli/src/main.ts", "channel", "start"],
52+
"type": "stdio"
53+
}
54+
}
55+
```
56+
57+
Or if opencli is installed globally:
58+
59+
```json
60+
{
61+
"opencli-channel": {
62+
"command": "opencli",
63+
"args": ["channel", "start"],
64+
"type": "stdio"
65+
}
66+
}
67+
```
68+
69+
### 3. Launch Claude Code with channel
70+
71+
```bash
72+
claude --dangerously-load-development-channels server:opencli-channel
73+
```
74+
75+
That's it! Platform events will now push into your session automatically.
76+
77+
## CLI Commands
78+
79+
```bash
80+
opencli channel start # Start MCP stdio server (called by Claude Code)
81+
opencli channel status # Show running channel server status
82+
opencli channel stop # Stop the running channel server
83+
```
84+
85+
## Configuration Reference
86+
87+
### `~/.opencli/channel.yaml`
88+
89+
```yaml
90+
sources:
91+
- command: <site/name> # opencli command to poll (e.g. twitter/timeline)
92+
type: polling # event source type
93+
interval: 60 # seconds between polls (minimum: 30)
94+
enabled: true # toggle source on/off
95+
dedupField: id # optional: override dedup key field
96+
97+
webhook:
98+
enabled: true # enable webhook HTTP receiver
99+
port: 8788 # HTTP port (localhost only)
100+
token: "" # Bearer token auth (empty = no auth)
101+
# supports $ENV_VAR syntax
102+
```
103+
104+
### Polling Sources
105+
106+
Any opencli command that returns a list can be used as a polling source. The channel server runs the command periodically, compares results with the previous snapshot, and pushes new items as notifications.
107+
108+
**Dedup key priority:** `id` > `url` > `title` > SHA-256 hash. Override with `dedupField` for platforms with custom ID fields (e.g. `dedupField: bvid` for Bilibili).
109+
110+
**Example sources:**
111+
112+
| Command | What it monitors |
113+
|---------|-----------------|
114+
| `v2ex/hot` | V2EX hot posts |
115+
| `twitter/notifications` | Twitter mentions & replies |
116+
| `twitter/timeline` | New tweets from follows |
117+
| `bilibili/dynamic` | Bilibili followee updates |
118+
| `reddit/hot` | Reddit hot posts |
119+
| `jike/notifications` | Jike notifications |
120+
| `bloomberg/feeds` | Bloomberg news |
121+
122+
### Webhook Source
123+
124+
The webhook source listens for HTTP POST requests on localhost. External services (CI, monitoring, custom scripts) can push events:
125+
126+
```bash
127+
curl -X POST http://127.0.0.1:8788/events \
128+
-H "Content-Type: application/json" \
129+
-d '{"source": "github", "event": "push", "message": "New push to main branch"}'
130+
```
131+
132+
**Payload format:**
133+
134+
| Field | Type | Description |
135+
|-------|------|-------------|
136+
| `source` | string | Platform name (e.g. "github") |
137+
| `event` | string | Event type (e.g. "push", "new_email") |
138+
| `message` | string | Human-readable event summary |
139+
| `data` | object | Optional raw event data |
140+
141+
## Error Handling
142+
143+
| Scenario | Behavior |
144+
|----------|----------|
145+
| Poll fails | Exponential backoff (×2, ×4, max 5min), one notification to user |
146+
| Cookie/auth expired | Pauses source, notifies user |
147+
| Queue overflow (>200) | Discards oldest events silently |
148+
| Claude Code disconnects | Graceful shutdown, releases lock |
149+
150+
## Architecture
151+
152+
- **Read-only / push-only** — The channel only monitors and notifies. All platform actions (reply, like, etc.) go through normal `opencli` commands.
153+
- **Pluggable event sources** — `EventSource` interface supports polling, webhook, and future extension-based monitoring.
154+
- **Single instance** — Lock file prevents duplicate channel servers.
155+
- **Browser lock** — Cross-process coordination prevents conflicts between channel polling and interactive opencli usage.
156+
157+
## Requirements
158+
159+
- Claude Code v2.1.80+ (Channels is a research preview feature)
160+
- `claude.ai` login (API key auth not supported for Channels)
161+
- Team/Enterprise orgs must enable Channels in admin settings

0 commit comments

Comments
 (0)