Skip to content

Knowledge ​

Knowledge gives every AI agent on your cluster the same memory of what works. It is on by default on every node and needs no setup: Clusto registers its own MCP server in your coding tools, keeps a short managed section in their instruction files, lets agents propose lessons you approve, mirrors Claude Code memory per repository, and backs the whole agent setup up with versions you can restore.

Open it from the navigation (Knowledge) or press F1 and run Go to Knowledge. The view has four cards: AI setup, Lessons, Agent memory, and Backups.

AI setup and backups act on the node the app is connected to. Lessons, Agent Docs, and memory are cluster-wide.

What happens on each node ​

Each node keeps itself configured. It checks its setup on start, after every knowledge change, and every few minutes, and repairs whatever drifted.

  • Notes vault. Every node gets a local Notes vault. It defaults to ~/.clusto/notes in the home of the node's default_session_user, so agents running as that user can read it. A vault that still lives in the daemon's data directory is moved there once. Files written into the vault keep the vault owner. An explicit user or local_dir on a vault is left alone. A node keeps every vault in whose Kept on scope it is; other vaults get no copy there (see Multiple vaults).
  • MCP server. Clusto registers an MCP server named clusto (command clusto mcp) in each installed tool: Claude Code (~/.claude.json), Codex (~/.codex/config.toml), and Gemini CLI (~/.gemini/settings.json).
  • opencode MCP server. opencode gets the clusto MCP server from the Clusto-owned plugin below, so opencode.jsonc is never rewritten. A clusto MCP entry you wrote yourself wins.
  • Waiting status. The ? waiting marker is wired for you: Clusto adds its own hooks to Claude Code's settings.json and writes the plugin ~/.config/opencode/plugins/clusto.js for opencode (first line // clusto:managed, rewritten by Clusto). Gemini CLI gets hook entries in ~/.gemini/settings.json and GitHub Copilot CLI a Clusto-owned ~/.copilot/hooks/clusto.json. Codex reports waiting itself; Cursor has no hook that fires while it waits, so it uses the copyable instructions. Your own Claude Code and Gemini CLI hooks are never touched, and a file at the plugin or Copilot hooks path that is not Clusto's is reported as an error and left alone.
  • Claude Code smooth scrolling. Clusto's terminal sends one wheel report per line (three per mouse notch), and Claude Code's fullscreen view ramps the lines per report during fast scrolls, so scrolling jumped. The node adds "wheelScrollAccelerationEnabled": false and "env": { "CLAUDE_CODE_SCROLL_SPEED": "1" } to ~/.claude/settings.json, which gives a steady three lines per notch on every platform. Each value is written only when its key is absent, so a value you set yourself is kept and the check reports "your own ... kept". To get acceleration back, set wheelScrollAccelerationEnabled to true there. Nothing is written while the AI setup is off, and turning it off later does not remove the values.
  • Local access file. The daemon writes ~/.config/clusto/local-daemon.toml (mode 0600) for the session user, so clusto mcp and clusto lessons work from any terminal with no flags or token.
  • Managed instruction section. Each installed tool's user instruction file (CLAUDE.md, Codex AGENTS.md, GEMINI.md, and so on) gets a section fenced by two HTML comment markers named clusto:knowledge:start and clusto:knowledge:end. It tells the agent how to use the Clusto tools and lists the approved global lessons. Clusto rewrites only that section; the rest of the file is yours. Do not write the markers into your own text: Clusto treats whatever sits between a start and an end marker as its section and replaces it. Agent Docs ignores the section when it compares or imports files and keeps it when it writes them.
  • Agent Docs sync. Your user-scope Agent Docs (global instructions, skills, subagents, and commands) are kept in step with the files of the node's agent account, in both directions. An edit made on the node is captured, a new or deleted skill, subagent, or command is picked up, and every saved item is written into each installed tool's folder where it is missing or out of date. Project scope stays manual. See Agent Docs.
  • First-run import. If the cluster tracks no user-scope Agent Docs yet, the node's existing global instructions, skills, subagents, and commands are imported into Agent Docs automatically. This happens once, and only on a node in two-way sync mode; deleting everything later does not re-import.

The AI setup card lists each check (vault, access file, MCP per tool, instruction section per tool, Claude Code waiting status, Codex waiting status, opencode waiting status, opencode MCP server, Gemini CLI waiting status, GitHub Copilot CLI waiting status, Claude Code smooth scrolling, Agent Docs sync, memory, backups) with its state. The Agent Docs sync row counts items tracked, captured, newly tracked, deleted, files written and removed, needs review, not synced, and errors. Fix now re-runs the setup; F1 has the same action as Re-run AI setup on this node.

Turning it off ​

Select Turn off on the AI setup card, or set it in the node's config.toml:

toml
[knowledge]
enabled = false

This is per node. Turning it off also removes the Claude Code and Gemini CLI waiting hooks, the Copilot hooks file and the opencode plugin together with the rest of the setup. Turn on in the same card enables it again.

To keep Knowledge on but change how a node takes part in Agent Docs sync, set agent_sync to "two_way" (default), "receive_only", or "manual". The same choice is the Skills and instructions sync select on the AI setup card (shown while knowledge is on) and, while the Knowledge view is open, the F1 actions Agent sync on this node: Two-way, ... Receive only, and ... Manual:

toml
[knowledge]
agent_sync = "manual"

Receive only writes the cluster's items to the node and sends nothing back. Manual does nothing automatically; you move items from Agent Docs. Manual suits a machine with a separate login, such as a work laptop on a company Claude account. See Sync modes.

Node Doctor ​

Settings > Node Doctor (System group) shows the AI setup of every cluster node in one place, so you do not have to connect to each node to repair it.

  • Each node is a row with a status: All Good, N Issues, Off (Knowledge is turned off there), Offline or Error. A peer that cannot be reached shows its error in the row.
  • Expand a row to see that node's checks, the same list as the AI setup card, followed by two host health checks (below).
  • Fix repairs one node. Fix all repairs every node, and Check again re-reads them.
  • A This device row at the top checks the notifications of the device you are on: system notification permission (Fix asks for it; if it is blocked, allow Clusto in the OS settings), alert popups (Fix turns them on), and alert sound, Android background checks and muted sessions, which are shown as choices rather than issues. Send test notification raises a sample alert through the same path a waiting agent uses. Fix all (and the F1 action) fixes this device too.
  • The card footer has Copy setup instructions for tools Clusto cannot wire itself, such as Cursor.

Host health checks ​

Each node also gets two checks about the machine itself. They are reported only; Fix does not change them.

CheckShown as an error whenWhat to do
CPU headroomLinux: processes spent 40% or more of the last 15 minutes waiting for a CPU. Windows and macOS (no pressure data): the CPU was 90% or more busy on average over the last 15 minutesLower the priority of the heavy jobs (on Linux, for example a systemd drop-in with CPUWeight=20 and Nice=10 for a CI runner), close the heaviest processes, or move the jobs to another machine
Peer linksThis node had to reset the link to a peer 3 or more times in the last hour. The check names the peerCheck CPU headroom on both ends, and the network path with tailscale ping <node>

A starved host answers late, and a peer that waits too long resets the link. Below the limit, CPU headroom is Ready and shows the measured value. A check that does not apply to a node, or has no CPU samples yet, shows Not available. The same checks run in clusto doctor.

Ignoring an issue ​

A check you do not care about, such as CPU headroom on a busy build host, can be ignored. Every check that is an issue (Missing or Error) on a node row, the This device row or the This computer's node row has an Ignore button.

  • An ignored check stays listed, dimmed, with an Ignored badge and a Stop ignoring button.
  • Ignored checks no longer count. The row shows All Good (plus an N Ignored badge) instead of N Issues, and Fix all reports success without them.
  • Fix leaves ignored device checks alone: it does not turn alert popups back on or ask for notification permission when those were ignored. Fix all does not raise the administrator prompt for an ignored hived upgrade, and that row's Fix button is hidden while it is ignored.
  • The terminal's device health banner (low memory, flapping peer links) skips a check you ignored for that node.

Ignoring is per node and per check, so the same check on another node still counts. The ignore list is a synced preference (clusto-node-doctor-ignored), so it follows you to your other devices through cluster preferences and account cloud sync. It is free on every plan.

Daemon install ​

A node that still runs the old hived daemon gets a Daemon install row. It is an error that names the reason the switch to clustod is skipped, or says Fix restarts the daemon when nothing blocks it. Nodes already on clustod show no row.

Fix (also Fix all) runs the repair on that node remotely. It stages the cutover rollback backup, moves stale leftover binaries aside, and when nothing blocks the cutover any more it restarts the daemon. The daemon then switches to clustod and keeps its data, token and sessions. The node is back after about a minute. See Moving from Hive to Clusto.

This computer's node ​

A daemon older than 1.15.36 cannot report the Daemon install row itself, so Node Doctor also checks the computer the app runs on. It reads the OS service manager (the Windows service list, or systemd), so it works however old the daemon is. When this PC still runs the hived service instead of clustod, a This computer's node row appears. Nothing shows once the node is on clustod.

Fix (also Fix all) upgrades the node in place after one administrator prompt: UAC on Windows, pkexec on Linux. It fetches the current clusto CLI and runs its install repair, which installs this release's daemon over hived. That daemon switches the node to clustod and keeps its data, token and sessions. On Linux without pkexec the row shows a command to run instead:

bash
curl -fsSL https://dl.clusto.app/install.sh | CLUSTO_SKIP_WIZARD=1 bash && sudo /usr/local/bin/clusto doctor --fix

F1 has Open Node doctor and Fix agent setup on all nodes. A session (agent) credential can only read its own node's setup; fixing another node needs your account in the app or the node admin token.

MCP tools ​

The clusto MCP server gives agents these tools:

ToolDoes
clusto_lessonsApproved lessons for the current repository and global ones
clusto_propose_lessonProposes a lesson for your review
clusto_notes_vaultsLists the Notes vaults this node keeps
clusto_notes_searchFull-text search over a Notes vault
clusto_notes_readReads a note
clusto_notes_listLists notes in a vault
clusto_notes_writeCreates or updates a note
clusto_notes_moveMoves or renames a note or folder inside a vault; never overwrites an existing note
clusto_notes_deleteDeletes one note, or an empty folder, from a vault
clusto_list_tasksLists the cluster's scheduled tasks with schedule, last exit code, next run and pause window
clusto_get_taskReads one task in full, by id or exact name
clusto_task_runsRecent runs of a task with exit status and output tail
clusto_task_createCreates a scheduled task (command, working_dir, schedule); it runs on this node as the session's account unless node_id names another node
clusto_task_updateChanges a task by id or exact name; omitted fields keep their value
clusto_task_deleteDeletes a task and its run history
clusto_task_triggerRuns a task now, regardless of its schedule
clusto_task_cancelCancels a task's running or pending run
clusto_task_pausePauses a task until resumed, or for minutes or until a time
clusto_task_resumeLets a paused task fire on its schedule again
clusto_docs_searchSearches the Clusto user docs for the installed version (the same pages as clusto.app/docs) and returns matching sections
clusto_docs_readReads one docs page, or one section of it, by page slug
clusto_guidePrints a topic of clusto guide, the command-first manual for agents
clusto_cli_helpPrints the exact --help of a clusto command for the installed version
clusto_mcp_statusWhich Clusto MCP servers are configured for Claude Code and Codex for this account, and whether clusto is on PATH
clusto_cluster_statusLive cluster state: nodes, which are online, versions and addresses
clusto_cluster_configThis node's cluster configuration: node id, peers, advertise addresses and which secrets are set (values are never returned)
clusto_list_sessionsTerminal and agent sessions across the cluster with status, node and project
clusto_list_projectsSaved projects with their directory, node and run-as users
clusto_project_createAdds a Clusto project for an existing folder on this node (name, absolute dir, optional description and run_as_user); an agent calls it when you ask, for example "create a project in Clusto for C:\Repos\SlotLaps". Under an agent session the folder must be one its own OS account owns, and every Run as on the project must be that same non-root account; otherwise it is refused with a message. Editing and deleting projects stay in the app. The Clusto Assistant does not get this tool
clusto_list_teamsAgent teams with their status and members
clusto_list_reportsLists reports from the Reports feed, newest first, filtered by text, tag, level, unread, archived or age
clusto_read_reportReads one report in full by id
clusto_github_prsOpen pull requests across your GitHub accounts: check status, review decision, requested reviewers and failed runs
clusto_azure_devopsActive pull requests and assigned work items across your Azure DevOps accounts, with build status and reviewer votes
clusto_daemon_logTails the clustod log of a node, optionally filtered to lines containing a string; tokens are redacted
clusto_change_historyRead-only: lists the change history of the cluster's nodes (config versions, edits and deletes of projects, tasks, workspaces, teams, SSH connections, removed nodes), optionally by kind, node and limit
clusto_change_entryRead-only: one change history entry by id with its before and after state; secrets show as changed, never their value. Agents cannot restore
clusto_timer_statusThe running time-tracking timer, today's entries and the time projects
clusto_timer_startStarts a timer, stopping the account's running one
clusto_timer_stopStops the running timer
clusto_time_entriesLists the account's time entries in a date range, with the range total and the time projects
clusto_time_entry_createBooks a finished time entry
clusto_time_entry_updateChanges one time entry by id
clusto_time_entry_deleteDeletes one time entry by id
clusto_time_project_createCreates a time project (name, optional client and color)
clusto_time_project_updateRenames, recolors, regroups, archives or unarchives a time project
clusto_time_project_deleteDeletes a time project; its entries stay, without a project
clusto_factory_projectsLists the factory projects with their autonomy and card counts per column
clusto_factory_file_cardFiles a Backlog card labelled proposed, for you to accept
clusto_factory_cardsLists the cards of one factory project (id, title, column, labels, brief), optionally only one column
clusto_factory_move_cardMoves a factory card to the end of a column (see below)
clusto_factory_take_cardHolds a factory card for the agent's own chat or session, so the factory and other agents leave it alone (see Take a card)
clusto_factory_release_cardReleases a card the agent holds, optionally into a column

The note tools (clusto_notes_search, clusto_notes_read, clusto_notes_list, clusto_notes_write, clusto_notes_move and clusto_notes_delete) accept an optional vault (id or name from clusto_notes_vaults). Without it they use the node's first vault. An agent can only reach vaults the node it talks to keeps. Moving never overwrites an existing note, and deleting removes one note or an empty folder.

The docs, guide, CLI help, MCP status, cluster status and configuration, session, project, team, report, GitHub, Azure DevOps and daemon log tools are read-only. Fifteen of them were once only in Clusto Assistant chats; every agent now has them. Secret values, forge tokens and the cluster token are never returned. The Assistant itself still has no task write tool and proposes changes as action cards.

The task write tools do what the clusto task CLI does, under the same rule: a session credential changes only tasks that run as its own OS account on its own node. Agents use them only when you ask, and clusto_task_trigger can cost time or money.

The timer, time entry and time project tools act on time tracking: agents use them only when you ask, only for the account that owns the running timer, and they change or delete only that account's entries. Time connectors and imports stay in the app.

The factory tools let an agent find a project, list its cards, file a proposed card and move a card between columns. Agents move a card only when you ask: Ready hands it to agents on an Auto project, and Done ends its review. Projects, rules, runs and plans stay yours.

The same tools run from a shell with clusto notes, clusto time and clusto tool, below.

Lessons ​

Agents call clusto_propose_lesson after you correct them or after a fix attempt fails. A proposal does nothing until you approve it; approval is the trust boundary. Text that looks like a secret is refused.

Pending proposals appear at the top of the Lessons card:

  • This repository approves the lesson for the repository it came from.
  • Everywhere approves it globally. Global lessons are written into the managed instruction section of every tool on every node.
  • Choose nodes... next to the approve buttons approves the lesson but limits it to the nodes and OS accounts you tick.
  • Drop discards it. Approved lessons can be dropped the same way.

An approved lesson reaches every agent on every node unless you limit it. The Limit button on an approved row opens the same node and OS account picker, and the row then shows where it applies (for example "on 2 nodes" or "for daniel"). A limited lesson still syncs to every node, but agents on the other nodes and accounts never see it. Limiting is for lessons that name something private to one machine or account.

The same from the CLI:

bash
clusto lessons pending                      # proposals waiting for review
clusto lessons approve <id> [--global]      # this repository, or everywhere
clusto lessons drop <id>                    # proposed or approved
clusto lessons list [--repo <path>]         # approved lessons (default: current directory)
clusto lessons propose "<title>" "<body>" [--repo <path>]

Tools from a shell ​

Anything that can run shell commands can use the clusto mcp tools without MCP. These commands talk to the local daemon through the same access file as clusto lessons, and run the tool code an agent would:

bash
clusto notes vaults | ls | search <query> | read <path> | write <path> | mv <from> <to> | rm <path>
clusto time status | start | stop | ls | add | edit | rm
clusto time project add | edit | rm
clusto tool ls [--json]
clusto tool call <name> '<json arguments>'

clusto notes takes --vault (id or name). clusto notes write reads the text from --content, --file or standard input, and needs --base-sha256 (printed by read) to update an existing note. clusto time add "standup" --start 2026-11-09T09:00 --minutes 30 --project Clusto books a finished entry. Any tool without its own command is reachable by name, for example clusto tool call clusto_github_prs '{}'. See the CLI reference.

Agent memory ​

Claude Code keeps per-project memory in ~/.claude/projects/<path>/memory. Clusto mirrors it per repository, keyed by the git remote, so the memory follows the repository across nodes, clones, and folder renames. The Agent memory card lists each repository and its file count.

  • MEMORY.md is Claude's own index and is not mirrored. When Clusto writes a memory file into a checkout, it adds an index line for it.
  • Files that look like secrets are not synced.
  • Folders whose checkout no longer exists are not mirrored.

Backups ​

Cluster replication is not a backup: a bad save replicates everywhere. The Backups card stores versions of Agent Docs, assets, variables, lessons, memory, and Markdown notes off the cluster, and restores any of them.

TargetWhereHistory
Clusto cloud (default)Your Clusto accountFree: 10 versions / 50 MB. Pro and Team: 100 versions / 500 MB. Oldest versions are pruned.
Git repositoryA folder on the node, default ~/.clusto/backup (the folder field has a browse button that picks a folder on the node), with an optional private remoteFull git history. Commits only when something changed.
S3The bucket of the first vault with sync on, under the .clusto-backup/ prefixKeeps the configured number of versions
OffNo backupsNot recommended
  • Cloud backups are encrypted in the app with your cloud-sync passphrase before upload, so the daemon never holds cloud credentials and the cloud stores only ciphertext. They run from the app while you are signed in with sync unlocked.
  • Git and S3 backups run on the node about once an hour when something changed. Git commits and pushes as the account that owns the folder.
  • Because Agent Docs sync tracks every skill, subagent, and command, including binary skill files, these backups cover your whole agent setup.
  • Snapshots include the notes of every vault the node keeps, tagged by vault. Notes larger than 1 MB are skipped, and a very large vault carries only its newest notes (up to 16 MB).

Back up now forces a backup (F1: Back up agent knowledge now). Versions lists stored versions; Restore replaces the knowledge records cluster-wide with that version and overwrites the notes contained in the backup. Notes that are not in the backup are kept. Notes are written only into vaults the restoring node keeps.

The target can also be set in config.toml:

toml
[knowledge.backup]
target = "git"                 # cloud | git | s3 | off
git_dir = "~/.clusto/backup"   # git: repository folder
git_remote = "git@example.com:me/agent-backup.git"   # git: optional private remote
s3_prefix = ".clusto-backup"   # s3: key prefix inside the first synced vault's bucket
keep_versions = 30             # s3: versions kept

clusto doctor ​

clusto doctor [--fix]

Shows this node's AI setup, the same checks as the AI setup card, plus the CPU headroom and Peer links checks. --fix repairs what is missing. Before the AI setup, the command also checks the local daemon install and prints a diagnosis; see the CLI reference. If the daemon cannot be reached, the AI setup part prints AI setup: not checked - <reason>. Inside a session that holds a limited session credential (any session not running as the daemon's own account), --fix shows the checks without repairing them: use Fix now in the app or pass the node admin token with --token.

Command palette ​

CommandDoes
Go to KnowledgeOpens the Knowledge view
Re-run AI setup on this nodeRepairs MCP registration, the managed section, the waiting-status hooks, and the access file
Open Node doctorOpens Settings > Node Doctor
Fix agent setup on all nodesRepairs the AI setup on every cluster node
Back up agent knowledge nowRuns a backup to the configured target
Refresh knowledgeReloads lessons, memory, and setup state

All but Go to Knowledge appear while the Knowledge view is open.

Clusto - remote AI coding agents over WebSocket.