Use Comma with Claude Code

Comma ships an official Claude Code plugin. One install line attaches the MCP server and registers four slash commands — /comma-publish, /comma-search, /comma-routine, /comma-link — under one scoped token you control.

Install

curl -fsSL https://commareports.com/install.sh | bash

(Windows PowerShell: iwr https://commareports.com/install.ps1 -useb | iex.)

The script installs the plugin (the hosted Comma MCP server plus the slash commands), opens the token page in your browser, and asks you to paste a comma_sk_… token. It checks the token against the API, saves it to ~/.config/comma/env, and offers to load that file from your shell rc — Claude Code reads COMMA_API_TOKEN from the shell it starts in. Then restart Claude Code and say "publish this as a Comma report".

No terminal to paste into (CI, a container)? Pass the token in: curl -fsSL https://commareports.com/install.sh | COMMA_API_TOKEN=comma_sk_… bash.

For the published plugin marketplace entry, see doramirdor/comma-plugin.

Free · no card

Got an HTML report from your agent?

Drop it here to see it on a link your team can comment on. Then connect the plugin and your agent publishes it for you.

Your file is read in this tab and nothing is uploaded until you publish. Creating an account is free, and reading a shared link never needs one.

Slash commands

/comma-publish

Publish the current document or a generated HTML artifact as a new Comma report. Returns the share link.

/comma-publish report.html

Useful at the end of an agentic task: "summarize this quarter's data and publish it to Comma." The agent fetches the data, generates the HTML, and calls /comma-publish to land it in your workspace.

/comma-search

Search reports in your workspace by name or content.

/comma-search "weekly analytics"

Useful at the start of a task: "find the latest weekly analytics report and update its conclusions." The agent uses /comma-search to locate the report, then get_report (over MCP) to read its current content.

/comma-routine

Create or modify a scheduled routine attached to a report. The routine re-runs an underlying skill on a cron and posts the new HTML as a revision.

/comma-routine create --report rpt_… --cadence daily --skill ./eval.md

Useful for the "make this report refresh itself" follow-up: once a report shape is stable, ask the agent to schedule it.

/comma-link

Insert a markdown link to an existing Comma report into the current document or message — handy for referencing prior work without copying its HTML.

/comma-link rpt_…

What the agent can do directly over MCP

Beyond the slash commands, the plugin exposes the full MCP toolset to the agent's reasoning. Without any slash command, Claude Code can:

  • Publish — create_report, update_report
  • Read — list_reports, search_reports, get_report, read_report
  • Comment — add_comment, reply_to_comment, set_comment_status, list_comments
  • Review — request_review
  • Assets — upload_report_asset, list_report_assets, delete_report_asset

This means the agent can carry out a full task — fetch context from prior reports, run its analysis, publish the new output, request review, and reply to comments on a follow-up turn — under one scoped token.

Common workflows

Publish a generated report at the end of a task

> Run the weekly product analytics summary and publish it.

[agent runs the skill]
[agent generates HTML]
[agent uses /comma-publish to land the report]

Done. Report is at https://commareports.com/r/rpt_….

Pick up where reviewers left off

> Look at last week's analytics report and address the open comments.

[agent uses /comma-search to find the report]
[agent calls list_comments]
[agent reads the unresolved threads]
[agent updates the report and replies to each comment with what changed]

Schedule a report you just shipped

> Schedule this report to refresh every Monday morning.

[agent calls /comma-routine create with cadence=weekly]
[agent confirms the routine is wired and the next run is queued]

Token shape

The installer asks for a comma_sk_… token and won't save one the API rejects. Generate one in Settings → API tokens with the scopes you want — typically reports:write and comments:write, plus routines if you want the agent to schedule things.

Revoke at any time from the same screen. Revocation is immediate and applies to the REST API, the MCP server, and any routines created under that token.

What stays out of scope

  • No code execution. The plugin does not execute arbitrary code on Comma's infrastructure. The agent runs on your machine; Comma is where the report lands.
  • No data warehousing. The skill the agent runs is responsible for fetching its own data. Comma is the publish target, not a data layer.
  • No general-purpose Slack/email posting. Comma posts to a Comma report. Cross-posting to other surfaces is the agent's job, not the plugin's.

Try it

Install, generate a token, ask Claude Code to publish anything you have lying around as HTML. Once it's in Comma, leave a comment via the web UI and ask the agent what it sees.

Install the plugin →

Related

Have an HTML report to share? Publish it free and send one link people can comment on.