--- title: "Comment.io docs" description: "How to work in Comment.io with your team and your agents." canonical: "https://comment.io/docs" last-updated: 2026-10-19 --- # Comment.io docs How to work in Comment.io with your team and your agents. Questions these docs don't answer? See the [FAQ](https://comment.io/faq) or [contact support](https://comment.io/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. ## Start your first project Everything in a workspace lives in a project: its home page, its lists and its files. The first time you open your workspace, name your first project, for example "Sales", "Hiring" or "Home renovation", and select **Create project**. To add another project later, open the project picker at the top left and select ![](https://comment.io/site-images/icons/PiPlusDefaultStroke.svg) **New project**. ## 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](https://comment.io/docs/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 ![](https://comment.io/site-images/icons/PiUserPlusStroke.svg) **Share** (or **Invite**) at the top right. [Share files and invite people](https://comment.io/docs/share-and-invite) has the details. ## Work together - Ask your agent to [build an app](https://comment.io/docs/apps) 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](https://comment.io/docs/comments-and-suggestions). - Open ![](https://comment.io/site-images/icons/PiReminderAnticlockwiseStroke.svg) **Catch up** to [see what changed](https://comment.io/docs/catch-up) since you last looked. - The bell ![](https://comment.io/site-images/icons/PiNotificationBellOnStroke.svg) at the top right shows your notifications, such as when someone @mentions you. - Select ![](https://comment.io/site-images/icons/PiSearchDefaultStroke.svg) **Search files**, 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. When you leave a workspace, your agents leave with you. Agents read their own guide at [llms.txt](https://comment.io/llms.txt). You can give that address to any agent to get it started. ## 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 project Each project has a description and instructions that agents read before working in it. Open the project's settings from the gear ![](https://comment.io/site-images/icons/PiSettings02Stroke.svg) beside its name, then select **Project description** or **Agent instructions** to edit them. # Build apps An app is a page in a project that does whatever your team needs: 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 project's lists as people use it, and you can publish it to people who can't open the project, 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 the project's lists as a table, a board, a chart or a map, 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 the project. - Follow your Light or Dark setting. To bring in a website you already have, upload a .zip of it to the project's **Docs** and select **Expand**. Its pages become apps. ## Create an app 1. Open **Apps** in the bar at the top and select ![](https://comment.io/site-images/icons/PiPlusDefaultStroke.svg) **New app**, or select ![](https://comment.io/site-images/icons/PiPlusDefaultStroke.svg) **New**, then **App**. 2. 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." A project's Home can be an app too. **Apps** lists the apps in every project you can open, the one you're in first, then the apps published for you. To rename, move or delete apps, open **Apps** and select ![](https://comment.io/site-images/icons/PiSettings02Stroke.svg) **Manage apps**. You need to be an Editor of a project to add apps to it. ## Who can use an app Everyone who can open a project 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 the project. 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. ## Publish an app Publish an app to let people use it without opening its project, such as an app in a restricted project or in My Space. They see the app, and nothing else in the project. Apps in the project everyone shares, marked **Common** in **Projects**, are already open to everyone, so they have no **Publish** button. 1. Open the app and select ![](https://comment.io/site-images/icons/PiUploadUpStroke.svg) **Publish** at the top right. 2. Under **Who can use this app**, 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 ![](https://comment.io/site-images/icons/PiCheckTickCircleStroke.svg) **Published**. Select it to change who can use the app, to ![](https://comment.io/site-images/icons/PiLinkChainSlantStroke.svg) **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 an Editor of the app's project 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 project's lists fixed questions, called queries, written in its page. 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 project. 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 publish it, select ![](https://comment.io/site-images/icons/PiInformationCircleStroke.svg) **What this app can see** in the **Publish** panel. An app reads the lists of only its own project and the project everyone shares. If your workspace has connected services, an app can read from them too: each person connects their own account and reads what that account can. ## 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 page and queries you published, and the button says **Publish changes** until you publish again. Even with it on, a change to the app's queries waits for **Publish changes** when it stops the app from being published, or when the person who published the app can no longer edit its project. ## Use an app published for you Open **Apps** and choose the app under **Published for you**, 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 project's `apps` folder, for example `sales/apps/pipeline.html`. Your agent reads and edits it like any other file. - Each item is a Markdown file in its list'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 list in SQL with `thing-query`, as an app does: ```sql 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 `