Auto Channels

Let an agent session (Claude Code or pi) react to the outside world — without a human re-prompting it.

you:     curl -X POST -H "X-Sender: dev" localhost:8788 -d "build failed on main"
claude:  <channel origin="webhook">build failed on main</channel>
         → reads it, reruns the failing test, starts fixing — mid-session, unprompted

A source — an event-source plugin — is a small script that watches for something happening outside the session (a webhook, a timer, a file landing in a directory) and pushes it straight into the transcript as it happens, via Claude Code's channels feature. Add, edit, or delete a source by saving a file in your own project; it's live immediately — no restarts, no registration, no redeploy.

Requirements

Bun ≥ 1.2, plus either Claude Code v2.1.80+ with channels enabled (research preview) or pi with the channels.tools extension (using it from pi).

Related MCP server: vanth

Quickstart

In your project:

bunx github:royiro10/auto-channels init        # --pi for pi, --claude --pi for both
claude --dangerously-load-development-channels server:auto-channels

To pin a release instead of following the latest: bunx github:royiro10/auto-channels#v0.1.0 init --ref v0.1.0.

init creates one adapter registration per host you select — .mcp.json at your project root for Claude Code (the default), .pi/channels.json for pi — and one self-contained .channels/ directory owning everything else, its own node_modules included, so a non-JS repo gains no root-level JS toolchain files. .channels/ depends on this GitHub repo and its lockfile pins the commit. To upgrade, cd .channels, then bun update auto-channels (following the latest) or bun add github:royiro10/auto-channels#v<version> (pinned), and restart the daemon (how). It's also safe in a project that's already set up: existing JSON configs gain only the missing entries (your other MCP servers survive untouched), and nothing is ever overwritten.

Nothing runs until you opt in. Enable your first source with a one-line file:

// .channels/sources/hooks.ts — live the moment you save it
import { webhook } from 'auto-channels/builtins'
export default webhook({ allowedSenders: ['dev'] })

Then, from another terminal:

curl -X POST -H "X-Sender: dev" localhost:8788 -d "build failed on main"

Example: the webhook builtin

import { webhook } from 'auto-channels/builtins'
export default webhook({ allowedSenders: ['dev', 'ci-bot'], port: 9000, path: '/ci' })

allowedSenders is required: the gate on the X-Sender header lives in your activation file. Every option, plus cron() and filedrop(): builtin sources.

The one hard rule

Channels only reach a real interactive claude session. -p/print mode structurally never receives channel events — confirmed empirically, not a timing fluke (see how Claude Code channels behave). --dangerously-load-development-channels is required for any custom channel during the research preview.

Documentation

• Writing your own source — the contract, gating, testing, opt-in delivery, multiple sessions.

• Builtin sources — webhook, cron, filedrop and their options.

• Configuration — env vars and when an invalid one fails.

• Using it from pi.

• Architecture and debugging — the daemon, daemon.log, the status file, restarts, known limitations.

• How Claude Code channels behave — the platform facts this design rests on.

Contributing

Issues and pull requests welcome; the dev setup, the gate and the rules for changing the code are in CONTRIBUTING.md.

Security

Report vulnerabilities privately, not in public issues: see SECURITY.md.

License

MIT