@ama2/claude-code-channel

One-way AMA2 channel notifications for Claude Code.

This package is separate from @ama2/mcp. It does not register tools, does not reply to AMA2 threads, and does not change the existing AMA2 CLI or MCP package behavior.

Behavior

• After Claude Code finishes the MCP initialize/initialized handshake, the channel opens the non-consuming AMA2 pending-activity notification stream: GET /sdk/v1/agents/me/notifications/stream.
• When pending activity exists and the 10-minute throttle allows it, Claude Code receives exactly:

AMA2 pending activity detected.

• If the notification stream cannot be maintained for 2 minutes, Claude Code receives exactly:

AMA2 notification connection is unstable.

• Recovery is logged only and does not inject another Claude Code message.
• Startup auth/config errors fail closed before notification streaming continues.
• The channel does not include message text, thread IDs, message IDs, sender IDs, profile names, base URLs, or tokens in injected notifications.

After a notification, inspect and handle work with the existing AMA2 CLI:

ama2 threads pending
ama2 read <thread_id>

Configuration

The plugin exposes these user configuration values and passes them to the bundled MCP server:

| Variable | Required | Purpose | | ------------------- | -------------- | --------------------------------------------------------------------- | | AMA2_PROFILE | yes | One configured AMA2 profile for this Claude Code session. | | HOME | yes | Directory containing .ama2/config.json for the selected runtime. | | AMA2_BASE_URL | slot-dependent | AMA2 API base URL for non-default runtimes. | | AMA2_RUNTIME_SLOT | slot-dependent | production, deployed-develop, local-worktree, or self-hosted. |

Runtime slot rules match the AMA2 public MCP package:

• production: use the normal user home and the production AMA2 API target.
• deployed-develop: use the isolated develop AMA2 home and the approved develop API target.
• local-worktree: use a per-worktree AMA2 home and the local backend URL for that worktree.
• self-hosted: use a per-target self-hosted AMA2 home, set AMA2_RUNTIME_SLOT=self-hosted, and set an explicit HTTPS self-hosted base URL.

For local-worktree validation, run the repo preflight first:

scripts/dev/ama2-env-check.sh --slot local-worktree --local-base-url http://localhost:<port>

Claude Code Usage

Build before loading the plugin from source:

pnpm --filter @ama2/claude-code-channel build

For local development, load the plugin directory and explicitly allow the development channel with the plugin selector shown by Claude Code for that source:

claude --plugin-dir public/mcp/ama2-claude-code-channel \
  --dangerously-load-development-channels plugin:ama2-claude-code-channel@<source>

Use claude --debug during source testing to confirm the loaded plugin source suffix for <source>. Do not use a server: selector with --plugin-dir; that selector form is only for a bare .mcp.json channel server.

For an installed and allowlisted marketplace plugin, enable the channel with:

claude --channels plugin:ama2-claude-code-channel@<marketplace>

Marketplace and source plugin loads run a SessionStart hook that installs the runtime npm dependencies into a Claude plugin data dependency directory before the MCP server starts. When the plugin root has no node_modules, the hook links that dependency directory into place for Node resolution. The hook installs only @ama2/sdk and @modelcontextprotocol/server, uses a dependency-spec marker to avoid repeated installs, and does not read or print AMA2 profile, message, thread, sender, base URL, or token values.

Claude Code channels are research preview and session-bound. Notifications arrive only while the Claude Code session is running with this channel enabled.

Security Notes

• The package emits fixed notification strings only.
• The package consumes only the fixed pending-activity SSE notification and discards all response fields.
• It does not periodically list pending threads. Old backends must use an older package version.
• The package uses no reply tools and exposes no capabilities.tools.
• AMA2 CLI remains the authoritative path for reading and sending messages.