Comment.io docs

How to work in Comment.io with your team and your agents.

Questions these docs don't answer? Open your account menu and select Help, see the FAQ, or contact support.

Getting started

Comment.io is a shared workspace of documents where your team and your agents work together. This guide takes you from an empty workspace to one your team and your agent use.

Find your way around

Your home opens first. It shows your apps, the documents you opened last, your tables once you have any, and your skills. Under Docs, select All to see every document as folders, or Recent for the ones you opened last. There, check documents or folders, then select Move or Delete to act on them together; a checked folder takes everything in it. A new team's tab shows what to do first above Apps until you're done with it. To rename or delete a skill, point at its card under Skills, open its menu and select Rename or Delete. A document has the same menu wherever it is listed, under Recent or All and on Shared with me: point at it, open its menu and select Open on the right, Edit name, Move or Delete. Where you can’t change it from there, it offers only Open and Open on the right. Open on the right, or ⌘ and a click on a document's name (Ctrl and a click on Windows and Linux), opens it beside Home, which stays on the left. Select Close at the top right of that document to have Home fill the page again.

The tabs at the top filter it: All, My Space, your own space, which only you and your workspace's owners can open, and your teams. The team named after your workspace gets its own tab once you have another team. Shared with me appears once someone shares a document with you. When they don't all fit, the rest are behind the + and a number at the end of the tabs: select it and type to find one. Select New beside Docs for New file, New folder, Upload files or Upload folder, or New app under Apps, to add to the selected team or My Space; on All, it goes in My Space. You can also drag files or folders from your computer anywhere onto Home: they go into the selected team, or on All into your team if you have just one, otherwise My Space. Drop them on a folder's name under All to put them in that folder.

Inside a document, the top left shows where you are, for example Home › Sales › Proposal. Select Home to come back, or the team's name to see that team's home. To add files to a document you can edit, drag them or a folder from your computer onto its text: each goes in on its own line between paragraphs, linked from there. Dropped on an app or any other open file, they go into its team.

Start a team

A team has its own apps, tables and documents. Select New team at the right end of the tabs, name it, for example "Sales", "Hiring" or "Home renovation", and select Create team.

Set up your work

When a team has nothing in it yet and you can add to it, its tab shows the first of two steps above Apps; on All, they show while your workspace has just its one team. This browser keeps your place in them.

  1. Bring in your work. Drop files, folders or a zip on Upload files and folders, or select Choose files or Choose a folder (on a phone, Upload files and Choose files). Or, under Connect your agent, select Copy prompt and paste it into your own agent: it brings in what it already knows about your work. If your workspace has Doc, he turns the files you add into tables and an app; select What should I add to <team>? (with your team's name) to ask him.
  2. Invite your team. Once your work is in, select Invite, type their email address and select Send invite. Select View files to see what you added. While Doc works on your files, Apps shows App on its way; once he's done, select Open beside what he made: your app, or Welcome, a list of your files, when they're all different kinds.

Select Skip beside a step's name to move on; on Invite your team, that ends it. It also goes once you send an invitation from it.

If your workspace has Doc, he's in his column at the left, or at the bottom of the page's left edge when you collapse it. Talk to him there, or select the phone beside Send to call him. Some workspaces don't offer calls: there's no phone beside Send, and you talk to him by typing. In some workspaces Doc starts off: an owner turns him on in Settings, then General, by switching Doc to On. When Doc isn't listed there, your workspace doesn't offer him.

On a call, when Doc asks with choices, he says the question and its choices. Answer aloud, or select them in the chat. If your microphone isn't available, you can keep typing.

Files you add from Bring in your work start Doc: he organizes them in his conversation while you watch. Each kind of document you have several of, such as customer interviews or specs, becomes a table whose items are those documents, with the details you'd want on each, and he makes an app to browse them all, which he shows as a card with Open. Everything else stays in Docs. Tell him if you'd group them differently. When your files are all different kinds, he lists them in a Welcome document instead. He organizes up to 60 files at a time, then asks before going on. He names any files that look sensitive, such as health records or an employee's pay or reviews, keeps them out of tables and apps, and offers to move them to My Space; he tells you to delete any file that holds a password or key. Files you add later don't start him: ask him to organize them. Not sure what to add? Ask him what to add first: he asks what you do, suggests a few kinds of files, and shows a card where you select Add files to pick them, or Not now to close it.

When Doc asks with choices, select one to answer. Where you can choose several, select each one you want, then select the button below them; a check shows on each choice you selected, and selecting one again unselects it. To answer differently, type your answer in the field below the choices instead.

Your own agent does the same with the setup prompt: it asks which folder to bring in if you didn't say, then brings in your files, organizes them the same way and tells you what it made, naming any files that look personal.

Work just for you goes in My Space.

New to Comment.io and joining a workspace that's already set up? Your home shows Welcome to and your workspace's name, with things to try: Connect your agent (select Copy prompt and paste it into your agent), Talk to Doc if your workspace has him (select Ask Doc), and Invite your team (select Invite, type their email address and select Send invite). Each shows a check once you've done it. It stays until you select Hide, have done each one, or start a team of your own; then it doesn't come back, in this workspace or any other. Select Ask Doc and he shows you around: he tells you what each team keeps and points you to what matters for your work.

Connect your agent

Your agent works for you: it can open and change what you can, and nothing more.

  1. Open your account menu and select Settings, then Agents.
  2. Select Copy setup prompt.
  3. Paste the prompt into Claude Code, Codex or any other agent.

The agent connects the best way it can and tells you what to approve. Connect your agent has the details.

Invite your team

Open Settings, then People, type an email address into Invite by email and select Invite. They get an email to join, and can connect their own agents too.

To invite someone straight to a document, open it and select Share (or Invite) at the top right. Share files and invite people has the details.

Log in with your company account

Comment.io offers single sign-on (SSO), so your team logs in to your workspace with your company account. Your workspace can also require it for everyone with your company's email address; guests keep their usual way to log in. To set it up, email support@comment.io.

Once it's set up, open your workspace's address and select Continue with SSO, in a browser or in the Comment iPhone and Mac apps. If the app asks you to update it, update Comment first. New colleagues open their invitation first, unless your workspace lets them join by logging in.

Work with a table

On Home, Tables first shows the tables you work through yourself, such as deals or candidates; your agent chooses them as it makes your tables, so ask it to change them. The rest are behind a button beside Tables that counts them, such as 2 more, or Show 2 when none show first: select it to show them, and Fewer or Hide to fold them again. Each tab of Home remembers this in this browser. When all of a tab's files have become items, Docs says Your files are in Tables.: select Tables there to go to them. Select a table, or open an item and select its table's name above its title, to see every item in the table. Type in Find by name to find one, or select a column heading to sort by it. Select an item's name to open it.

If you can edit the table, select New item, type its name and select Add; the new item opens. Select Edit Table Definition to change the table's properties and the text every new item starts with, then select Done editing to see the items again. Select Move table to move the table and its items to another team. To move or delete one item, open the menu beside its name.

Work together

  • Ask your agent to build an app for whatever your team tracks, then publish it to the people who need it.
  • Select text in a document to comment on it or suggest an edit.
  • Open Catch up at the top right to see what changed since you last looked: Mentions shows your notifications, such as when someone @mentions you, and Recent changes what others changed in files you edited, commented on, created, opened or caught up on recently.
  • Select Search everything, or press ⌘P (Ctrl+P on Windows and Linux), to find a file by its name or its text.

Connect your agent

Connect Claude Code, Codex or any other agent to your workspace, so it can read and change your documents for you.

Connect an agent

  1. Open your account menu and select Settings, then Agents.
  2. Under Connect an agent, you can type the name the agent goes by in the workspace. Leave it empty to let the agent choose.
  3. Select Copy setup prompt and paste the prompt into your agent.

The agent picks the best way to connect it can use: MCP if your agent supports it, then SSH, then the HTTP API. It tells you what to approve. When it gives you a link, open it while logged in to Comment.io and approve the agent.

If the agent asks you for an API token, select Create one under the setup prompt, then give the token to the agent. It's shown only once.

What your agent can do

An agent works for the person who connected it. It can open and change exactly what you can, and its comments and edits show its own name, so everyone can see what it did. Ask it what's new and it reads your Recent changes list. When you leave a workspace, your agents leave with you.

Agents read their own guide at llms.txt. You can give that address to any agent to get it started.

Let an app work as any member

In workspaces where Comment.io has turned this on, owners see Settings → Admin → Integration token. Select Make token and give the token to an app, such as a team chat bot, so it can work as any member of the workspace, with that member's access. What it does shows as that member's agent, named from Agent name on the same page: "{name}'s Agent" until an owner changes it, where {name} becomes the member's name, for example "Ada's Agent". Changing it, or a member changing their own name, renames their agent at once. These agents aren't listed under Connected agents.

The token is shown once. Make new token replaces it and Revoke token ends it; either way, every app using the old token stops working at once. The token keeps working even if the owner who made it leaves.

Manage your agents

Settings → Agents lists the agents connected to the workspace under Connected agents. Open the menu on one of yours to:

  • Upload photo or Change photo, so its comments and edits are easy to spot.
  • Create API token or Roll API token, to give it a new token. Rolling replaces the old one.
  • Add SSH key, for an agent that connects over SSH.
  • Disconnect, to remove its access.

Tell agents how to work in a team

Each team has a description and instructions that agents read before working in it. Open the team's settings from the gear beside its name, then select Description or Agent instructions to edit them. My Space has its own description and instructions too.

Build apps

An app in a team or personal space does whatever you need: a pipeline board, a dashboard, an intake form, a tracker, a calculator or a small website. Your agent builds it for you. It reads and changes the tables where it lives as people use it, and you can publish it to people who can't open the rest, so they see only what the app shows.

An app can be anything

An app is a web page, made of HTML, CSS and JavaScript, so it can look and work however you want. An app can:

  • Show its team's or personal space's tables as a board, a chart, a map or a table of its own, and update by itself when anyone, person or agent, changes an item.
  • Change items as you use it: tick off a task, move a deal to its next stage, or add an item from a form.
  • Show the images and files your items name.
  • Let people upload files into its team or personal space.
  • Follow your Light or Dark setting.

To bring in a website you already have, select Home, choose a team or My Space, then select New beside Docs, then Upload files. Choose its .zip and select Expand. Its pages become apps.

Create an app

  1. Select Home at the top left, choose the team's tab, then select New app under Apps. On All, the app goes in My Space.
  2. In New app, give it a name, such as Pipeline. Keep the drawn icon or select Change icon to choose another drawing or Upload a picture. You can add a short description of what it's for. Then select Create app.
  3. An empty app opens. Tell your agent what you want it to do, and it builds the app there. If your workspace has Doc, Doc opens and asks what you need.

You can also just ask your agent, for example: "In Sales, build an app that shows every open deal by stage and lets me move a deal to its next stage."

Apps, on your home, shows the apps in every team you're in and in My Space, then the apps published for you. Choose a team's tab to see only its apps. To rename, move or delete an app, point at its card and open its menu , then select Rename, Move or Delete. A new name saves when you press Enter or click away; press Esc to keep the old name. You need to be able to edit a team or My Space to add, rename, move or delete its apps.

Describe an app

On a team's tab of Home, an app's description shows under its name; on All, which shows its team there, rest the pointer on its card to read it, as you do when a long description is cut off. Give it one when you create the app, in New app, or later: point at its card and open its menu , then select Edit description, and type what the app is for. It saves when you press Enter or click away; press Esc to keep the old one. A description is one line of up to 200 characters; empty it to remove it. If someone else changed it while you were typing, you see theirs instead; edit it again to replace it. You need to be able to edit the app's team or My Space to describe it.

Change an app's icon

Point at the app's card on Home, open its menu and select Change icon. Choose a drawing, Default (a drawing that matches the app's name, when a word in it has one), or Upload a picture to use your own; a picture is cropped to a square. Your choice saves at once. Drawings are Multicolor to start, each in its own color; to draw them all in one color, choose the color above the drawings first, then the drawing. You need to be able to edit the app's team or My Space to change its icon.

Who can use an app

Everyone who can open a team or personal space can open its apps. An app works as the person using it: it shows each person only the items they can see, and changes items only for people who can edit there.

If an owner turned on Ask before apps change items in Settings, then General, under Apps, the first time an app tries to change items for you it asks Allow NAME to create and change items as you? Select Allow, then try again.

Share an app

If Publish changes to apps immediately is off and you can edit the app, use Publish an app instead. Apps in the team everyone is in still use Share.

  1. Open the app and select Share at the top right.
  2. If Approve appears, check What can this app see? and select Approve. Only an Editor of the app's team can approve it.
  3. Enter a name or email address, keep Can view and select Share. Someone who isn't in the workspace yet is invited to it.
  4. To let everyone in the workspace use it, set General access to Can view. Restricted keeps it to the people added.

Giving Can comment or Can edit adds the person to the app's team at that level. Apps in My Space can only be shared to view. To take someone's access away, open the menu beside their name and select Stop sharing.

Publish an app

If your workspace doesn't share single files, or Publish changes to apps immediately is off, apps are published instead. Publish an app to let people use it without opening its team or personal space, such as an app in a restricted team or in My Space. They see the app, and nothing else where it lives. Apps in the team everyone is in, which has your workspace's name, are already open to everyone, so they have no Publish button.

  1. Open the app and select Publish at the top right.
  2. Keep Everyone in your workspace, or set it to No access and add people by name or email. Someone who isn't in the workspace yet is invited to it.
  3. Select Publish.

The button then says Published. Select it to change who can use the app, to Copy link to it, or to Unpublish it.

If something in the app stops it from being published, the panel says what. If your workspace has Doc, select Fix it for me. Otherwise select Copy prompt and send it to your agent.

Only someone who can edit the app's team or personal space can publish it. In Settings, Published apps lists the published apps you can manage, with who can use each one.

What a published app shares

An app asks the tables in its team or personal space fixed questions, called queries, written in the app. When you publish an app, you approve its queries. The people you publish it to can read, but not change:

  • The app itself.
  • Every item its queries can return, and the files attached to those items.
  • Totals: a query that counts or adds up items gives them the total, not the items behind it.

They don't see comments, history or anything else in the team or personal space. A query can ask who is using the app, so it can show each person only their own items. If the app has a search box, people can read every item a search could find, not only the ones on screen. To check what an app shares before you approve it, select What can this app see? in Share, or What data is being published? at the bottom of the Publish panel.

An app reads the tables of only its own team or personal space and the team everyone is in. If your workspace has connectors, an app can read from them too: each person connects their own account and reads what that account can. Connect yours in Settings, under My Connectors. Workspace owners add connectors and choose the tools apps may use under Connectors Settings.

When Doc or your agent suggests a connector

Doc or your own agent can suggest a connector by showing you a link or a Review button. Opening it shows the connector's website and what adding it means; nothing is added until someone chooses to.

  • If you're not an owner, select Ask an owner. Your request waits in My Connectors until an owner answers; open its menu to withdraw it.
  • If you're an owner, a number next to Settings in your account menu shows open requests. In Connectors Settings, open the Asked by menu next to one to review or dismiss it. Select Add to add the connector, then connect your account to see its tools. Tools that can only read are picked for you; tools that can change information can't be picked.

Doc can't use a suggested connector until an owner selects Let Doc use on its page. From then on, the connector sees what Doc asks it, and anything Doc writes into a shared document is seen by that document's readers.

Keep a published app up to date

People always see the items an app shows as they are now. With Publish changes to apps immediately on, changes to the app itself reach them too, shortly after you make them. It's on unless an owner turns it off in Settings, then General, under Apps. With it off, people keep the app and queries as you last published them. When you've changed it, the button at the top right says Publish changes; select it, then Publish. Once people have the latest version it says Published.

Even with it on, a change to the app's queries waits for approval when it stops the app from being published, or when the person who published the app can no longer edit its team or personal space.

Use an app published for you

Select Home, choose All, then select the app marked Shared with me, or open the link someone sent you. Select a link to an item in the app to read the item, and Back to the app to return.

What your agents see

Agents work with your workspace as plain files, and with apps too:

  • An app is an HTML file in its team's or personal space's apps folder, for example sales/apps/pipeline.html. Your agent reads and edits it like any other file. Comment.io may refuse an edit that copies what a connector returned into an app, because everyone who opens the app would see that copy. Ask your agent to read the data live instead, so each viewer sees their own. If you want a fixed copy, first make sure everyone who can open the app should see it, then tell your agent to keep the copy.

  • Each table's Table Definition is a Markdown file in its team's or personal space's definitions folder, for example sales/definitions/deal.md.

  • Each item is a Markdown file in its table's folder, for example sales/things/deal/acme.md, with its properties at the top. Your agent reads items with its usual tools, and asks questions across a table in SQL with thing-query, as an app does:

    SELECT name, stage, owner.name FROM Deal WHERE stage = 'lead' ORDER BY name
    
  • An app's queries are written in its HTML file, each with a name, in a <script type="application/commentio-queries"> block. The app runs them with commentio.app.query, or commentio.app.watch to keep the results up to date. These named queries are what you approve when you publish the app.

  • An app published for you from a team or personal space you can't open appears to your agent as a read-only folder, apps/APP, laid out like the team or personal space. It holds only what the app shares with you: the app itself, the items it can return and their files. Your agent can search that folder and run the app's queries by name with app-query.

  • If you can edit a team or personal space, your agent can list its published apps with app-list, and check what an app would share with app-review before you publish it. Publishing, choosing who can use an app and unpublishing it are yours to do in the browser.

Agents can see and do only what you can. Their own guide to these commands is Run workspace commands.

Comments and suggested edits

Discuss any part of a document with comments, and propose changes as suggested edits that the document's editors accept or reject. People and agents use both the same way.

Comment on a document

  1. Select the text you want to talk about.
  2. Select Comment in the menu that appears, or press ⌘⌥M (Ctrl+Alt+M on Windows and Linux).
  3. Write your comment and select Comment.

Type @ and a name to mention someone. They get a notification.

Comments appear beside the text they're about. Reply to keep the conversation in one thread, and select Resolve when it's settled.

Resolving a comment takes its notifications out of everyone's Mentions in Catch up. A link in an earlier email still opens it, read-only, marked resolved. Select Reopen to pick the conversation up again; its notifications come back.

Suggest an edit

  1. Select text and select Suggest edit, or press ⌘⌥S (Ctrl+Alt+S on Windows and Linux).
  2. Type your change. While Suggest edit is on, your changes are kept as suggestions instead of changing the document.
  3. Select Suggest edit again to stop suggesting.

You can suggest edits in Markdown (.md) documents.

Each suggestion shows beside the text with what it would change. Anyone who can comment can discuss it under Comment on this suggestion.

Accept or reject a suggestion

If you can edit the document, select Accept to apply the change or Reject to drop it. Rejected one by mistake? Select Undo in the message at the top of the page within 10 seconds to bring it back. If you suggested it but can't edit the document, you can Withdraw it.

Who can comment

What you can do depends on your access to the team or personal space:

  • Viewer: reads.
  • Commenter: also comments and suggests edits.
  • Editor: also changes files, and accepts or rejects suggestions.

If someone shares one document with you, Can view lets you read it, Can comment also lets you comment and suggest edits, and Can edit also lets you change it, without joining its team or personal space.

Catch up on changes

See what people and agents changed in your files since you last looked, and who changed them, then step through each change and comment on it.

Open Catch up

Select Catch up at the top right. Mentions shows your notifications; Recent changes lists your files where someone else has changed something or left a comment or suggestion you haven't seen: files you edited, commented on, created, opened or caught up on recently. A red badge counts unread notifications in Mentions, and a blue badge counts updates in Recent changes. If only one tab has something new, it opens first; otherwise Mentions does.

In Recent changes, each file reads like a short briefing: who changed it and what they changed, such as "Ana raised the seat limit to 75." While a summary is being written, it says "Ana made changes · Summing up…". It stays "Ana made changes." when there's no summary, such as when a workspace owner has turned off Allow file processing or Summarize changes in Settings > General. Turning either back on sums up only edits made after it. The newest three changes show in full, and older ones are summed up as "Earlier, Jonah made changes." Under them you see the file's folder, when it last changed, and how many comments or suggestions you haven't read. Changes that leave nothing to see aren't listed, and Catch up skips them: text added and removed again while the file was being worked on, with no break of 10 minutes or more between edits, and changes to spaces and blank lines alone. Changes show once whoever made them has finished. If someone else is still editing the file, changes made since they started show once that person or agent has finished too. For the document you're in, you see changes right away, along with who is editing now, and it comes first in the list. When an agent edits many of your files at once, they show as one entry under the team's name, such as Sales: "Doc edited 23 of your files." Select a file there to open it with Catch up.

Select Mark all as seen to clear the whole list, including files beyond the ones shown. With nothing new, Recent changes says you're all caught up.

To catch up on one file:

  1. Select the file in Recent changes. The document opens with Catch up beside it, starting at the top of the document: for each change it shows who made it and when, and highlights the text.
  2. Select Next to go to the next change or comment, and Previous to go back. Once you've selected Next, pressing Tab also goes to the next one.
  3. When you've seen everything, Catch up says so, and the file leaves Recent changes when you close Catch up or go to another file or page. If a change listed in Recent changes has nothing left to show, Catch up tells you what the list said instead, above any open comments.

Respond to a change

Under a change, write in Add a comment and select Comment. The comment mentions the change's authors, so they're notified, whether a person or an agent. To undo a change, edit the text yourself or suggest an edit.

Ask your agent what's new

A connected agent sees the same Recent changes list you do. Ask it what's new, or what changed while you were away, and it tells you which files someone else changed, who changed them, and which comments or suggestions you haven't read. Asking it doesn't mark anything as seen.

Options

Open the menu at the top of Catch up to turn on:

  • Comments only, to step through comments and skip changes.
  • Show removed, to also see what was deleted where text was replaced. Text that was only deleted always shows.

Select to close Catch up.

Share files and invite people

Invite people to your workspace, choose which teams they can open, and share single documents with people who aren't in a team.

Invite people to your workspace

Open your account menu and select Settings, then People. Type an email address into Invite by email and select Invite. Pending invitations show in the list, where you can Resend invitation or Cancel invitation.

To share a document with someone, open it and select Share at the top right. Choose the access to give, enter their name or email address and select Share. Someone outside the workspace is invited and gets the document when they join. If the team keeps its files to its people, the button says Add instead, and adds them to the team.

Copy link copies the document's address. It works only for people who can already open it.

If your workspace doesn't share single files, the button says Invite: type their email address and select Send invite. They join the workspace and start on that document. If the team is limited to some people, only a workspace owner can invite someone new to it. Copy invite to doc copies a link to the document; the note under it says who the link works for.

Choose who can open a team

Workspace owners choose who can open each team. Open the team's settings from the gear beside its name and find Access. At first, everyone in the workspace is an Editor of a new team.

To choose who can open it, set Everyone in your workspace to No access. Then only owners and the people you add can open it. Add each person as a Viewer, Commenter or Editor:

  • Viewer: reads.
  • Commenter: also comments and suggests edits.
  • Editor: also changes files.

Each person's agents can open no more than they can. To keep something private, create a new team and restrict it before you add anything to it.

The team everyone is in has your workspace's name. It can't be restricted: owners choose what everyone can do in it instead. My Space is your personal space, open only to you and the workspace's owners.

Share one document

In some workspaces, anyone in a team can share a single document with someone in the workspace without giving them the whole team, at up to their own level there: editors can give Can view, Can comment or Can edit, commenters Can view or Can comment, and viewers Can view. Someone a document was shared with can't share it on; they ask the person who shared it. You can also share a document from My Space without giving access to the rest of your personal space.

  1. Open the document and select Share.
  2. Choose Can view, Can comment or Can edit. Clear Notify people if you don't want to tell them.
  3. Type their name or email address and choose them from the list. The document is shared as soon as you choose them.

To remove someone, open the menu beside their name and select Stop sharing. You can stop shares you made; the team's editors and the workspace's owners can stop anyone's.

In a restricted team, an owner can turn on Only people in this team in the team's settings, under File sharing. People outside the team then can't open its shared documents until it's turned off again.

Ask for access

If a link opens You need access, select Request access. If you aren't in that workspace, your email address is shared with the people who can give you access, and you'll get an email if someone shares it with you; follow its invitation to join. Select Continue to your workspace to carry on meanwhile.

Answer a request for access

Workspace owners, and the editors of the file's team, see requests under Mentions in Catch up. Choose the access to give, up to your own, then select Share, or Decline. Someone outside the workspace is shown by their email address: Invite and share invites them, and the file is shared with them when they join.

If you're a workspace owner, someone may ask for access to a link with nothing at it. The request appears under Mentions in Catch up with their name or email address, the path they asked for, and "Nothing is at that link." Only owners see these requests. Select Dismiss to answer it; there is nothing to share.