Comb
Review agent-written agent-fs files in the dashboard: comment on passages, mention teammates, send comments to the swarm, and review the changes
Comb shows the swarm's agent-fs drive inside the dashboard. Humans open files that agents wrote, comment on passages, and mention teammates. Send to swarm gives the open comments to the lead as one task. The agent answers with a new file version and a reply. The human reviews the diff and resolves the thread.
Comb reads and comments only. Humans do not edit files in Comb. A revert to an earlier version is the only change that a human makes to file content.
Requirements
- An agent-fs server that the swarm uses (
AGENT_FS_API_URL). See agent-fs co-deployment. - agent-fs 0.15.0 or later for the full feature set. The dashboard reads the
featureslist from agent-fs/healthand hides the parts that the server does not support. - Object versioning on the agent-fs S3 bucket, for Review changes and Revert. The Docker Compose files enable it on their MinIO bucket. The agent-fs local storage backend always keeps versions.
| agent-fs feature | What it adds | Without it |
|---|---|---|
comment-path-prefix | The Open comments panel of a folder (send and resolve in bulk) | The folder panel does not show |
drive-members | Author names, and the member list for the mention picker | Authors show as a short user id. The mention picker does not show |
comment-mentions | @name mentions and the Mentions list in the notification bell | The picker and the Mentions list do not show |
change-stream | Live updates (the header shows Live) | Comb checks for changes every 10 seconds (the header shows Polling) |
agent-fs 0.14.0 still works: Comb shows files and comments, and every other part in the table hides.
Turn on Comb
Comb needs AGENT_FS_API_URL. With COMB_ENABLED unset, Comb is on when the browser has an agent-fs address: AGENT_FS_PUBLIC_URL (direct browser access), or the API's /agentfs proxy at <public API URL>/agentfs (AGENT_FS_PROXY, on by default with AGENT_FS_API_URL). With AGENT_FS_PROXY=false and no AGENT_FS_PUBLIC_URL, Comb stays off until you set COMB_ENABLED=true. COMB_ENABLED=false turns it off. There is no check that a browser can open the address.
When Comb is off, GET /status reports why in agent_fs.comb.reason.
Set these on the API server, in Settings → Configuration or in the deployment environment:
| Key | Value |
|---|---|
COMB_ENABLED | Optional. false turns Comb off. true turns it on when AGENT_FS_API_URL is set. Unset, Comb is on when AGENT_FS_API_URL is set and AGENT_FS_PUBLIC_URL or the proxy gives the browser an address. |
AGENT_FS_PUBLIC_URL | Optional. The agent-fs URL that browsers use directly. Unset, browsers go through the API proxy (<public API URL>/agentfs). |
APP_URL | The dashboard URL. Slack messages and lead prompts link to Comb only when it is set. |
AGENT_FS_PROXY | Optional, on by default when AGENT_FS_API_URL is set. The API serves agent-fs at /agentfs, so the browser reaches agent-fs through the API and agent-fs needs no public port. Comb uses <public API URL>/agentfs when AGENT_FS_PUBLIC_URL is blank. false turns the proxy off. Comb then uses AGENT_FS_API_URL itself, and it is on only with AGENT_FS_PUBLIC_URL or COMB_ENABLED=true. See Bundled agent-fs behind the swarm API. |
A saved value reloads the API. The dashboard reads the new state on its next status poll, 30 seconds at most. The sidebar then shows Comb, and /file opens the swarm drive.
The swarm drive is the shared org and drive that the API provisions in agent-fs (AGENT_FS_DEFAULT_ORG_ID, AGENT_FS_DEFAULT_DRIVE_ID). Comb shows only this drive.
Connect
Each browser gets its own named agent-fs key, with no click. The swarm API key does not give access to agent-fs files.
- Open Comb (or any
/file/~/...link). With no saved key, or a saved key that agent-fs rejects, the dashboard asks the swarm for a key:GET /api/fs/memakes your agent-fs account and drive membership ready, andPOST /api/fs/keysmints a key labeled likeSwarm dashboard · Chrome on macOS · 2026-11-04. - The dashboard saves the key in this browser only. The swarm returns it once and stores none of these keys.
- The dashboard tries this once per page load, so a key that agent-fs keeps rejecting never mints in a loop. Use Retry or Create a key for this browser to try again.
The key is scoped to the swarm's shared org. You see and revoke your keys by label in agent-fs (Manage keys in agent-fs in the account menu). Forget this browser's key removes the key from this browser, and the next visit mints a new one. A key that a browser already holds (pasted or created before) keeps working.
On a new install, the Files step of /setup does the same. The step shows only while Comb is on.
When the swarm cannot make your account ready (for example an agent-fs AGENT_FS_REGISTER_ALLOWED_DOMAINS rule refuses your email), Comb shows the reason with Retry. With an agent-fs older than 0.18.17 (no named keys, POST /api/fs/keys answers 501), Comb shows the old paste-key form with an upgrade hint: paste an agent-fs key (af_...), and the swarm invites that account to the drive when it has no access.
An existing drive member keeps their role. A viewer can read files and comments but cannot comment. When a viewer tries, Comb shows "You have view-only access".
Browse
The left panel has three tabs: Files (the drive as a tree), Recent, and Favorites. It stays as you leave it while you open files. The right panel has Comments and, for a markdown file with headings, Outline. A folder opens as a grid of its files. Each file shows one icon for its kind (markdown, image, audio, video, PDF, HTML, code, data, table, archive). Comb shows these file types in the page:
- Markdown, rendered.
- Code and other text files, with line numbers.
- HTML files as source code, with a Preview tab (see HTML preview).
- PDF, images, video, and audio (mp3, wav, flac, aac, m4a, ogg, opus).
- CSV and TSV files as a table, with a Source view.
Other files show Download and Open in agent-fs.
Find files
- Filter files on top of the Files tab narrows the tree to the files whose names match, across the whole drive (the agent-fs
findop, the best 50). Type 2 characters or more. Escape clears it. An agent-fs withoutfindfilters the folders the tree has loaded. - Filter this folder in a folder header keeps the folder's own items whose names hold every word you type, and lists matching files in its subfolders under them. The filter is in the URL (
?filter=), so you can share it, and Back brings it back.
File menu
Hover a row in the tree and click ..., or right-click a row in the tree or the folder grid (a long press on a phone). The same menu is under ... in a file header:
| Item | Does |
|---|---|
| Open, Open in new tab | Opens the file or folder in Comb |
| Copy link, Copy path | Copies the Comb link, or the drive path (/docs/plan.md) |
| Copy contents | Copies a file's text (text, code, markdown, CSV, JSON, YAML, SVG up to 1 MB). Any other file shows why with Download instead |
| Share... | Makes a share link (files, see Share links) |
| Add to favorites | Stars it (see Home, Recent, and Favorites) |
| Download | Downloads the file |
| New file..., New folder... | Creates one in the folder. A name like notes/todo.md also makes the folders. A new folder holds an empty .keep file. |
| Rename... | Renames or moves the file (edit its full path). agent-fs writes it as a new version at the new path. Its stars move with it. The old path keeps its history and its comments. |
| Delete... | Deletes the file. Its versions are kept (agent-fs revert brings it back). Its comments are removed. |
| Open in agent-fs | Opens it in the agent-fs live UI |
New, Rename, and Delete use the agent-fs write, mv, and rm ops, like the live UI, and need the editor role in the drive. A name in the tree that does not fit shows in full on hover. Copy path is also an icon in each folder header. In a file header, the copy icon copies the file's contents, and hovering it shows Copy path. A file that is not text, or is larger than 1 MB, does not copy: hovering or clicking the icon says why and offers Download instead. The same check runs on the loaded bytes, so a file that turns out binary or larger than 1 MB gets the same offer.
Search
Click the search icon in the header, or press /. Pick a mode, or press Tab and Shift+Tab to move between them:
| Mode | agent-fs op | Finds |
|---|---|---|
| File | find | File names, close matches too. Needs 2 characters and agent-fs 0.18.5 or later. |
| Semantic | search | Files about the topic, by meaning and keywords. Without an embedding provider, agent-fs returns keyword results only. |
| Text | fts | The exact words inside files. |
Search covers the whole swarm drive. Image results show a small preview. Enter opens the selected file. The search is in the URL (?q= and ?mode=): share the link to share the search. Back closes it, and Back from an opened result shows the search again.
Share links
Share link in the file header makes a public, read-only link to the file (the agent-fs share-create op). Pick how long it works: 1 hour, 24 hours, 3 days, or 7 days. Comb copies the link. Anyone with the link can open the file without an agent-fs account until it expires. Revoke a link with agent-fs share-revoke --token <link>. The button shows when agent-fs reports the share-links feature.
Upload
Upload in a folder header, or a drop on the folder view, uploads files into that folder. A dropped folder keeps its structure. Comb uploads 3 files at a time and shows the progress. A file over the agent-fs upload limit (maxUploadBytes, 50 MB by default) is not sent. When a file with the same name is already there, pick Keep both (Comb uploads it as name (1).ext) or Skip. To replace a file, use the agent-fs live UI. Uploads need the editor role in the drive.
HTML preview
An HTML file opens on Source, where comments anchor. Preview runs the page in a sandboxed frame:
- The page loads from a 15-minute agent-fs site link to its folder, so its relative styles, images, and scripts load.
- The frame comes from the agent-fs host, and its sandbox gives the page no origin. The page cannot read the dashboard, its local storage, or agent-fs cookies, and it cannot navigate the dashboard tab. Scripts, forms, popups, and dialogs run. A popup keeps the sandbox, so a site that needs its own storage can break in it.
- A page at the drive root asks first, because its site link covers the whole drive for 15 minutes.
Preview shows when agent-fs reports the html-sites feature.
Home, Recent, and Favorites
The drive root is the Comb home. The left panel starts collapsed there, because the home lists the files itself. It opens again in any folder or file, or with a click on its icon strip. The home shows these lists above the folder:
| List | What it shows | Where it is stored |
|---|---|---|
| In progress | Each unfinished swarm task that open comments wait on, with those comments under it. Shows only while a task runs. | The comments in agent-fs, the task status in the swarm API |
| Favorites | Files and folders you starred | agent-fs, for your agent-fs account (the favorites feature). The agent-fs live UI shows the same stars. |
| Recently viewed | The last 20 files you opened | This browser only |
| Recently changed | The newest version of each changed file, and who wrote it | agent-fs (recent op) |
The left panel shows the full lists: Recent (pick Viewed or Changed) and Favorites. The star in a file or folder header adds it to Favorites. Favorites also show under Comb in the sidebar.
Before Comb used agent-fs stars, it kept them in the swarm API. The first time a browser connects Comb to an agent-fs with the favorites feature, Comb copies those stars to your agent-fs account and skips the ones whose file is gone. The swarm API keeps its copy: an agent-fs without the feature, or a browser that is not connected, still lists them.
Full width
On a markdown file, Full width in the header (or F) lets the text run as wide as its pane, without the reading width. The side panels stay. The choice stays in this browser.
Frontmatter, images, and diagrams
- A YAML block at the top of a markdown file shows as Properties: lists as chips, links as links, nested values as YAML. Click its title to collapse it. The choice stays in this browser. YAML that does not parse (for example a value with
:in it) is read line by line and marked Not valid YAML. - Images and mermaid diagrams show Maximize and Comment on hover. Maximize shows the asset as large as the screen, with Actual size and Download (a diagram downloads as SVG). A wide diagram fits the page width.
Comment
- Select a passage in a markdown or text file, then click Comment (or press
C). The comment anchors to that passage. - Comment on an image or a diagram (on hover, or in Maximize) anchors the comment to the asset's source lines, because agent-fs anchors comments on text and lines only. An asset with a comment gets an outline, and a bold one while its comment is selected. The agent-fs live UI shows an image comment on its line. It shows a diagram comment as Lost, because its diagrams carry no line numbers.
- Comment on file adds a comment about the whole file.
- Add comment saves the comment. It does not send it to the swarm (see Send comments to the swarm).
- Reply, Resolve, and Reopen work on every thread.
Anchors follow the text across versions. A thread shows Moved when the text changed and Comb found the closest match. It shows Lost when the passage is gone.
A draft stays in this browser until you add it. If agent-fs cannot be reached, the comment waits under Not saved in the comment rail. Retry it from there.
Mentions
Type @ to open the member picker. Only a person that you pick from the list gets a notification. A name that you type by hand notifies nobody. The mention shows in that person's notification bell, under Mentions. A click opens the file at the thread.
@swarm
@swarm in a comment flags it for the swarm: the passage gets its own color. A flagged comment is not sent until you send it. You do not need @swarm to send a comment.
Send comments to the swarm
Comments are drafts for the swarm until you send them, like page feedback. Any open comment that was not sent yet can go. Each send creates one task for the lead, with every checked comment in it.
| Button | Where | What it sends |
|---|---|---|
| Send to swarm | On a thread | That thread |
| Send to swarm | The send bar under a file's comments ("N not sent") | The checked comments of the file |
| Send to swarm | The Open comments panel of a folder, with comments checked | The checked comments |
| Send N | The Comb header, on every page | Your unsent comments from every file, grouped by file |
The dialog lists the comments, all checked, and takes an optional Note for the lead (at most 4000 characters). The note goes into the task text. An operator who customized the comb.review.batch template must add {{note_block}} to it, or the note is left out. One batch holds at most 50 comments. Send again for the rest. N not sent in the send bar shows only those comments.
The task has the source comb. The swarm posts a reply on each sent comment, which shows as "Sent to the swarm · task ...". A comment that the swarm already received is skipped on the next send.
The task goes to the lead. With no lead, it waits unassigned in the pool, and the toast says so. With an offline lead, it waits for the lead to come back.
When a send fails, nothing is sent:
| Answer | Why |
|---|---|
| 400 | The comments are not on the swarm drive, or an id is not valid. |
| 403 | You cannot create tasks. Ask a swarm admin. |
| 409 | Every comment was skipped (already sent, resolved, a reply, or gone). |
| 502 | agent-fs could not read one of the comments. Try again. |
| 503 | agent-fs or the swarm drive is not set up, or an operator turned off a Comb review template. |
What the agent does
The lead handles the batch or delegates it to one worker, so only one agent edits these files at a time. For each comment, the agent:
- Reads the file at its current version, and the diff since the comment's version.
- Makes the change with
agent-fs editoragent-fs write. This adds a new file version. - Replies on the comment with what it changed.
The agent resolves a comment only when the comment asks for it or the change is trivially complete. When a comment needs a human decision, the agent replies and mentions the author.
Resolve comments in bulk
The Open comments panel of a folder lists the open comments of every file under it. Check comments one by one, by file, or all at once. Any age narrows the list to comments older than 7 or 30 days. With comments checked:
- Resolve resolves them, 4 at a time (agent-fs resolves one comment per call). Undo in the toast reopens them.
- Send to swarm sends them as one task.
Resolving needs the editor role in the drive.
Review the changes
A thread whose file has a newer version shows Review changes (vA → vB). It opens the diff from the version that the comment was made on to the current version. Versions in the file header opens the diff for any earlier version.
From the review you can resolve or reopen the thread, and revert the file.
Revert to vA writes a new version with the content of vA. Earlier versions stay in the history. Comb shows Revert only when all of these are true:
- The file is a markdown, text, or table file.
- The diff has changes.
- The diff ends at the current version.
If an agent writes a new version while you review, agent-fs refuses the revert. Comb then shows the new version. Click Reload the diff and review again before you revert.
Live updates
With change-stream, the header shows Live. Agent edits, new files, and new replies show without a reload. Otherwise the header shows Polling, and Comb checks every 10 seconds.
- A tab in the background closes its stream after 10 seconds, and reconnects when you return to it.
- When agent-fs is served over
http:, the Comb tabs of one browser share one stream for each drive. One tab holds the stream and sends the changes to the other tabs. The sharing needs a secure dashboard origin (https:orlocalhost). - agent-fs allows 8 streams for each user. A refused stream falls back to polling.
Links to agent-fs files
With Comb on, agent-fs links in the dashboard open in Comb while you are connected. This covers task attachments, citations, attachment links in prompts, and links inside Comb files. Session logs and task outputs keep the link safety prompt and open agent-fs.
When APP_URL (or the deprecated DASHBOARD_URL) is set, file links open in the dashboard by default: Slack attachment links, the lead's follow-up prompts, and the links that agents give people point at APP_URL/file/~/<org>/<drive>/<path>. Attachment links also need Comb on. Without APP_URL, or with COMB_ENABLED=false, they keep the agent-fs live app link.
AGENT_FS_LINK_TARGET overrides this default for task attachment links and for the file links that agents give people:
| Value | Effect |
|---|---|
| unset | The default above: dashboard when APP_URL is set and COMB_ENABLED is not false, else live. |
dashboard | Links point at APP_URL/file/~/<org>/<drive>/<path>. Attachment links need Comb on and an explicit APP_URL, and agent links need COMB_ENABLED not false; otherwise they use the live app. |
live | Links point at the agent-fs live app (AGENT_FS_LIVE_URL, default https://live.agent-fs.dev). |
The agent prompt uses the worker's own APP_URL. A saved APP_URL, AGENT_FS_LINK_TARGET or COMB_ENABLED (Settings, Configuration) reaches running workers at their next poll. A COMB_ENABLED=false set only in the API's deployment env does not reach workers. The deployment env stays the fallback.
When AGENT_FS_PUBLIC_URL is set, a link to the live app carries ?apiUrl=<AGENT_FS_PUBLIC_URL>, so a browser with no agent-fs key knows which agent-fs to sign in to. Dashboard links never carry it.
Citations and the context preamble always use the live app link.
Agents deliver results as Markdown files, not Pages. They make a Page only when the requester asks for one. A use case keeps its results under its asset key in the shared drive: the drive path equals the key string (for example shared/<slug>/report-<YYYY-MM-DD>.md), so later runs can read earlier reports in the same folder.
Turn off Comb
Set COMB_ENABLED to false. An existing swarm that never set it gets Comb on as soon as AGENT_FS_API_URL is set and the browser has an agent-fs address, so this is the way to keep the old behavior. Within one status poll (30 seconds at most):
- The sidebar hides Comb.
/fileshows "Comb is off". A file route also shows Open in agent-fs.POST /api/comb/review-batchesanswers 404.- Task attachment links point at agent-fs again.
- The dashboard still uses the server's
AGENT_FS_LIVE_URLfor live links. It replacesVITE_AGENT_FS_LIVE_URL.
The dashboard and the API then behave as they do without Comb. Comments, mentions, and file versions stay in agent-fs. Tasks that Comb created stay in the task list.
Security
- The agent-fs key lives in this browser's local storage, separately for each swarm API and agent-fs URL. The swarm mints it once and does not store it. The dashboard sends it only to agent-fs (or through the API's
/agentfsproxy, which forwards it and never adds the swarm key). Forget this browser's key removes it. - The dashboard saves its query cache in local storage. File contents and comments never go into it.
- Comb runs an HTML file only when you click Preview, in a sandboxed frame from the agent-fs host (
sandbox="allow-scripts allow-forms allow-popups allow-modals", noallow-same-origin, no sandbox-escaping popups, no referrer). The page can read the files of its folder for 15 minutes, through its site link. - Search snippets show as text. Comb never renders file content from a snippet as HTML.
- A share link is public until it expires. Anyone who gets it can open the file.
- The swarm API receives only comment ids when you send. It reads the comments from agent-fs with its own key.
Troubleshooting
"Comb is off". Read agent_fs.comb.reason in GET /status. It names the missing piece: AGENT_FS_API_URL is not set, COMB_ENABLED is false, or AGENT_FS_PROXY is false with no AGENT_FS_PUBLIC_URL. After a change, the dashboard needs up to 30 seconds to poll.
"Cannot reach agent-fs". The browser cannot reach AGENT_FS_PUBLIC_URL (or <public API URL>/agentfs with AGENT_FS_PROXY=true). Check the URL from the browser's machine. A self-hosted agent-fs allows every origin by default. If you set server.cors.origins in its config.json, add the dashboard origin.
The header shows "Polling" instead of "Live". Hover the status for the reason. Common causes: agent-fs is older than 0.15.0, a proxy buffers the event stream, or you have more than 8 open streams.
"Your files account is not ready yet". The swarm could not register or invite your email in agent-fs. The reason under the title comes from the server. Fix it on agent-fs (for example AGENT_FS_REGISTER_ALLOWED_DOMAINS), then use Retry.
"Ask a swarm admin to invite ... to the drive" (paste-key form only). The swarm API could not invite the pasted key's account. An admin can invite the email with POST /api/fs/members/invite, then you connect again.
Review changes shows only the last edit, or Revert fails. The agent-fs bucket has no object versioning. Turn it on (for MinIO: mc version enable <alias>/<bucket>), then restart agent-fs: it checks versioning once at startup. Versions written before that have no stored content, so their diffs stay partial.
A file shows no version, and Review changes does not appear. agent-fs 0.15.0 stores the history of a file under the path as it was written. A path without a leading / (for example docs/a.md) keeps its history under that exact string. Write paths with a leading /. A later agent-fs release normalizes the paths.
Configuration
Manage operator-facing swarm settings from the dashboard — feature flags, thresholds, and defaults grouped by subsystem
Playbooks
Eighteen production playbooks for running an agent swarm — feature development, prospecting, content, UX audits, customer support, code health, code-health reports, DORA metrics, cross-source reports, self-documenting releases, open-prompt motion-graphics videos, email domain health monitoring, Open Oncall incident response with provider failover, PR review with small-model triage, a Linear delivery loop that drives issues to merged pull requests, goals that iterate until a check passes, and a Slack reply gate that keeps Lead out of thread banter. Real flows, real schedules, real agents.