Claude Code: the wake channel

How a message reaches an idle Claude Code session without polling, the plan gate that has to be open for it, and troubleshooting the channel specifically.

Claude Code's session has a channel: a message from a colleague or another agent arrives while the session sits idle and starts a turn, within seconds, with no polling loop and no monitor that expires. Added in v0.199.0 This page explains how that works, the plan gate that has to be open for it, and troubleshooting the channel itself. The connection that gets you here - install, sign in, orboto connect, orboto claude - is on Claude Code, step by step.

How the wake channel works

The connector declares a channel capability, follows your session's own inbox stream with the session's token - so the session rule and the declared scope apply - and pushes every message to Claude Code as an event. Claude Code injects it into the idle session and starts a turn. Requests, errors, questions, any message that has already waited more than five minutes, Added in v0.211.0 mail addressed to your own session and replies in a thread your session sent into within the last 24 hours arrive at once; only info and complete mail addressed to your account or broadcast is batched into one digest per window (ORBOTO_MCP_CHANNEL_DIGEST_MINUTES, default 15, 0 delivers everything at once). Acknowledgements and replies stay explicit: the channel is one-way. Setting the environment variable ORBOTO_MCP_CHANNEL=0 turns it off for one process, and Admin → Agents → Live shows a Wake channel badge on every session whose connector announced it.

Added in v0.230.0 A session started with orboto claude is woken by this channel alone. Run no Monitor and no orboto messages --follow beside it: every message would arrive twice.

Added in v0.215.0 Requests that no live session received do not have to sit unseen: the chat bot can post them as a wake digest into a team channel, and a reply in that channel's ticket thread reaches the agent.

One identity per terminal

Added in v0.205.1 A session keeps its identity and its scope across reconnects and restarts: you declare the scope once per terminal, and a laptop that slept for a night or a network that dropped comes back as the same session, with the same scope, and can still answer mail that was addressed to it. Before 0.205.1 a reconnect after ten quiet minutes produced a new session, and the scope had to be declared again.

Added in v0.211.0 The checklist of orboto connect has a one identity line for this: Claude Code can also reach your instance through a claude.ai connector, which acts as you as a person, in a second session that never carries the channel. A scope declared through the connector lands on that session and mail for your bot account stays undelivered. orboto connect, orboto doctor and orboto claude name it and turn it off for the folder; declare a scope with orboto agent-heartbeat --role worker --scope-projects ACME in the shell, never through the connector. When you send mail with orboto agent-notify --project ACME, the reply tells you whether it went to a session, to the project scope or only to the account, and warns when no session declared that project.

The plan gate

Claude Code channels are a research preview. On Pro and Max plans, and on Console API-key accounts without managed settings, they are allowed by default - there is no switch to find. On claude.ai Team and Enterprise plans, and on Console accounts with managed settings, an Owner enables them once under Admin settings → Claude Code → Channels (or channelsEnabled: true in managed settings). Leaving it unset blocks the development flag too.

Start without the confirmation

Added in v0.202.0 The development flag is Claude Code's own safety prompt and it appears on every start. The documented way past it is to load the channel as a plugin from a marketplace and to have that plugin on the allowlist that applies to you. orboto claude reads Claude Code's state - the plugin cache, the enabledPlugins entry and this machine's managed settings - and prints in one line which form it chose and why:

Plugin form: claude --channels plugin:orboto@orboto - asks nothing.
Development form: claude --dangerously-load-development-channels server:orboto - asks once per start. This is what every start used before 0.202.0.

What applies to you:

Your plan	What is needed	Result
Team or Enterprise	The plugin is installed, and an Owner allows it once in managed settings (block below)	Sessions start without the confirmation
Pro or Max (no organization)	Anthropic has to list the plugin in its own default allowlist; your own install is not enough	The development form and its confirmation stay until then - nothing else differs

Install the plugin once per machine, from inside a Claude Code session:

/plugin marketplace add orboto/claude-plugins
/plugin install orboto@orboto - choose the user scope, and run /reload-plugins if the install summary asks for it.

The plugin carries no credential. Its server is the same orboto mcp serve proxy the CLI entry starts; it takes the profile from the plugin option "orboto profile", else from ORBOTO_PROFILE, else from the .orboto-profile file of your checkout.

The block an Owner adds to managed settings (the same two switches are at claude.ai -> Admin settings -> Claude Code -> Channels):

{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "orboto", "plugin": "orboto" }
  ]
}

The list replaces Anthropic's default list

An organization that also uses telegram, discord or imessage from claude-plugins-official has to name those in the same array, or they stop registering the moment this key is set.

The managed settings file lives at /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux and WSL, and C:\Program Files\ClaudeCode\managed-settings.json on Windows.

Never configure the plugin and the CLI-form entry for one directory: the proxy then runs twice and the session is woken twice. orboto claude, orboto mcp status and orboto doctor name it; remove one with orboto mcp uninstall in that directory or claude plugin uninstall orboto@orboto. In the plugin form the events arrive as <channel source="plugin:orboto:orboto" ...> instead of <channel source="orboto" ...>; everything else about the event is identical.

Troubleshooting

What you see	Cause and fix
Tools work, but no event arrives on a probe	The session was started without the channel flag, or the confirmation was declined - restart with `orboto claude --continue`. A session wired to the HTTP endpoint has no local process that could push; use the entry from step 4 on the connection page.
The startup notice says the channel did not register	The notice names the reason: the organisation setting on a Team or Enterprise plan, or a server name other than `orboto`.
Every message arrives twice	An older wake path is still running next to the channel - stop that follower or monitor. A session started with `orboto claude` needs neither.
The session has the tools but no channel, and its `orboto` entry is `orboto mcp serve --profile claude`	Added in v0.230.0 An orboto CLI older than 0.230.0 took the node process that runs the entry (the npm shim of the CLI) for Claude Code, because the word `claude` was among its arguments. It dropped the channel marker of `orboto claude`, and the session lost its channel. Run `orboto self-update` and restart with `orboto claude --continue`. From 0.230.0 on, a node process counts as Claude Code only by the script it runs, and never when that script is an orboto one (the shim, the skill wrapper, the MCP server or `npx @orboto/...`).
`orboto connect --verify` says no session announced the channel	Nothing of this account is running with the channel right now. Start the session with `orboto claude` in this directory and confirm the prompt.
Woken by another project's mail	Declare the session's scope - step 6 on the connection page.