From 1e6870e1883d2118e0198ea45066a221bf3e051e Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Wed, 2 Sep 2026 14:21:40 -0700 Subject: [PATCH] docs: rewrite Claude channel setup guide --- integrations/claude-channel/README.md | 222 ++++++++++++++++---------- 1 file changed, 134 insertions(+), 88 deletions(-) diff --git a/integrations/claude-channel/README.md b/integrations/claude-channel/README.md index 5a9793f..c72ad4b 100644 --- a/integrations/claude-channel/README.md +++ b/integrations/claude-channel/README.md @@ -1,88 +1,134 @@ -# @plannotator/artifact-server-claude-channel - -The Artifact Server bridge for [Claude Code -channels](https://code.claude.com/docs/en/channels-reference). Claude Code -spawns this process over stdio; it runs the same claim loop as the Pi bridge -(the long poll is the heartbeat, so presence is real), pushes each dispatched -annotation bundle into the opted-in session as a -`notifications/claude/channel` event, and exposes the `artifact_comments` -tool so Claude replies to and resolves each thread. - -## Evidence tier - -This bridge registers with `capabilities: {beacon: true, evidence: -"channel"}`. `delivered` means the notification was written to the -transport — admission to the session, not model processing. Claude Code -queues channel events while the session is busy, which matches the bridge's -follow-up-only delivery rule. A rejected notification fails that dispatch and -leaves the channel process available for later bundles. - -## Configuration - -Same resolution as the Pi extension, once at start: - -| Source | Setting | -| --- | --- | -| Environment | `ARTIFACT_SERVER_ORIGIN` + `ARTIFACT_SERVER_AGENT_TOKEN` | -| Environment | `ARTIFACT_SERVER_AGENT_NAME` (optional display name) | -| Local discovery | `~/.artifact-server/local-service.json` + `local-api-token` | - -Nothing resolved → one stderr notice, then dormant. - -## Try it (research preview) - -Channels are a research preview; custom channels run behind a development -flag. From a project directory: - -1. Add the channel to that project's `.mcp.json`: - - ```json - { - "mcpServers": { - "artifact-server": { - "command": "npx", - "args": ["-y", "@plannotator/artifact-server-claude-channel@"] - } - } - } - ``` - -2. Start the local Artifact Server (`pnpm dev` in this repository, or a - packaged `artifactserver start`). - -3. Launch Claude Code with the development bypass for this entry: - - ```bash - claude --dangerously-load-development-channels server:artifact-server - ``` - -4. In the Artifact Server web UI: comment on an artifact and Send to agent — - the session appears in the picker as a `claude`-kind agent with live - presence. The bundle lands in the Claude session as a - `` event; Claude replies and resolves - through `artifact_comments`, and the threads update in the web UI. - -The package version above is a release-day placeholder. For development from -this repository, replace the command and arguments with -`"node"` and -`["/path/to/artifact-server/integrations/claude-channel/bin/claude-channel.js"]`. - -The `channelsEnabled` organization policy still applies; the flag bypasses -only the allowlist. - -If the session starts but bundles never arrive, check in order: - -1. Team/Enterprise org policy: `channelsEnabled` must be true — Claude Code - drops channel events silently when it is off. -2. `MCP_PROTOCOL_NEGOTIATION=auto` in your environment: Claude Code refuses - to register a channel server that negotiates MCP revision 2026-07-28 - (this package's SDK can). Unset it for the channel session. -3. The startup notice: Claude Code prints one line naming exactly why a - channel did not register. - -## Tested - -`tests/client/claude-channel.test.ts` drives this process over real stdio -MCP against a real spawned server: channel-tier registration, one -notification per bundle (sanitized), `delivered` on transport admission, -and reply/resolve through the tool to `addressed`. +# Claude Code live feedback + +Connect a Claude Code session to Artifact Server through +[Claude Code Channels](https://code.claude.com/docs/en/channels-reference). +Reviewers can send open comment threads to the session. Claude receives the +threads, completes the work, replies, and resolves them in Artifact Server. + +## Current support + +Claude Code Channels are a research preview. Custom channels require a +development flag. Team and Enterprise administrators must also enable the +`channelsEnabled` organization policy. + +The Artifact Server channel is currently available from a source checkout. +The npm package is not published yet. + +## Before you start + +Before you start, make sure that: + +- Artifact Server is running. +- The Artifact Server source is available locally. +- Node.js 24.12.0 or later is installed. +- pnpm 10.34.3 is installed. +- Claude Code supports Channels. + +From the Artifact Server source directory, install the dependencies: + +```bash +pnpm install +``` + +## Connect to Artifact Server + +### Local installation + +If `artifactserver start` runs the server, the channel reads the connection +from these files: + +- `~/.artifact-server/local-service.json` +- `~/.artifact-server/local-api-token` + +No additional connection settings are necessary. + +If `pnpm dev` runs the server from source, set the origin and token in the +shell that starts Claude Code: + +```bash +export ARTIFACT_SERVER_ORIGIN="http://127.0.0.1:8787" +export ARTIFACT_SERVER_AGENT_TOKEN="$(<.artifact-server/local-api-token)" +``` + +Run these commands from the Artifact Server source directory. Do not print or +commit the token. + +### Team installation + +Ask an Artifact Server administrator to issue an API key with these +permissions: + +- **Connect agents** +- **Manage comments** + +Set the server origin and API key in the shell that starts Claude Code: + +```bash +export ARTIFACT_SERVER_ORIGIN="https://artifacts.example.com" +export ARTIFACT_SERVER_AGENT_TOKEN="replace-with-the-api-key" +``` + +Do not add the API key to `.mcp.json` or source control. + +You can also set `ARTIFACT_SERVER_AGENT_NAME` to change the session name that +appears in Artifact Server. The default name is the current directory name. + +## Add the channel to Claude Code + +Add this entry to `.mcp.json` in the project where you use Claude Code: + +```json +{ + "mcpServers": { + "artifact-server": { + "command": "node", + "args": [ + "/absolute/path/to/artifact-server/integrations/claude-channel/bin/claude-channel.js" + ] + } + } +} +``` + +Replace the example path with the absolute path to your Artifact Server +checkout. + +## Start Claude Code + +Start Claude Code from the project that contains `.mcp.json`: + +```bash +claude --dangerously-load-development-channels server:artifact-server +``` + +Claude Code shows a warning for the development channel. Select **I am using +this for local development**. If Claude Code also asks whether to use the MCP +server, select **Use this MCP server**. + +## Send comments to Claude + +1. Open an artifact in Artifact Server. +2. Add one or more comments. +3. Select the Claude session in the agent picker. +4. Send the open comments to the session. + +Claude receives the comments as follow-up work. The channel gives Claude the +`artifact_comments` tool to read, reply to, and resolve each thread. + +## Troubleshooting + +If the channel does not start, run `/mcp` in Claude Code. Make sure that the +server entry uses the correct absolute path. + +If Claude Code reports that an organization policy blocked the channel, ask +an administrator to enable `channelsEnabled`. + +If the channel starts but no agent appears in Artifact Server, make sure that +Artifact Server is running. Then make sure that the connection settings are +available in the shell that started Claude Code. + +If `MCP_PROTOCOL_NEGOTIATION=auto` is set, Claude Code can reject the MCP +version of the channel. Unset the variable. Then restart Claude Code. + +Claude Code writes channel errors to +`~/.claude/debug/.txt`.