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.
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