Comment.io Plugin for Claude Code

Claude Code skills for working with Comment.io. The plugin teaches Claude to use the first Comment.io route already available: callable tools, a supplied comm through authenticated HTTPS, read-only URL fetch, the visible browser UI, or direct REST. A permanent handle, CLI, and daemon are not required to work in one supplied comm or to use the guidance-only skills.

Set $BASE to the supplied comm's final Comment.io origin after any shortlink redirect; otherwise use the active tool/account origin or an explicitly selected profile's base_url. With no target context, use https://comment.io. Keep every deployment-local guide and CLI --origin on that immutable $BASE.

Use Comment.io now

1. If Comment.io tools are present, use them immediately. With the standard MCP tools, call open_comm, then read_comm; call create_comm only when the human explicitly requested a new comm, never to verify setup. Follow tool next_actions.
2. Otherwise use the supplied comm handoff through authenticated HTTPS, read-only URL fetch, or the visible browser. A hosted connector receives a slug, token-free document URL, or exact clean CMNT/configured shortlink only in url_or_slug; never a raw token-query URL or clean link embedded elsewhere. Local MCP accepts a full invite only when its tool description explicitly says so.
3. If no current route works, follow exactly one matching route from $BASE/llms/setup.txt. Do not install persistent software merely to open one supplied comm.

Optional notification and persistent paths

To arm @mention handling in an ordinary Claude session, start Claude normally and run /comment listen. When no conflicting task identity is active, it can attach a human-selected eligible durable handle; it can also re-arm the Ephemeral handle already used by this session's direct-REST work, or create a standalone Ephemeral listener when no task identity exists. It never creates an unrelated listener for a task using MCP, a connector, browser identity, or a supplied per-doc token; those routes keep their own identity and are checked on active turns unless they provide a real wake mechanism.

For a daemon-managed handle or standing local agent, use comment run: it starts Claude Code in tmux, registers that session with the local daemon for one installed profile, and arms the path for fixed trusted receive nudges. Neither launch is proof of delivery. Call the path live only after a different participant sends a fresh event and this exact runtime receives, reads/responds to, and settles it through $BASE/llms/notifications.txt.

After that optional persistent setup, launch Claude Code with one selected Comment.io profile using:

comment --origin "$BASE" --account your-saved-account run \
  --runtime claude --profile yourhandle.my-agent

For a transparent shell wrapper, use the principal-pinned form generated by the $BASE/llms/setup/full.txt. The wrapper consumes Comment.io flags such as --runtime, --profile, and --cwd; all remaining arguments are passed to Claude unchanged. Do not add a guessed --home: exact --origin plus the saved --account lets the registry resolve that account's scoped home.

Prerequisites

For a supplied comm or guidance-only use: Claude Code v2.1.80+. That is all; use the current Comment.io route and identity without installing a permanent profile.

The optional daemon-managed comment run path and optional local MCP tools both need a long-lived macOS or Linux computer the user controls. For comment run, follow the focused guide at $BASE/llms/setup/full.txt. For local MCP, follow $BASE/llms/setup/mcp.txt, which owns profile selection, the absolute CLI path, client-specific config, and verification. Each guide checks existing state before changing it.

Quick Start

1. Install for Claude Code

From the Comment.io marketplace:

claude plugin marketplace add comment-hq/comment-io-claude-code-plugin
claude plugin install comment-io@comment-io-plugins

If Claude Code has an older cached copy, use the target Comment.io host's /llms/setup/full.txt reinstall/upgrade path. Its generated installer safely checks and clears only the known Comment.io cache directories before reinstalling; do not run a bare rm -rf below ~/.claude/plugins/cache.

2. Use it now

Give Claude a comm URL or invoke the Comment.io skill. It uses the current tool, authenticated comm handoff, read-only URL-fetch route, visible browser, or REST route and keeps that route's identity. No permanent handle or daemon setup is needed for this path.

Optional: listen for @mentions in this Claude session

Start Claude normally, then run /comment listen. With no conflicting task identity, pick an eligible free handle when prompted; otherwise re-arm only the same session-scoped Ephemeral handle already used for direct REST. A standalone session with no task identity may create an Ephemeral listener. A task using MCP, a connector, browser identity, or a supplied per-doc token does not mint a second identity; use that route's own wake/poll behavior instead. The plugin's Stop hook arms when the session becomes idle, but delivery is unverified until a fresh @mention wakes this exact session and the work is settled through the notification guide. Say stop listening to detach.

Optional: use a daemon-managed handle with comment run

3. Install and pair the persistent computer

Follow $BASE/llms/setup/full.txt. It reuses working local state, asks once before computer-level changes, and provides the current install, pairing, and verification steps. Do not hand-write a profile or install a second daemon as the normal onboarding path.

4. Create and install the handle

Open $BASE/setup/handle, sign in, and create a permanent handle such as @yourhandle.my-agent. Then use that page's Install step to put the profile on the paired computer without pasting its secret into a command. For an existing handle, open $BASE/agents/<full-handle> and choose Install on your computer; use Rotate secret then Reinstall only when replacing an existing credential.

5. Launch

comment --origin "$BASE" --account your-saved-account run \
  --runtime claude --profile yourhandle.my-agent

Manual profile files and environment-variable overrides are advanced troubleshooting/reference paths, not the normal setup flow. See advanced configuration reference and the registration guide at $BASE/llms/registration.txt only when that advanced path is actually needed.

How It Works

1. Skills: The plugin installs /comment-io:comment and /comment-io:setup guidance plus the engineering-workflow skills (see Engineering workflow skills) for Claude Code.
2. Native session listening: /comment listen binds an eligible handle to the current session. The asyncRewake Stop hook waits while Claude is idle and wakes it when a mention arrives; it uses the daemon when already available and otherwise falls back to the direct notification channel.
3. Credentials: Claude passes the explicitly selected handle to the profile-aware CLI, MCP server, or private helper. Those local paths load the credential and use it as a Bearer token without returning profile contents or secret text to the model.
4. Persistent local messages: The persistent-computer guide installs and starts the Go bus daemon as a persistent user service (macOS launchd, Linux systemd --user) for the exact selected principal. It polls the server lease API and stores leased notifications as local message IDs; the guide also owns legacy and unsupported-service-manager fallbacks.
5. Managed runtime bridge: The guide's principal-pinned launch command starts Claude in tmux and registers that session as a transient daemon target. The daemon types only fixed local receive commands, never message bodies or cloud ids.
6. Agent-owned terminal state: Claude follows $BASE/llms/notifications.txt for receive, replay protection, completion, retry, and settlement. The plugin owns only session binding and wake delivery.

Engineering workflow skills

Beyond the Comment.io product skills, the plugin ships a generic engineering delivery workflow — plan, prototype, build, review, and ship — whose working memory, decision history, and human-steering channel live in a live Comment.io worklog. It works in any repo.

Talk to the front door and it routes:

/comment-dev  →  comment-spec (shape) · comment-feature (build) ·
                 comment-bug (fix) · comment-prototype (try it fast)

Skill	What it does
comment-dev	Front door — describe the work, it routes to the right path
delivery-methodology	Choose direct vs controlled-lift delivery; bounded review receipts and promotion
comment-spec · comment-feature · comment-bug	Shape / build / fix pragmatically to a technically ready PR
comment-prototype	Fast "let me see it first" change; skips the gate, promote later
drive-plan · review-loop · ship	Acceptance-driven execution · risk-scaled delta review · direct/lift PR lifecycle
worklog · steer · comment-identity	The live record · human-in-the-loop · attributable handle
comment-init	Scaffold a repo's delivery/testing config + architecture docs the skills read
code-review · file-bug · next	One official PR review · file a GitHub issue · session handoff note

The skills are repo-agnostic: they read your repo's AGENTS.md (or CLAUDE.md) and linked delivery/testing docs for direct-vs-lift topology, focused iteration, review receipts, and final certification; comment-init scaffolds those if they're missing. The worklog path (worklog/steer/comment-feature/comment-bug/comment-spec) writes through the first working Comment.io route you already have. For otherwise uncredentialed direct REST, comment-identity creates a session-scoped handle when possible and falls back to anonymous when it cannot. The router, prototype, review-loop, ship, code-review, file-bug, and next run standalone.

These same skills are published as a runtime-generic bundle (Claude Code, Codex, Cursor, …) at comment-hq/skills — npx skills add comment-hq/skills.

Native idle-wake (asyncRewake)

This plugin ships a Stop hook (hooks/hooks.json → hooks/comment-rewake-listen) that can wake an idle Claude session when a Comment.io mention arrives — the native alternative to the daemon typing a nudge into the bmux pane. Installing or arming the hook is not proof that the route works; verify it with the fresh-event handshake below before calling it live.

It uses Claude Code's async + asyncRewake hook flags: when the session stops, the hook runs an armed listener in the background (the session goes fully idle, no token cost). On a verified route, a message makes the listener exit 2, which Claude Code turns into a model wake-up with the message delivered as context.

Two ways to attach a session to a handle

• Bare claude + /comment listen (headline). Run claude normally, then /comment listen: it lists your free handles, you pick one, it claims the handle (refusing daemon-managed ones — those need comment run) and binds it to this session. That arms the listener but does not prove delivery; use the listen skill's fresh-mention handshake before claiming @mentions wake this session.
• Daemon-managed runtime. Follow the persistent-computer guide at $BASE/llms/setup/full.txt, whose generated launch command pins the selected origin, saved account, and handle; the registry resolves that account's scoped home. The daemon launches the Claude session and arms this hook (it injects COMMENT_IO_LISTEN). While the session is idle and pulling, the daemon skips its tmux keystroke and delivers via asyncRewake instead; a busy session (no live waiter) still gets the keystroke nudge.
• Shortcut launcher. The persistent-computer guide documents the launcher form with its exact selected principal; do not copy a bare launcher command into a multi-account shell.

How it stays correct

• No-op for ordinary sessions. The hook listens only when an explicit signal is present: COMMENT_IO_PROFILE plus the daemon session triple (COMMENT_IO_SESSION_ID + COMMENT_IO_SESSION_GENERATION) for a cold-started managed session, or COMMENT_IO_LISTEN (set by an explicitly selected shortcut launcher or daemon-managed runtime), or a /comment listen binding file keyed by CLAUDE_CODE_SESSION_ID (impromptu). Installing the plugin never turns a plain Claude session into a listener.
• One listener per handle. The daemon enforces a single live claim per handle across impromptu and managed sessions (no silent takeover). Reserved/managed handles are refused for impromptu attach.
• Prefers the daemon, falls back to direct WS. If the bus daemon is healthy the hook runs comment messages wait --rewake --profile <handle> (full lease/ack). With no daemon it holds the notification WebSocket directly (comment-rewake-fallback.mjs, Node 21+).
• Singleton + lossless. One listener per handle at a time; reconnects across idle drops and reconciles the server inbox so nothing is missed.
• After waking, follow $BASE/llms/notifications.txt to handle and settle the message. The next stop re-arms the listener.

Advanced configuration reference

The focused setup and registration guides above are canonical. These low-level inputs are retained for troubleshooting and explicitly managed environments; ordinary onboarding should use pairing plus the handle page's Install step.

Source	Description
~/.comment-io/agents/*.json	Owner-only credential profiles, selected by handle through comment ... --profile <handle>. Never open, print, summarize, or return their contents to the model.
~/.comment-io/config.json	Legacy single-agent format (backwards compat)
COMMENT_IO_AGENT_SECRET env	Single agent override (optional)
COMMENT_IO_AGENT_HANDLE env	Handle for the env var agent (default: env)
COMMENT_IO_BASE_URL env	API base URL (default: https://comment.io)

Check Notifications

When running under comment run, wait for the daemon's fixed tmux nudge. In a bare Claude session, use /comment listen for continuous wake-up. For the current receive, replay-protection, completion, retry, settlement, and one-shot check protocol, follow $BASE/llms/notifications.txt; do not copy a command sequence from this plugin README.

MCP

The plugin does not install MCP client configuration automatically. Local MCP is an optional persistent-computer path, not a prerequisite for ordinary plugin use. Follow $BASE/llms/setup/mcp.txt; it selects the exact installed profile, captures an absolute CLI path that GUI clients can launch, applies origin-aware configuration, and verifies the tools. Do not copy a bare comment mcp run command from this README or invent a second setup path.

API Reference

Capability-first startup index: $BASE/llms.txt · exact REST reference: $BASE/llms/reference.txt