Appearance
Agent Docs
The Agent Docs view keeps one reviewed Clusto version of your AI coding configuration and writes it to every tool you use, on every node, for every OS account. You write the instructions once. Each node renders them for itself, with its own home directory, paths, and operating system, before writing the file each tool reads.
Clusto replicates the saved version between daemons. In project scope, files on disk change only when you apply. In user scope, nodes also keep the files and the saved version in step on their own; see Automatic sync.
Scopes
Choose a scope at the top of the view:
- User (all nodes) holds one user-level version for the whole cluster. Its files go into each tool's user config directory on every node, and automatic sync keeps them current.
- Project holds one version for the selected project. Its files go into the project's working directory on the node that owns the project.
Supported tools and file locations
User-scope paths are relative to the tool's user config directory. Project paths are relative to the project's working directory. A dash means the tool has no location for that item in that scope.
| Tool | User config directory | User instructions | Project instructions |
|---|---|---|---|
| Claude Code | ~/.claude | CLAUDE.md | CLAUDE.md |
| Codex | ~/.codex | AGENTS.md | AGENTS.md |
| Gemini CLI | ~/.gemini | GEMINI.md | GEMINI.md |
| opencode | ~/.config/opencode | AGENTS.md | - (reads AGENTS.md) |
| GitHub Copilot | ~/.copilot | copilot-instructions.md | .github/copilot-instructions.md |
| Cursor | ~/.cursor | - | .cursorrules |
| Windsurf | - | - | .windsurfrules |
| Cline | - | - | .clinerules/clusto.md |
| JetBrains Junie | - | - | .junie/guidelines.md |
Skills, subagents, and commands:
| Tool | User skills | User subagents | User commands | Project skills | Project subagents | Project commands |
|---|---|---|---|---|---|---|
| Claude Code | skills/ | agents/ | commands/ | .claude/skills/ | .claude/agents/ | .claude/commands/ |
| Codex | skills/ | - | prompts/ | .agents/skills/ | - | - |
| Gemini CLI | skills/ | - | commands/ (TOML) | .gemini/skills/ | - | .gemini/commands/ (TOML) |
| opencode | skills/ | agents/ | commands/ | .opencode/skills/ | .opencode/agents/ | .opencode/commands/ |
| GitHub Copilot | skills/ | agents/ (.agent.md) | - | .github/skills/ | .github/agents/ (.agent.md) | - |
| Cursor | - | - | commands/ | - | - | .cursor/commands/ |
| Windsurf | - | - | - | - | - | .windsurf/workflows/ |
| Cline | - | - | - | - | - | .clinerules/workflows/ |
Notes:
- The project
AGENTS.mdis one shared file. It is listed under Codex, and opencode, Copilot, Cursor, and other tools read it too, so only one target writes it. - Cline instructions live in
.clinerules/clusto.md, one file inside Cline's rules directory, so Clusto never replaces your other Cline rule files. A project that still has a single.clinerulesfile must turn it into a directory before Clusto can write there. - Directory overrides come from the
envtable of the daemon configuration (the environment sessions run with):CLAUDE_CONFIG_DIRmoves the Claude Code directory,CODEX_HOMEmoves the Codex directory, andXDG_CONFIG_HOMEmoves opencode to$XDG_CONFIG_HOME/opencode. clusto agents toolsprints this catalog from the connected daemon.
Instructions: one shared body
The Instructions card holds one Shared body that you write once. Each tool target then picks a mode:
- Shared body writes the shared body as-is.
- Shared + extra writes the shared body followed by extra content for that tool only.
- Custom only ignores the shared body and writes only that tool's own content.
Tick only the tools Clusto should manage. A fresh version starts with every tool unticked, so an empty draft can never erase existing files. Clusto never writes an instruction file whose rendered content is empty: when a tool's instructions render to nothing on a node (for example a body wrapped in an os=linux block, seen on Windows), that tool's file is left exactly as it is, the target shows Agent Docs has no instructions for <tool> on this node; nothing written, and sync does not count it as an error.
Each target also has a Where it applies setting (see below).
Templates: variables and blocks
Instructions, skills, subagents, and commands are templates. Each node resolves them before writing, so the file a tool reads contains no Clusto syntax.
Variables
Write {{clusto:name}} to insert a value. Built-in variables:
| Variable | Value on the target node |
|---|---|
home | Home directory of the OS account |
user | OS account name |
os | linux, windows, or macos |
arch | CPU architecture, for example x86_64 or aarch64 |
node | Node name |
shell | Default shell |
sep | Path separator: \ on Windows, / elsewhere |
provider | Tool key being written: claude, codex, gemini, ... |
provider_home | That tool's user config directory (tools that have one) |
skill_dir | Directory of the skill being written (skills only) |
Custom variables live in the Variables card. Each has a cluster-wide default and optional per-node values, for example repos set to /data/Repos by default and C:\Repos on a Windows node. Names use lowercase letters, digits, and _, start with a letter, and cannot reuse a built-in name. From a shell use clusto agents vars.
An unknown or unset variable is a render error: the file is not written, and status shows Render error with the line number. Clusto never writes a blank in place of a missing value.
Conditional blocks
Whole-line blocks keep or drop the lines between them:
markdown
Repositories live in {{clusto:repos}}.
<!-- clusto:if os=windows -->
Use PowerShell. Paths use backslashes.
<!-- clusto:else -->
Use bash.
<!-- clusto:end -->Scripts and TOML files can use the comment form instead:
bash
# clusto:if os=linux,macos
export PATH="$HOME/.local/bin:$PATH"
# clusto:endCondition rules:
- Keys:
os,arch,node(node name or node id),user,provider. key=valuematches,key!=valueexcludes.- A comma means OR within a term:
os=linux,macos. - Space-separated terms are AND:
os=windows provider=codex. clusto:elseis optional. Blocks do not nest.
The template editor has buttons that insert each variable and an OS-specific block.
Where it applies
Every instruction target and every skill, subagent, or command can be limited to:
- Operating systems
- Nodes
- OS accounts (comma separated)
Leave everything empty to apply everywhere. On a node, account, or OS that is excluded, the item shows Not applicable and is skipped.
In user scope, a tool whose user config directory does not exist on a node (for example ~/.gemini on a machine that never ran Gemini CLI) shows Tool not installed and is skipped there. Clusto does not create a tool's config directory. Project scope always writes into the project.
Skills, subagents, and commands
The Skills, subagents and commands card stores each item once and writes it for every tool listed under Written for:
- A skill is a whole directory:
SKILL.mdplus any scripts and references. Files marked Executable are written with the executable bit on Unix. Skill directories hold up to 200 files. - A subagent or command is one Markdown file, with optional frontmatter in Claude Code's dialect.
Clusto converts the format where a tool differs:
- Gemini CLI commands are written as TOML with
descriptionandprompt;$ARGUMENTSbecomes{{args}}. Import converts them back. - opencode subagents get
descriptionandmode: subagent; GitHub Copilot subagents getnameanddescriptionand the.agent.mdsuffix. Thetoolsandmodelfields are dropped for these tools because tool and model ids are not portable between them.
Skills can hold binary files such as images, fonts, and audio. They are stored in the record as base64, written byte for byte, and never templated. A binary file is limited to 1 MiB and a skill to 8 MiB in total; text files keep the 256 KiB limit. A larger file is listed as not synced and stays local. In the asset editor, binary files show as read-only binary rows. The manual Review node changes import takes text only: a copy that contains binary files cannot be imported there, but automatic sync carries them.
Stop tracking removes the item from Clusto and, through sync, from every node. See Deleting an item.
If two tools share one directory through a symbolic link (for example a tool's skills directory linked to another tool's) and the rendered content differs between them, the write is blocked with a message naming the other tool. Remove the link so each tool gets its own copy, or make the content identical.
Automatic sync (user scope)
In user scope, every node keeps your Agent Docs and the files of its agent account in step, in both directions, with no review step. It runs as part of the Knowledge reconcile: on start, after any knowledge or Agent Docs change, and every 5 minutes. A pass that finds nothing changed does not read the tool files again, so the 5-minute check costs almost nothing on an idle node. Project scope is unchanged: it stays manual (review, import, apply), and repositories carry their own files through git.
Automatic sync is always on. Each node's sync mode decides what it does: two-way, receive-only, or manual. In manual mode items move only when you send and apply them, so a node that must stay apart is set to manual.
Capture. A skill, subagent, or command file you edit on a node, a new one you place in a tool's folder, or one you delete becomes the replicated record. A new item is written for every tool that supports that kind, the same as a manual user-scope import. Node paths are turned into variables on capture, the same as Replace node paths with variables.
Write. Every record is rendered for the node's OS, account, and custom variables and written into every installed tool's folder where the file is missing or out of date. A tool whose config directory does not exist is skipped, as before.
Conflicts. Sync compares three things for each file: the file on disk, the record, and what this node last wrote.
- An edit the record has not moved past is captured.
- When both sides changed, or a file Clusto never wrote differs, the newer modification wins.
- A file that loses is first copied to
~/.clusto/agent-sync/replaced/<path relative to home>(the latest copy only), then overwritten. If no copy can be kept, because the file is outside the home or over 1 MiB, it is not overwritten and shows under needs review. - A file modified in the last 30 seconds is left for the next pass, since an agent may still be editing it.
What can be captured. An edit is captured only when it can be turned back into the template exactly:
- The template has no
clusto:ifblocks. A node sees only its own OS branch. - It uses only variables that map back from paths:
home,provider_home,skill_dir, and custom variables whose value is a path. - The tool stores the canonical format: Claude Code format for subagents and Markdown for commands. Edits to opencode or Copilot subagents and to Gemini TOML commands are not captured.
- Rendering the captured template again reproduces the file.
Otherwise the file is left alone and listed as needs review in Agent Docs. Sync never overwrites it. Use Review node changes to import it by hand.
OS handling. A change that only alters line endings, such as CRLF from a Windows editor, is not captured. Windows has no executable bit, so there the bit comes from the record, or is set for files that start with #!.
Instructions. An edit to a tool's instruction file goes into the shared body (Shared body mode), the tool's custom content (Custom only), or the shared part when the tool's own extra text is unchanged (Shared + extra). Only enabled targets are synced, and sync never ticks a new tool on. The managed Knowledge section is ignored, as before.
Deleting an item
- Deleting a skill, subagent, or command in Agent Docs (Stop tracking) removes it from every node. Only files Clusto wrote and nobody edited are removed; edited copies are kept.
- Deleting the item's folder or file from every tool on one node deletes it everywhere once it has stayed gone for about a minute.
- A copy edited after the deletion brings the item back. A copy edited before it is kept on disk but not revived.
A deletion replicates as a tombstone record, so a node that was offline cannot bring the item back when it reconnects.
Status and safety
The Knowledge view AI setup card shows an Agent Docs sync row with counts for items tracked, captured, newly tracked, deleted, files written, files removed, needs review, not synced, and errors. clusto doctor shows the same check. The daemon log records a failing check once, and again only when its detail changes, not on every 5-minute pass.
Files are read without following links out of the account's home, and a file with more than one hard link is refused, so a planted link never makes the daemon capture a file outside the account. Text that looks like a secret is not captured.
Sync is free on every plan, Personal included. [knowledge] enabled = false turns it off completely on a node. To change how a node takes part, pick a sync mode.
Sync modes
Each node has its own mode. Set [knowledge] agent_sync in config.toml to "two_way" (the default), "receive_only", or "manual". You can also pick it in the Knowledge view's AI setup card with Skills and instructions sync (shown while knowledge is on), or from F1 while the Knowledge view is open: Agent sync on this node: Two-way, ... Receive only, ... Manual.
toml
[knowledge]
agent_sync = "receive_only"- Two-way. Everything described above: the node captures edits, new items and deletions, writes the cluster's items, and removes deleted ones.
- Receive only. The cluster's items are written to this node, but nothing from the node is captured or sent. New items there are not tracked, edits are not captured, and deleting an item's folder there deletes nothing elsewhere (the cluster copy is written back). A file Clusto did not write, for example a company skill with the same name, is never overwritten. An edit to a file Clusto wrote stays until the cluster record changes; then the newer side wins as usual and the losing copy is kept in
~/.clusto/agent-sync/replaced/. These files show under needs review in Agent Docs with the reason "edited on this node, which only receives" or "not written by Clusto, and this node only receives". - Manual. Nothing is automatic and the node is isolated. Items move only on demand from Agent Docs, on that node: Review node changes then Save to Clusto sends an item to the cluster, and Apply (or a row's write) pulls items to it. Apply to all nodes skips manual nodes. The AI setup row Agent Docs sync shows Off with the detail "manual: send and apply items from Agent Docs".
Use Manual or Receive only for a machine with a different login, for example a work laptop signed in to a company Claude account. Its skills stay apart from your others, and you still move single items when you choose.
The first-run import of a node's existing setup into Agent Docs (see Knowledge) runs only on a two-way node, so a receive-only or manual node never sends its setup on first start.
Review and import from a node
Select Review node changes on the Instructions card or the skills card, choose an online node, and in user scope an OS account. Clusto scans every supported location and marks each file Same, Changed, or New (skills) or Not found (instructions).
Replace node paths with variables turns the node's literal paths back into variables before you import: the account's home directory becomes {{clusto:home}}, a tool directory becomes {{clusto:provider_home}}, a skill directory becomes {{clusto:skill_dir}}, and path-like values of your custom variables become those variables. A file imported this way renders correctly on every other node.
For an instruction file:
- Diff compares the Unsaved Clusto draft with the Node version.
- Use as shared body puts the node file into the shared body.
- Use for tool only stores it as that tool's custom content.
- Smart merge previews a three-way merge into the shared body or the tool's custom content.
For skills, subagents, and commands, the scan groups the same item across tools into one row and notes when the tools' copies differ. Pick which copy to compare with, then use Diff, Edit draft, Smart merge, Use node version, and Save to Clusto. Tick several rows and choose Save to Clusto to import them in bulk. A user-scope import is written for every tool that supports that kind of item; a project-scope import is written for the tools that already hold it. Change the list later under Written for.
Discovery also scans older directory layouts (opencode's singular agent/ and command/ directories, Codex's project .codex/skills/) and labels those copies old layout. Clusto always writes to the current locations listed above.
Discovery and editing change only the unsaved draft. Save Clusto version replicates it between daemons but still writes nothing to disk.
Smart merge and line diffs
Smart merge never changes the draft immediately. It opens a diff from Current draft to Merged preview. Choose Apply merge to draft or Cancel. If both sides rewrote the same lines, the preview reports the conflict count and the applied draft contains <<<<<<< conflict markers to resolve before saving.
Every diff in Agent Docs uses one synchronized line view. Both sides scroll together and keep their own line numbers. Row markers:
-removed: the line exists only on the left+added: the line exists only on the right~changed: a line and its replacement, aligned on one row
Preview on a node
Preview on a node renders the unsaved draft for a chosen node and, in user scope, OS account. It shows the context used (node, OS, account, home), the state of each tool's file, and a diff of On disk (current) against the Rendered draft, including render errors and why a target does not apply. Use it to check variables and blocks before saving. Each skill, subagent, or command editor has its own Preview.
Roll out to nodes
The rollout card lists every node. Offline nodes stay visible but cannot be checked or written. Save the Clusto version before checking or applying.
On a root daemon, an account picker chooses which OS account to render and write for: the default session account plus every run-as user of the node's projects. An unprivileged daemon writes only for its own account. Project scope renders for the project's run-as user, or the default account.
Select Check to compare. Each file reports one state:
| State | Meaning |
|---|---|
| In sync | The file matches what Clusto would write |
| Missing | The file does not exist yet |
| Outdated | Clusto wrote the file and the saved version has changed since |
| Edited on node | Clusto wrote the file and someone changed it afterwards |
| Diverged | The file differs and Clusto never wrote it |
| Not applicable | The item is limited to another OS, node, account, or tool |
| Tool not installed | The tool's user config directory does not exist for this account |
| Unsupported | The tool has no location for this item in this scope |
| Render error | A variable is unknown or a block is malformed |
Open diff on a row to compare On disk (current) with Clusto would write. write on a row writes only that file; Apply writes every enabled instruction file and every tracked item for the node.
Missing and outdated files are written directly. Files that are Edited on node or Diverged are only replaced after confirmation: the dialog lists them and offers Overwrite or Skip edited files.
Apply to all nodes (user scope) writes to every online node, rendered for each node's default account. It always skips edited and diverged files, offline nodes, and nodes in manual sync mode. A manual node refuses the bulk write ("this node syncs agent docs manually; apply on this node directly") and counts as skipped. Apply on a single node to review and overwrite edited files, or to write to a manual node.
Clean up removes files that Clusto wrote, that nobody edited since, and that no saved instruction or item renders any more, for example after you untick a tool. It shows the file list first and deletes only after you confirm.
Symbolic links
Status shows when a file is a symbolic link and where it points. A safe link whose final target stays inside the managed root (the account's home directory or the project directory) is preserved: Clusto writes through it, and the confirmation says so. Clusto blocks the write when the link is broken, points outside the managed root, or a parent directory is a link that escapes it. Fix the link and check again. Paths are revalidated at write time, so a link changed after review cannot redirect a write.
An absolute link, such as ~/.claude/CLAUDE.md pointing into a dotfiles checkout, can also be refused at write time even when its target is inside the home. The error names the link and its target: replace the link with a regular file (or a relative link that stays inside the home), or set Agent Docs sync to Manual on that node so Clusto stops trying.
When two tools reach the same file through a link (for example CLAUDE.md linked to AGENTS.md), Clusto writes it only if both render the same content. If they differ, the second tool is blocked with a reason: give each tool its own file, or set both to the same content.
From the CLI
clusto agents offers the same operations from a shell, including from inside a Clusto session where the connection comes from the environment. See CLI Reference.
bash
clusto agents status # user scope, this node, default account
clusto agents render --tool codex # print what would be written
clusto agents apply --overwrite # write, replacing edited files
clusto agents vars set repos 'C:\Repos' --node <NODE_ID>Knowledge keeps a Clusto-managed section, fenced by the clusto:knowledge:start and clusto:knowledge:end HTML comment markers, in each tool's user instruction file. Agent Docs ignores that section when comparing or importing and keeps it when writing, and on a fresh cluster the node's existing user-scope setup is imported automatically once.
Upgrading from earlier versions
Existing Agent Docs records migrate automatically and without loss:
- Instructions: the body most targets used becomes the Shared body; targets that held it switch to Shared body, and targets with different content keep it as Custom only.
- Skills, subagents, and commands: the old per-file entries are grouped into one item per name, a skill becoming one bundle with all its files. When tools held different copies of the same item, the most recently updated copy is kept and every tool stays listed under Written for. The older copies on disk then show as Diverged and are never overwritten without your confirmation.
The migration writes nothing to disk. Check a node and apply when you are ready.