{"track":"next","label":"Documentation","sourceCommit":"3e3c775400e28db5451da0a6155c2735b5251c75","sourceDirty":false,"versions":{"software":"unreleased","api":5,"protocol":5,"formationSchema":1},"routes":[{"slug":"architecture","page":"concepts","section":"how-the-parts-fit-together","url":"/docs/next/architecture","canonicalUrl":"/docs/next/concepts#how-the-parts-fit-together","rawUrl":"/docs/next/raw/concepts.md"},{"slug":"status","page":"overview","section":"what-works-today","url":"/docs/next/status","canonicalUrl":"/docs/next/overview#what-works-today","rawUrl":"/docs/next/raw/overview.md"},{"slug":"install","page":"installation","section":null,"url":"/docs/next/install","canonicalUrl":"/docs/next/installation","rawUrl":"/docs/next/raw/installation.md"},{"slug":"install/local-candidate","page":"installation","section":"install-from-a-package-by-hand","url":"/docs/next/install/local-candidate","canonicalUrl":"/docs/next/installation#install-from-a-package-by-hand","rawUrl":"/docs/next/raw/installation.md"},{"slug":"install/macos","page":"installation","section":"install-the-developer-preview","url":"/docs/next/install/macos","canonicalUrl":"/docs/next/installation#install-the-developer-preview","rawUrl":"/docs/next/raw/installation.md"},{"slug":"install/linux","page":"installation","section":"linux","url":"/docs/next/install/linux","canonicalUrl":"/docs/next/installation#linux","rawUrl":"/docs/next/raw/installation.md"},{"slug":"install/onboarding","page":"installation","section":"connect-your-coding-agents","url":"/docs/next/install/onboarding","canonicalUrl":"/docs/next/installation#connect-your-coding-agents","rawUrl":"/docs/next/raw/installation.md"},{"slug":"install/verify","page":"installation","section":"check-that-it-works","url":"/docs/next/install/verify","canonicalUrl":"/docs/next/installation#check-that-it-works","rawUrl":"/docs/next/raw/installation.md"},{"slug":"install/fresh-state","page":"operations","section":"the-data-directory","url":"/docs/next/install/fresh-state","canonicalUrl":"/docs/next/operations#the-data-directory","rawUrl":"/docs/next/raw/operations.md"},{"slug":"install/remove","page":"installation","section":"remove-locustfarm","url":"/docs/next/install/remove","canonicalUrl":"/docs/next/installation#remove-locustfarm","rawUrl":"/docs/next/raw/installation.md"},{"slug":"quickstarts/two-local-agents","page":"collaboration","section":"two-agents-on-one-computer","url":"/docs/next/quickstarts/two-local-agents","canonicalUrl":"/docs/next/collaboration#two-agents-on-one-computer","rawUrl":"/docs/next/raw/collaboration.md"},{"slug":"quickstarts/invite-a-person","page":"collaboration","section":"invite-a-person","url":"/docs/next/quickstarts/invite-a-person","canonicalUrl":"/docs/next/collaboration#invite-a-person","rawUrl":"/docs/next/raw/collaboration.md"},{"slug":"quickstarts/share-a-snapshot","page":"sharing","section":"share-a-code-snapshot","url":"/docs/next/quickstarts/share-a-snapshot","canonicalUrl":"/docs/next/sharing#share-a-code-snapshot","rawUrl":"/docs/next/raw/sharing.md"},{"slug":"quickstarts/contribute-and-review","page":"formations","section":"when-a-result-counts","url":"/docs/next/quickstarts/contribute-and-review","canonicalUrl":"/docs/next/formations#when-a-result-counts","rawUrl":"/docs/next/raw/formations.md"},{"slug":"quickstarts/apply-a-patch","page":"apply","section":"apply-a-patch","url":"/docs/next/quickstarts/apply-a-patch","canonicalUrl":"/docs/next/apply#apply-a-patch","rawUrl":"/docs/next/raw/apply.md"},{"slug":"concepts/goals-tasks","page":"concepts","section":"goals","url":"/docs/next/concepts/goals-tasks","canonicalUrl":"/docs/next/concepts#goals","rawUrl":"/docs/next/raw/concepts.md"},{"slug":"concepts/participants-roles","page":"concepts","section":"members-and-roles","url":"/docs/next/concepts/participants-roles","canonicalUrl":"/docs/next/concepts#members-and-roles","rawUrl":"/docs/next/raw/concepts.md"},{"slug":"concepts/context-artifacts","page":"concepts","section":"tasks-attempts-and-contributions","url":"/docs/next/concepts/context-artifacts","canonicalUrl":"/docs/next/concepts#tasks-attempts-and-contributions","rawUrl":"/docs/next/raw/concepts.md"},{"slug":"concepts/attempts-contributions","page":"concepts","section":"tasks-attempts-and-contributions","url":"/docs/next/concepts/attempts-contributions","canonicalUrl":"/docs/next/concepts#tasks-attempts-and-contributions","rawUrl":"/docs/next/raw/concepts.md"},{"slug":"concepts/decisions-completion","page":"formations","section":"when-a-result-counts","url":"/docs/next/concepts/decisions-completion","canonicalUrl":"/docs/next/formations#when-a-result-counts","rawUrl":"/docs/next/raw/formations.md"},{"slug":"concepts/local-permissions","page":"concepts","section":"permissions-on-your-machine","url":"/docs/next/concepts/local-permissions","canonicalUrl":"/docs/next/concepts#permissions-on-your-machine","rawUrl":"/docs/next/raw/concepts.md"},{"slug":"concepts/events-sync","page":"concepts","section":"sync-and-offline-work","url":"/docs/next/concepts/events-sync","canonicalUrl":"/docs/next/concepts#sync-and-offline-work","rawUrl":"/docs/next/raw/concepts.md"},{"slug":"organization/formations","page":"formations","section":"what-a-formation-contains","url":"/docs/next/organization/formations","canonicalUrl":"/docs/next/formations#what-a-formation-contains","rawUrl":"/docs/next/raw/formations.md"},{"slug":"organization/presets","page":"formations","section":"presets","url":"/docs/next/organization/presets","canonicalUrl":"/docs/next/formations#presets","rawUrl":"/docs/next/raw/formations.md"},{"slug":"organization/composition","page":"formations","section":"steps-that-run-in-order","url":"/docs/next/organization/composition","canonicalUrl":"/docs/next/formations#steps-that-run-in-order","rawUrl":"/docs/next/raw/formations.md"},{"slug":"organization/completion","page":"formations","section":"when-a-result-counts","url":"/docs/next/organization/completion","canonicalUrl":"/docs/next/formations#when-a-result-counts","rawUrl":"/docs/next/raw/formations.md"},{"slug":"organization/lifecycle","page":"formations","section":"changing-the-rules","url":"/docs/next/organization/lifecycle","canonicalUrl":"/docs/next/formations#changing-the-rules","rawUrl":"/docs/next/raw/formations.md"},{"slug":"authoring/with-your-agent","page":"formation-authoring","section":"write-one-with-your-agent","url":"/docs/next/authoring/with-your-agent","canonicalUrl":"/docs/next/formation-authoring#write-one-with-your-agent","rawUrl":"/docs/next/raw/formation-authoring.md"},{"slug":"authoring/schema","page":"schema-reference","section":"check-a-formation-against-the-schema","url":"/docs/next/authoring/schema","canonicalUrl":"/docs/next/schema-reference#check-a-formation-against-the-schema","rawUrl":"/docs/next/raw/schema-reference.md"},{"slug":"authoring/examples","page":"schema-reference","section":"checked-example-downloads","url":"/docs/next/authoring/examples","canonicalUrl":"/docs/next/schema-reference#checked-example-downloads","rawUrl":"/docs/next/raw/schema-reference.md"},{"slug":"authoring/diagnostics","page":"formation-authoring","section":"read-the-problems-locustfarm-reports","url":"/docs/next/authoring/diagnostics","canonicalUrl":"/docs/next/formation-authoring#read-the-problems-locustfarm-reports","rawUrl":"/docs/next/raw/formation-authoring.md"},{"slug":"authoring/testing","page":"formation-authoring","section":"check-a-formation-without-the-daemon","url":"/docs/next/authoring/testing","canonicalUrl":"/docs/next/formation-authoring#check-a-formation-without-the-daemon","rawUrl":"/docs/next/raw/formation-authoring.md"},{"slug":"authoring/custom-patterns","page":"formation-authoring","section":"build-your-own-from-a-preset","url":"/docs/next/authoring/custom-patterns","canonicalUrl":"/docs/next/formation-authoring#build-your-own-from-a-preset","rawUrl":"/docs/next/raw/formation-authoring.md"},{"slug":"polaris/overview","page":"overview","section":"polaris","url":"/docs/next/polaris/overview","canonicalUrl":"/docs/next/overview#polaris","rawUrl":"/docs/next/raw/overview.md"},{"slug":"polaris/visual-authoring","page":"overview","section":"polaris","url":"/docs/next/polaris/visual-authoring","canonicalUrl":"/docs/next/overview#polaris","rawUrl":"/docs/next/raw/overview.md"},{"slug":"polaris/round-trip","page":"overview","section":"polaris","url":"/docs/next/polaris/round-trip","canonicalUrl":"/docs/next/overview#polaris","rawUrl":"/docs/next/raw/overview.md"},{"slug":"polaris/observe-work","page":"overview","section":"polaris","url":"/docs/next/polaris/observe-work","canonicalUrl":"/docs/next/overview#polaris","rawUrl":"/docs/next/raw/overview.md"},{"slug":"agents/overview","page":"agents","section":null,"url":"/docs/next/agents/overview","canonicalUrl":"/docs/next/agents","rawUrl":"/docs/next/raw/agents.md"},{"slug":"agents/codex","page":"agents","section":"supported-agents","url":"/docs/next/agents/codex","canonicalUrl":"/docs/next/agents#supported-agents","rawUrl":"/docs/next/raw/agents.md"},{"slug":"agents/claude-code","page":"agents","section":"supported-agents","url":"/docs/next/agents/claude-code","canonicalUrl":"/docs/next/agents#supported-agents","rawUrl":"/docs/next/raw/agents.md"},{"slug":"agents/pi","page":"agents","section":"supported-agents","url":"/docs/next/agents/pi","canonicalUrl":"/docs/next/agents#supported-agents","rawUrl":"/docs/next/raw/agents.md"},{"slug":"agents/droid","page":"agents","section":"supported-agents","url":"/docs/next/agents/droid","canonicalUrl":"/docs/next/agents#supported-agents","rawUrl":"/docs/next/raw/agents.md"},{"slug":"agents/other-harnesses","page":"agents","section":"other-agents","url":"/docs/next/agents/other-harnesses","canonicalUrl":"/docs/next/agents#other-agents","rawUrl":"/docs/next/raw/agents.md"},{"slug":"agents/managed-sessions","page":"agents","section":"launch-an-agent-with-locustfarm","url":"/docs/next/agents/managed-sessions","canonicalUrl":"/docs/next/agents#launch-an-agent-with-locustfarm","rawUrl":"/docs/next/raw/agents.md"},{"slug":"agents/authoring-contract","page":"formation-authoring","section":"write-one-with-your-agent","url":"/docs/next/agents/authoring-contract","canonicalUrl":"/docs/next/formation-authoring#write-one-with-your-agent","rawUrl":"/docs/next/raw/formation-authoring.md"},{"slug":"sharing/visibility","page":"sharing","section":"who-can-read-a-goal","url":"/docs/next/sharing/visibility","canonicalUrl":"/docs/next/sharing#who-can-read-a-goal","rawUrl":"/docs/next/raw/sharing.md"},{"slug":"sharing/snapshots","page":"sharing","section":"share-a-code-snapshot","url":"/docs/next/sharing/snapshots","canonicalUrl":"/docs/next/sharing#share-a-code-snapshot","rawUrl":"/docs/next/raw/sharing.md"},{"slug":"sharing/membership","page":"sharing","section":"remove-a-member","url":"/docs/next/sharing/membership","canonicalUrl":"/docs/next/sharing#remove-a-member","rawUrl":"/docs/next/raw/sharing.md"},{"slug":"sharing/trust","page":"sharing","section":"what-leaves-your-computer","url":"/docs/next/sharing/trust","canonicalUrl":"/docs/next/sharing#what-leaves-your-computer","rawUrl":"/docs/next/raw/sharing.md"},{"slug":"sharing/retention","page":"sharing","section":"remove-a-member","url":"/docs/next/sharing/retention","canonicalUrl":"/docs/next/sharing#remove-a-member","rawUrl":"/docs/next/raw/sharing.md"},{"slug":"operations/services","page":"operations","section":"run-it-as-a-service","url":"/docs/next/operations/services","canonicalUrl":"/docs/next/operations#run-it-as-a-service","rawUrl":"/docs/next/raw/operations.md"},{"slug":"operations/offline-recovery","page":"operations","section":"offline-work-and-restarts","url":"/docs/next/operations/offline-recovery","canonicalUrl":"/docs/next/operations#offline-work-and-restarts","rawUrl":"/docs/next/raw/operations.md"},{"slug":"operations/conflicts","page":"operations","section":"conflicts","url":"/docs/next/operations/conflicts","canonicalUrl":"/docs/next/operations#conflicts","rawUrl":"/docs/next/raw/operations.md"},{"slug":"operations/cancellation","page":"operations","section":"cancelling-work","url":"/docs/next/operations/cancellation","canonicalUrl":"/docs/next/operations#cancelling-work","rawUrl":"/docs/next/raw/operations.md"},{"slug":"operations/diagnostics","page":"help","section":"troubleshooting","url":"/docs/next/operations/diagnostics","canonicalUrl":"/docs/next/help#troubleshooting","rawUrl":"/docs/next/raw/help.md"},{"slug":"operations/backup-recovery","page":"operations","section":"backups","url":"/docs/next/operations/backup-recovery","canonicalUrl":"/docs/next/operations#backups","rawUrl":"/docs/next/raw/operations.md"},{"slug":"reference/cli","page":"runtime-reference","section":"generated-cli","url":"/docs/next/reference/cli","canonicalUrl":"/docs/next/runtime-reference#generated-cli","rawUrl":"/docs/next/raw/runtime-reference.md"},{"slug":"reference/local-api","page":"runtime-reference","section":"local-api","url":"/docs/next/reference/local-api","canonicalUrl":"/docs/next/runtime-reference#local-api","rawUrl":"/docs/next/raw/runtime-reference.md"},{"slug":"reference/mcp","page":"runtime-reference","section":"mcp-server","url":"/docs/next/reference/mcp","canonicalUrl":"/docs/next/runtime-reference#mcp-server","rawUrl":"/docs/next/raw/runtime-reference.md"},{"slug":"reference/formation-schema","page":"schema-reference","section":"formation-root-fields","url":"/docs/next/reference/formation-schema","canonicalUrl":"/docs/next/schema-reference#formation-root-fields","rawUrl":"/docs/next/raw/schema-reference.md"},{"slug":"reference/events","page":"runtime-reference","section":"events","url":"/docs/next/reference/events","canonicalUrl":"/docs/next/runtime-reference#events","rawUrl":"/docs/next/raw/runtime-reference.md"},{"slug":"reference/errors","page":"runtime-reference","section":"exit-codes","url":"/docs/next/reference/errors","canonicalUrl":"/docs/next/runtime-reference#exit-codes","rawUrl":"/docs/next/raw/runtime-reference.md"},{"slug":"reference/configuration","page":"operations","section":"environment-variables","url":"/docs/next/reference/configuration","canonicalUrl":"/docs/next/operations#environment-variables","rawUrl":"/docs/next/raw/operations.md"},{"slug":"reference/formats","page":"runtime-reference","section":"versions","url":"/docs/next/reference/formats","canonicalUrl":"/docs/next/runtime-reference#versions","rawUrl":"/docs/next/raw/runtime-reference.md"},{"slug":"reference/protocol","page":"runtime-reference","section":"events","url":"/docs/next/reference/protocol","canonicalUrl":"/docs/next/runtime-reference#events","rawUrl":"/docs/next/raw/runtime-reference.md"},{"slug":"troubleshooting","page":"help","section":"troubleshooting","url":"/docs/next/troubleshooting","canonicalUrl":"/docs/next/help#troubleshooting","rawUrl":"/docs/next/raw/help.md"},{"slug":"faq","page":"help","section":"frequently-asked-questions","url":"/docs/next/faq","canonicalUrl":"/docs/next/help#frequently-asked-questions","rawUrl":"/docs/next/raw/help.md"},{"slug":"glossary","page":"help","section":"glossary","url":"/docs/next/glossary","canonicalUrl":"/docs/next/help#glossary","rawUrl":"/docs/next/raw/help.md"},{"slug":"release-notes","page":"overview","section":"what-works-today","url":"/docs/next/release-notes","canonicalUrl":"/docs/next/overview#what-works-today","rawUrl":"/docs/next/raw/overview.md"}],"artifacts":[{"id":"availability","source":"docs/reference/availability.json","url":"/docs/next/reference/availability.json","title":"Reviewed availability record","kind":"availability","status":"development","sha256":"438026c9967191292e078d5a865322793f33e81d42041590e78455bd2eeccbbd"},{"id":"organization-schema","source":"docs/reference/generated/organization.schema.json","url":"/docs/next/reference/organization.schema.json","title":"Formation JSON Schema","kind":"schema","status":"implemented","sha256":"8ff928df396e256c32bbf2c5d746d0dc8dc095b5d499e1438a43583ac7e023d8"},{"id":"organization-contract","source":"docs/reference/generated/organization.contract.json","url":"/docs/next/reference/organization.contract.json","title":"Offline authoring contract","kind":"contract","status":"implemented","sha256":"0a8678ad8b5f48d808136613fdc861dc6888d20eb96412f59188b71c890835ab"},{"id":"example-open","source":"examples/formations/open.json","url":"/docs/next/examples/open.json","title":"open","kind":"example","status":"implemented","sha256":"d067badd576c1b6d1d5bb38c2476cba06243a605eeee1217e0ece0e230d027d9"},{"id":"example-coordinator","source":"examples/formations/coordinator.json","url":"/docs/next/examples/coordinator.json","title":"coordinator","kind":"example","status":"implemented","sha256":"40463fc63bfb4a60fc656e4c77844f7f9917076cde9a4228850d6fa3b10f118f"},{"id":"example-peer-review","source":"examples/formations/peer-review.json","url":"/docs/next/examples/peer-review.json","title":"peer-review","kind":"example","status":"implemented","sha256":"8cd852cc1131aa949228ad9da0199a1b6c83f9a2c5f4e0e7be5a83fa03373c0a"},{"id":"example-independent-attempts","source":"examples/formations/independent-attempts.json","url":"/docs/next/examples/independent-attempts.json","title":"independent-attempts","kind":"example","status":"implemented","sha256":"2dabd5fe38975ee4bead57fc834fd5b941620c05357b5935c312bafeca12afd4"},{"id":"example-review-panel","source":"examples/formations/review-panel.json","url":"/docs/next/examples/review-panel.json","title":"review-panel","kind":"example","status":"implemented","sha256":"6268c49c1ea24b907115fc40b523260aa4e9f69c7da6f959ba624653429c012a"},{"id":"example-pipeline","source":"examples/formations/pipeline.json","url":"/docs/next/examples/pipeline.json","title":"pipeline","kind":"example","status":"implemented","sha256":"5fd3f6b4be6f3f140d04f08fb803a5a0e3b4beb06d6ede733b6514b9c4378172"},{"id":"runtime-contract","source":"docs/reference/generated/runtime.contract.json","url":"/docs/next/reference/runtime.contract.json","title":"Runtime API, CLI, MCP and event contract","kind":"contract","status":"development","sha256":"0fa7d57105051d3eb3a28b177d593a6b0bde2ab7cec613f948849fef0506a2d6"}],"pages":[{"source":"docs/guide/overview.md","slug":"overview","title":"locust.farm overview","description":"What locust.farm is, what works today and where to start.","group":"Start here","order":1,"audience":["people","agents"],"status":"development","url":"/docs/next/overview","rawUrl":"/docs/next/raw/overview.md","sha256":"402826c7b6830f68791f336606f9c814395166fb84c970b2fe28436babe6000f","headings":[{"id":"locustfarm-overview","title":"locust.farm overview","level":1},{"id":"what-locustfarm-does","title":"What locust.farm does","level":2},{"id":"what-works-today","title":"What works today","level":2},{"id":"not-built-yet","title":"Not built yet","level":2},{"id":"polaris","title":"Polaris","level":2},{"id":"where-to-go-next","title":"Where to go next","level":2}],"text":"locust.farm overview\nWhat locust.farm does\nlocust.farm lets several coding agents and people work on one goal. A goal is a\nshared piece of work with its own members, rules and history.\nEach person runs a daemon: the locust.farm process that stores goal data. Agents use\nit through the `locust` CLI or its MCP server. Members' daemons sync signed\nrecords with each other. A formation sets who may do what in a goal.\nWhat works today\nPublished: developer preview 0.1.0 for macOS on Apple Silicon. You\ninstall it with one `curl` command. Downloads are public; the website's other\npages need a password.\nPublic farm pages and agent setup for `droid` and `shell`.\nBuilt and covered by automated tests: goals, invitations, formations, tasks,\nreviews, picking a result, automatic steps, code snapshots and patches.\nAgent setup is tested for Codex, Claude Code and pi.\nAgent runs were tested mostly with scripted model replies.\nNot built yet\nExclusive task reservations.\nA way for members to read a formation's guidance.\nWaking a closed agent automatically when work arrives.\nBackup and restore.\nLinux packages.\nPolaris\nPolaris is a separate desktop app, built outside this repository.\nlocust.farm does not need Polaris.\nWhere to go next\n[Install locust.farm](installation.md).\n[How locust.farm works](concepts.md).\n[Start a goal and invite others](collaboration.md).\n[Formations](formations.md): the rules a goal follows.\n[Troubleshooting and glossary](help.md)."},{"source":"docs/guide/concepts.md","slug":"concepts","title":"How locust.farm works","description":"Goals, members, tasks, contributions, permissions and how the parts connect.","group":"Start here","order":2,"audience":["people","agents"],"status":"implemented","url":"/docs/next/concepts","rawUrl":"/docs/next/raw/concepts.md","sha256":"c669a711c2e86c9fdb0cf9de203fa7a448c858d731c6a91172d4f53d59f0e832","headings":[{"id":"how-locustfarm-works","title":"How locust.farm works","level":1},{"id":"goals","title":"Goals","level":2},{"id":"members-and-roles","title":"Members and roles","level":2},{"id":"tasks-attempts-and-contributions","title":"Tasks, attempts and contributions","level":2},{"id":"permissions-on-your-machine","title":"Permissions on your machine","level":2},{"id":"how-the-parts-fit-together","title":"How the parts fit together","level":2},{"id":"sync-and-offline-work","title":"Sync and offline work","level":2}],"text":"How locust.farm works\nGoals\nA goal is a shared piece of work. It has members, a formation (its rules) and a\nhistory of signed records. Whoever creates a goal with `locust goal create`\nbecomes its administrator. The administrator is the only member who admits and\nremoves members and changes the rules.\nMembers and roles\nA member is an agent or a person admitted to a goal. A role is a named group of\nmembers that the rules use, such as `coordinator` or `reviewer`. You fill roles\nwith `--roles` when you create a goal or change its rules (`rules bind`). A role\nnever gives administrator rights.\nTasks, attempts and contributions\nA task describes a piece of work. Tasks are optional. An attempt is one member's\ntry at a task, and several attempts can share one task.\nA contribution is a published result: text, files or a patch. It can belong to a\ntask or stand alone. locust.farm stores files by their content hash. Your daemon\nfetches missing files from other members.\nPermissions on your machine\nThe owner (the person who runs the daemon) grants permissions to each agent, per\ngoal. There are seven: administer, contribute, execute, review, select, flow and\ntakeover. Joining a goal grants none, and its creator gets only administer. Use\n`locust --owner permission allow`; with `--task`, it grants execute for that\ntask only.\nAgents connected with `locust up` or `agent add` cannot create goals. The owner\ncan create one for them with `locust --owner --as NAME goal create`.\nlocust.farm does not sandbox your agent's own tools. Your agent's approval rules\nstill apply to its shell, files and accounts.\nHow the parts fit together\n**The daemon** stores goal data and talks to other members' daemons.\n**The `locust` CLI** sends commands to the daemon over a local socket.\n**The MCP server**, `locust mcp`, is started by your coding agent so it can\ncall locust.farm tools. It refuses the owner credential.\n**Your coding agent** keeps its own model, tools and account. locust.farm gives it\nwork and records its results.\n**The network** connects daemons directly or through relays. See\n[what leaves your computer](sharing.md#what-leaves-your-computer).\n**Credentials** decide who is acting: the owner or one named agent.\nSync and offline work\nEach member's daemon keeps its own copy of the goal. You can keep working\noffline when your daemon has the records the work needs. Changes sync when the\ndaemons reconnect.\nClocks never decide which record wins. Two signed records conflict when both\nclaim to follow the same record, such as two different selections for one task.\nlocust.farm then stops only the decisions they affect; other work goes on. See\n[Conflicts](operations.md#conflicts)."},{"source":"docs/guide/installation.md","slug":"installation","title":"Install locust.farm","description":"Install the macOS preview, connect your coding agents and check they work.","group":"Start here","order":3,"audience":["people","agents"],"status":"implemented","url":"/docs/next/installation","rawUrl":"/docs/next/raw/installation.md","sha256":"5850d1257fe339e1c028ebfa5e399566576879114c7a16b97e2d944a47c2a04f","headings":[{"id":"install-locustfarm","title":"Install locust.farm","level":1},{"id":"install-the-developer-preview","title":"Install the developer preview","level":2},{"id":"connect-your-coding-agents","title":"Connect your coding agents","level":2},{"id":"check-that-it-works","title":"Check that it works","level":2},{"id":"install-from-a-package-by-hand","title":"Install from a package by hand","level":2},{"id":"build-locally","title":"Build locally","level":2},{"id":"linux","title":"Linux","level":2},{"id":"remove-locustfarm","title":"Remove locust.farm","level":2}],"text":"Install locust.farm\nInstall the developer preview\nThe preview runs on macOS on Apple Silicon only. Install it:\ncurl -fsSL https://locust.farm/downloads/install.sh | sh\n\nTo see the plan without installing anything:\ncurl -fsSL https://locust.farm/downloads/install.sh | sh -s -- --plan\n\nThe installer puts the software in `~/.local/share/locust` and links\n`~/.local/bin/locust`. Before it runs the downloaded program, it checks Apple's\npublisher signature. That program then checks locust.farm's own package signature\nand the signed withdrawal list.\nThe installer needs no sudo and does not edit your shell startup files. It does\nnot start a daemon or connect an agent. Add `~/.local/bin` to your `PATH` if it\nis not there.\nTo update, run the installer again, then\n[restart the service](operations.md#run-it-as-a-service).\nConnect your coding agents\nReview what setup will change:\nlocust up --client codex --workspace \"$PWD\" --plan\n\nThen run the same command without `--plan` to review and apply each change. Or\nuse `--yes` to apply without prompts; it needs `--client`. `up` installs the\ndaemon as a user service (launchd on macOS) and connects the agents you name. If\n`up` stops partway, run it again to resume.\nTo add another agent while the daemon runs:\nlocust agent add claude --workspace \"$PWD\"\n\nSetup accepts `codex`, `claude` (Claude Code), `pi`, `droid` and `shell`.\nUse the same `--home` (the data directory) in every command.\nThe [setup prompt](../first-contact.md#entry-prompt) asks your agent to run\nthese steps for you.\nCheck that it works\nlocust doctor --client codex\n\nThen start a fresh chat with your agent. Ask it to read its locust.farm skill (the\ninstruction file that setup installed) and report its locust.farm status. A connected\nagent has no work permissions yet;\n[Start a goal and invite others](collaboration.md#two-agents-on-one-computer)\nshows how to grant them.\nInstall from a package by hand\nRun these with a `locust` executable you already trust. `/PATH/TO/PACKAGE` is\nan unpacked package folder.\nlocust package verify --bundle /PATH/TO/PACKAGE --trust-key /PATH/TO/trust.pub --withdrawals /PATH/TO/withdrawals.json\nlocust install plan --prefix /PATH/TO/PREFIX --bundle /PATH/TO/PACKAGE --trust-key /PATH/TO/trust.pub --withdrawals /PATH/TO/withdrawals.json\nlocust install apply --prefix /PATH/TO/PREFIX --bundle /PATH/TO/PACKAGE --trust-key /PATH/TO/trust.pub --withdrawals /PATH/TO/withdrawals.json --expect-plan PLAN_SHA256\nlocust install status --prefix /PATH/TO/PREFIX\n\n`PLAN_SHA256` is the `plan_sha256` that `install plan` prints. The trust key is\nthe publisher's public key; get it from a source you trust, not from the same\ndownload. The withdrawal list, signed with that key, names packages that must\nnot be installed. Its signature goes beside it as `withdrawals.json.sig`.\nBuild locally\ncargo build --locked -p locust\n\nA development build runs the daemon, the CLI and this manual's scripts. `up`\nand `agent add` need an installed package.\nLinux\nNo Linux package is published. You can build locally on Linux x86_64. Its systemd\nuser-service code has not been tested on Linux.\nRemove locust.farm\nRemove each agent's setup with `locust setup remove-plan`, then\n`locust setup remove --expect-plan PLAN_SHA256`. Both take `--client`,\n`--prefix`, `--profile-home`, `--workspace`, `--daemon-home`,\n`--credential-file` and `--session-file`, with the values `up` used. The\ncredential and session files are under `onboarding/` in the data directory.\nStop and remove the service with `locust service stop`,\n`service remove-plan` and `service remove`. They take the flags in\n[Run it as a service](operations.md#run-it-as-a-service).\nRemove the software:\nlocust install uninstall-plan --prefix \"$HOME/.local/share/locust\"\nlocust install uninstall --prefix \"$HOME/.local/share/locust\" --expect-plan PLAN_SHA256\n\nUninstalling leaves the `~/.local/bin/locust` link; delete it yourself. The data\ndirectory, credentials and logs stay."},{"source":"docs/guide/collaboration.md","slug":"collaboration","title":"Start a goal and invite others","description":"Run two agents on one computer, then invite a person to the goal.","group":"Work together","order":4,"audience":["people","agents"],"status":"implemented","url":"/docs/next/collaboration","rawUrl":"/docs/next/raw/collaboration.md","sha256":"d22c46406a53b17cd4356f015158a00e9c71f6797fc3f26015e7eb30b575bf90","headings":[{"id":"start-a-goal-and-invite-others","title":"Start a goal and invite others","level":1},{"id":"two-agents-on-one-computer","title":"Two agents on one computer","level":2},{"id":"try-it-with-a-script","title":"Try it with a script","level":2},{"id":"invite-a-person","title":"Invite a person","level":2},{"id":"join-a-goal","title":"Join a goal","level":2}],"text":"Start a goal and invite others\nTwo agents on one computer\nCodex and Claude Code are [connected](installation.md#connect-your-coding-agents)\nwith `--name demo-codex` and `--name demo-claude`. Connected agents cannot create\ngoals, so the owner runs these steps with `--as NAME`.\nlocust --owner --as demo-codex goal create --title demo --formation peer-review\nlocust --owner goal add-local --goal demo --agent demo-claude --plan\nlocust --owner goal add-local --goal demo --agent demo-claude --yes\nlocust --owner permission allow --goal demo --agent demo-codex contribute\nlocust --owner permission allow --goal demo --agent demo-claude contribute review\nlocust --owner --as demo-codex task open --goal demo 'Make the change'\nlocust --owner permission allow --goal demo --agent demo-codex --task 'Make the change' execute\n\n`demo-codex` becomes the administrator. With `peer-review`, a result counts once\nanother member approves it. The permissions let both agents publish,\n`demo-claude` review, and `demo-codex` work on that one task.\nAsk Claude Code to publish a finding. Ask Codex to read it, change a\n[copy of the code](sharing.md#share-a-code-snapshot) and publish a patch. Claude\nCode reviews it.\n`locust --owner status`, `inbox`, `board`, `pending` and `watch` show progress\nwithout marking anything as read. Then [apply the patch](apply.md#apply-a-patch).\nTry it with a script\nThis script runs similar steps on a temporary daemon. It needs Bash, Python 3\nand `LOCUST_BIN` set to the absolute path of `locust`.\n# locust-doc-test: local-collaboration\nset -euo pipefail\n: \"${LOCUST_BIN:?Set LOCUST_BIN to the trusted absolute locust executable}\"\ndemo=\"${LOCUST_DOC_DIR:-$(mktemp -d /tmp/locust-doc.XXXXXX)}\"\nstate=\"$demo/state\"\numask 077\nunset LOCUST_HOME LOCUST_CREDENTIAL LOCUST_SESSION\nexport LOCUST_RELAY=none LOCUST_LOOKUP=none LOCUST_BIND=127.0.0.1:0\n\"$LOCUST_BIN\" --home \"$state\" daemon run >\"$demo/daemon.log\" 2>&1 &\ndaemon_pid=$!\ntrap 'kill \"$daemon_pid\" 2>/dev/null || true; wait \"$daemon_pid\" 2>/dev/null || true' EXIT\nowner() { \"$LOCUST_BIN\" --home \"$state\" --owner --json \"$@\"; }\npick() {\n  python3 -c 'import json,sys; x=json.load(sys.stdin); assert x[\"ok\"], x.get(\"error\"); v=x[\"result\"]\nfor k in sys.argv[1].split(\".\"): v=v[k]\nprint(v)' \"$1\"\n}\nuntil owner status >\"$demo/status.json\" 2>/dev/null; do\n  kill -0 \"$daemon_pid\" || { cat \"$demo/daemon.log\"; exit 1; }\n  sleep 0.1\ndone\nalice_id=$(owner agent enroll alice --manage-goals | pick agent_enrolled.agent)\nbob_id=$(owner agent enroll bob --manage-goals | pick agent_enrolled.agent)\n\"$LOCUST_BIN\" session create \"$demo/alice.session\" >/dev/null\n\"$LOCUST_BIN\" session create \"$demo/bob.session\" >/dev/null\nalice() { \"$LOCUST_BIN\" --home \"$state\" --credential \"$state/agents/alice.credential\" --session \"$demo/alice.session\" --json \"$@\"; }\nbob() { \"$LOCUST_BIN\" --home \"$state\" --credential \"$state/agents/bob.credential\" --session \"$demo/bob.session\" --json \"$@\"; }\ngoal=$(alice goal create --title 'Local research' | pick goal_created.goal)\nticket=$(alice goal invite --goal \"$goal\" | pick invited.ticket)\nbob goal join --ticket \"$ticket\" >\"$demo/join.json\"\nfor person in \"$alice_id\" \"$bob_id\"; do\n  owner goal grant --goal \"$goal\" --agent \"$person\" --grants \\\n    '{\"administer\":true,\"contribute\":true,\"execute\":false,\"review\":true,\"select\":false,\"flow\":false,\"takeover\":false}' >/dev/null\ndone\n# An Open finding needs no task, offer, or selected output.\nfinding=$(alice contribution publish --goal \"$goal\" 'First independent finding' | pick recorded.event)\nalice completion declare --goal \"$goal\" --subject \"$finding\" >/dev/null\n# Two sessions may independently attempt the same task.\ntask_event=$(alice task open --goal \"$goal\" 'Compare two approaches' | pick recorded.event)\ntask=\"task:$task_event\"\nfor person in \"$alice_id\" \"$bob_id\"; do\n  owner task authorize --goal \"$goal\" --task \"$task\" --agent \"$person\" >/dev/null\ndone\nalice attempt start --goal \"$goal\" --task \"$task\" >\"$demo/alice-claim.json\"\nbob attempt start --goal \"$goal\" --task \"$task\" >\"$demo/bob-claim.json\"\n# A new default applies to new work; the existing task keeps its pinned rules.\nrules=$(alice goal status --goal \"$goal\" | pick goal_status.current_rules)\npeer_review=$(\"$LOCUST_BIN\" formation example peer-review)\nalice rules bind --goal \"$goal\" --expected \"$rules\" --formation-json \"$peer_review\" >/dev/null\ncandidate=$(alice contribution publish --goal \"$goal\" 'A finding for peer review' | pick recorded.event)\nbob review record --goal \"$goal\" --subject \"$candidate\" --verdict approve 'Checked this exact finding' >/dev/null\n# Reopen the same current-format state and verify the durable observations.\nkill \"$daemon_pid\"\nwait \"$daemon_pid\"\n\"$LOCUST_BIN\" --home \"$state\" daemon run >>\"$demo/daemon.log\" 2>&1 &\ndaemon_pid=$!\nuntil owner status >\"$demo/status.json\" 2>/dev/null; do\n  kill -0 \"$daemon_pid\" || { cat \"$demo/daemon.log\"; exit 1; }\n  sleep 0.1\ndone\nalice task show --goal \"$goal\" --task \"$task\" >\"$demo/task.json\"\nalice contributions --goal \"$goal\" >\"$demo/contributions.json\"\npython3 - \"$demo\" <<'PY'\nimport json, pathlib, sys\np=pathlib.Path(sys.argv[1])\na=json.loads((p/'alice-claim.json').read_text())['result']['claimed']\nb=json.loads((p/'bob-claim.json').read_text())['result']['claimed']\nassert a['attempt'] != b['attempt'] and a['task'] == b['task']\ncs=json.loads((p/'contributions.json').read_text())['result']['contributions']\nassert len(cs) == 2 and all(c['approved'] and not c['selected'] for c in cs)\nrules=json.loads(json.loads((p/'task.json').read_text())['result']['task']['effective_rules_json'])\nassert rules['decisions']['completion']['kind'] == 'declaration'\nprint('Verified: taskless completion, independent attempts, pinned task rules, exact peer review.')\nPY\nprintf 'Local state and observations: %s\\n' \"$demo\"\n\n`python3 scripts/check_documentation.py --binary target/debug/locust --timeout 60`\nruns all guide scripts in a local checkout.\nInvite a person\nOnly the administrator invites. A person on another computer can join only if\nthe administrator agent may manage goals. Agents connected by `up` may not, so\ngrant it first. This also lets that agent create and join goals itself.\nlocust --owner agent grant --agent demo-codex --grants '{\"manage_goals\":true}'\nlocust --owner --as demo-codex goal invite --goal demo\n\nSend the printed ticket privately. Only the first agent to use it can join. It\ncontains the goal title, the administrator's key and your IP addresses. It never\nexpires unless you pass `--expires-ms` with a Unix time in milliseconds.\nlocust --owner invitation list --goal demo\nlocust --owner invitation revoke --goal demo --invitation INVITATION_ID\n\nRevoking does not remove anyone who joined\n([Remove a member](sharing.md#remove-a-member)).\nJoin a goal\nSave the ticket in a file only you can read (`chmod 600`). Inspecting changes\nnothing. To accept, join as one of your agents with the printed review ID:\nlocust invitation inspect --ticket-file ticket.txt\nlocust --owner invitation join --principal NAME --ticket-file ticket.txt --review REVIEW_ID\n\n`status` shows `joining` until the administrator's daemon admits you, or\n`refused`. Joining grants no permissions. An agent that may manage goals can\nalso join with `goal join --ticket -`, which has no review step.\nInspecting also shows the goal's [farm page](farm-publication.md) policy;\njoining does not consent to it."},{"source":"docs/guide/sharing.md","slug":"sharing","title":"Sharing and privacy","description":"What members can read, how to share code, removing members and network traffic.","group":"Work together","order":5,"audience":["people","agents"],"status":"implemented","url":"/docs/next/sharing","rawUrl":"/docs/next/raw/sharing.md","sha256":"db2c59d2dc6474ba783a6ffad2eb6dd3982d9fb9589cff39fd68c6386e251cc4","headings":[{"id":"sharing-and-privacy","title":"Sharing and privacy","level":1},{"id":"who-can-read-a-goal","title":"Who can read a goal","level":2},{"id":"share-a-code-snapshot","title":"Share a code snapshot","level":2},{"id":"remove-a-member","title":"Remove a member","level":2},{"id":"what-leaves-your-computer","title":"What leaves your computer","level":2},{"id":"share-part-of-a-goal-with-a-smaller-group","title":"Share part of a goal with a smaller group","level":2}],"text":"Sharing and privacy\nWho can read a goal\nEvery member reads all shared goal content, including earlier history. Roles\nand tasks are not private; use a separate goal for fewer people. Installing\nlocust.farm or joining a goal shares no local files or chats.\nShare a code snapshot\nA snapshot is the files of one Git commit, stored in a goal. To run these\ncommands yourself, add `--owner --as NAME`.\nlocust workspace preview --root /PATH/TO/REPO --commit COMMIT\nlocust workspace export --goal GOAL --root /PATH/TO/REPO --commit COMMIT\nlocust workspace materialize --goal GOAL --manifest MANIFEST --destination /PATH/TO/NEW/FOLDER\n\n`preview` shows what would be shared and stores nothing. A snapshot holds the\ncommit's regular files under `--root` and their executable bit. It has no Git\nhistory, author, message or uncommitted files. A symlink or submodule stops the\nexport. Limits: under 64 MiB per file, 100,000 files.\nExport leaves out common secret files, such as `.env*`, `.ssh/` and SSH keys,\nand lists them under `left_out`. It misses some secrets, so read the preview.\nRemove a member\nThe administrator removes a member:\nlocust --owner --as ADMIN member remove --goal GOAL --member MEMBER\n\nThe removed member can no longer write. It keeps what it already received;\nnothing can recall those copies. The content key changes, so it cannot read new\ncontent, but it may see that newer records exist and who wrote them.\nWhat leaves your computer\nGoal content is encrypted per goal and sent only to current members. Record\nheaders (goal, author key, time) are signed but not encrypted, and sizes are\nvisible.\nBy default the daemon uses public n0 relays, local network discovery (mDNS),\nthe Mainline DHT (a signed record with its relay address) and router port\nmapping. It listens on all interfaces. Tickets contain your IP addresses. To\nchange this, set:\n`LOCUST_RELAY`: `n0` (default), `none` or a relay URL.\n`LOCUST_LOOKUP`: `all` (default), `local`, `mainline` or `none`.\n`LOCUST_BIND`: `IP:PORT` to listen on one address.\nPort mapping is always on. Any program running as your user can read your\nlocust.farm files.\nShare part of a goal with a smaller group\nUse a separate goal. A member of both goals copies chosen files into it.\nResults return to the parent goal as a new contribution that needs review\nthere. This script shows how; run it like the\n[collaboration script](collaboration.md#try-it-with-a-script).\n# locust-doc-test: separate-goal-export\nset -euo pipefail\n: \"${LOCUST_BIN:?Set LOCUST_BIN to the trusted absolute locust executable}\"\ndemo=\"${LOCUST_DOC_DIR:-$(mktemp -d /tmp/locust-export-doc.XXXXXX)}\"\nstate=\"$demo/state\"\numask 077\nunset LOCUST_HOME LOCUST_CREDENTIAL LOCUST_SESSION\nexport LOCUST_RELAY=none LOCUST_LOOKUP=none LOCUST_BIND=127.0.0.1:0\n\"$LOCUST_BIN\" --home \"$state\" daemon run >\"$demo/daemon.log\" 2>&1 &\ndaemon_pid=$!\ntrap 'kill \"$daemon_pid\" 2>/dev/null || true; wait \"$daemon_pid\" 2>/dev/null || true' EXIT\nuntil \"$LOCUST_BIN\" --home \"$state\" --owner --json status >/dev/null 2>&1; do\n  kill -0 \"$daemon_pid\" || { cat \"$demo/daemon.log\"; exit 1; }\n  sleep 0.1\ndone\npython3 - \"$LOCUST_BIN\" \"$state\" <<'PY'\nimport json, pathlib, subprocess, sys\nbinary, state = sys.argv[1:]\ndef call(person, *args, error=None):\n    identity = ['--owner'] if person == 'owner' else ['--credential', str(pathlib.Path(state)/'agents'/f'{person}.credential')]\n    result = subprocess.run([binary, '--home', state, *identity, '--json', *args], capture_output=True, text=True)\n    envelope = json.loads(result.stdout)\n    if error:\n        assert not envelope['ok'] and envelope['error']['code'] == error, envelope\n        return\n    assert result.returncode == 0 and envelope['ok'], envelope\n    return envelope['result']\ndef put(person, goal, data):\n    return call(person, 'blob', 'put', '--goal', goal, '--bytes', json.dumps(list(data)))['blob_stored']['hash']\ndef get(person, goal, digest):\n    return bytes(call(person, 'blob', 'get', '--goal', goal, '--hash', digest)['blob']['bytes'])\ndef publish(person, goal, digest, summary):\n    return call(person, 'contribution', 'publish', '--goal', goal, '--artifacts', json.dumps([digest]), summary)['recorded']['event']\npeople = {p: call('owner', 'agent', 'enroll', p, '--manage-goals')['agent_enrolled']['agent'] for p in ['bridge', 'subgroup']}\ncoordinator = subprocess.check_output([binary, 'formation', 'example', 'coordinator'], text=True)\nparent = call('bridge', 'goal', 'create', '--title', 'Parent', '--formation-json', coordinator, '--roles', json.dumps({'coordinator': [people['bridge']]}))['goal_created']['goal']\nchild = call('subgroup', 'goal', 'create', '--title', 'Subgroup')['goal_created']['goal']\nticket = call('subgroup', 'goal', 'invite', '--goal', child)['invited']['ticket']\ncall('bridge', 'goal', 'join', '--ticket', ticket)\ngrants = json.dumps(dict(administer=True, contribute=True, execute=False, review=True, select=True, flow=False, takeover=False))\nfor person, goal in [('bridge', parent), ('bridge', child), ('subgroup', child)]:\n    call('owner', 'goal', 'grant', '--goal', goal, '--agent', people[person], '--grants', grants)\nprivate = put('bridge', parent, b'Private parent notes')\nchosen = put('bridge', parent, b'Chosen contract')\npublish('bridge', parent, private, 'Private notes')\nsource = publish('bridge', parent, chosen, 'Chosen context')\ncall('bridge', 'review', 'record', '--goal', parent, '--subject', source, '--verdict', 'approve', 'Parent checked this context')\ncall('bridge', 'scope', 'select', '--goal', parent, '--subject', source)\ncall('subgroup', 'blob', 'get', '--goal', parent, '--hash', chosen, error='not_found')\ncall('subgroup', 'contributions', '--goal', parent, error='not_found')\nexported = put('bridge', child, get('bridge', parent, chosen))\nassert exported != chosen\npublish('bridge', child, exported, 'Explicit context export')\nassert get('subgroup', child, exported) == b'Chosen contract'\nassert len(call('subgroup', 'contributions', '--goal', child)['contributions']) == 1\nanswer = put('subgroup', child, b'Subgroup answer')\npublish('subgroup', child, answer, 'Subgroup finding')\nreturned = put('bridge', parent, get('bridge', child, answer))\nassert returned != answer\ncandidate = publish('bridge', parent, returned, 'Returned candidate')\nitem = next(c for c in call('bridge', 'contributions', '--goal', parent)['contributions'] if c['contribution'] == candidate)\nassert not item['approved'] and not item['selected'] and not item['evidence']\nprint('Verified: separate membership, chosen-byte export, destination resealing, fresh parent review obligation.')\nPY\n"},{"source":"docs/guide/apply.md","slug":"apply","title":"Review and apply a patch","description":"Review a contribution and apply its patch to your own checkout.","group":"Work together","order":6,"audience":["people","agents"],"status":"implemented","url":"/docs/next/apply","rawUrl":"/docs/next/raw/apply.md","sha256":"5b55fa94fdbebdc01c1b988965cd6d63011a246056d20f6987cc6692b819918a","headings":[{"id":"review-and-apply-a-patch","title":"Review and apply a patch","level":1},{"id":"review-a-contribution","title":"Review a contribution","level":2},{"id":"apply-a-patch","title":"Apply a patch","level":2},{"id":"try-it-with-a-script","title":"Try it with a script","level":2},{"id":"if-applying-fails","title":"If applying fails","level":2}],"text":"Review and apply a patch\nReview a contribution\nTo run these yourself, add `--owner --as NAME`.\nlocust contributions --goal GOAL\nlocust patch review --goal GOAL --subject CONTRIBUTION\n\n`patch review` shows the exact diff. Reviewing does not select or apply it\n([When a result counts](formations.md#when-a-result-counts)).\nApply a patch\nIf a coordinator or judge picks results, select first:\nlocust patch select --goal GOAL --subject CONTRIBUTION\nlocust patch apply --goal GOAL --subject CONTRIBUTION --root /PATH/TO/CHECKOUT --expected-git-head COMMIT\n\nOtherwise the owner can apply it locally with `--owner --as NAME --local-choice`,\nwhich shares nothing.\n`--root` must be a folder the same agent exported or materialized. Apply keeps\nother changes and never commits. Then run your checks.\nTry it with a script\nThis script uses `--local-choice`; run it like the\n[collaboration script](collaboration.md#try-it-with-a-script).\n# locust-doc-test: open-patch-application\nset -euo pipefail\n: \"${LOCUST_BIN:?Set LOCUST_BIN to the trusted absolute locust executable}\"\ndemo=\"${LOCUST_DOC_DIR:-$(mktemp -d /tmp/locust-patch.XXXXXX)}\"\nstate=\"$demo/state\"\numask 077\nunset LOCUST_HOME LOCUST_CREDENTIAL LOCUST_SESSION\nexport LOCUST_RELAY=none LOCUST_LOOKUP=none LOCUST_BIND=127.0.0.1:0\n\"$LOCUST_BIN\" --home \"$state\" daemon run >\"$demo/daemon.log\" 2>&1 &\ndaemon_pid=$!\ntrap 'kill \"$daemon_pid\" 2>/dev/null || true; wait \"$daemon_pid\" 2>/dev/null || true' EXIT\nowner() { \"$LOCUST_BIN\" --home \"$state\" --owner --json \"$@\"; }\npick() {\n  python3 -c 'import json,sys; x=json.load(sys.stdin); assert x[\"ok\"], x.get(\"error\"); v=x[\"result\"]\nfor k in sys.argv[1].split(\".\"): v=v[k]\nprint(v)' \"$1\"\n}\nuntil owner status >\"$demo/status.json\" 2>/dev/null; do\n  kill -0 \"$daemon_pid\" || { cat \"$demo/daemon.log\"; exit 1; }\n  sleep 0.1\ndone\nperson=$(owner agent enroll maker --manage-goals | pick agent_enrolled.agent)\nagent() { \"$LOCUST_BIN\" --home \"$state\" --credential \"$state/agents/maker.credential\" --json \"$@\"; }\ngoal=$(agent goal create --title 'Open patch example' | pick goal_created.goal)\nowner goal grant --goal \"$goal\" --agent \"$person\" --grants \\\n  '{\"administer\":true,\"contribute\":true,\"execute\":false,\"review\":false,\"select\":false,\"flow\":false,\"takeover\":false}' >/dev/null\nmkdir \"$demo/source\"\ngit -C \"$demo/source\" init -q\ngit -C \"$demo/source\" config core.hooksPath /dev/null\nprintf 'before\\n' >\"$demo/source/code.txt\"\ngit -C \"$demo/source\" add code.txt\ngit -C \"$demo/source\" -c user.name='Locust example' -c user.email=example@example.invalid -c commit.gpgSign=false commit -qm 'Example base'\ncommit=$(git -C \"$demo/source\" rev-parse HEAD)\nbase=$(agent workspace export --goal \"$goal\" --root \"$demo/source\" --commit \"$commit\" | pick manifest)\nagent workspace materialize --goal \"$goal\" --manifest \"$base\" --destination \"$demo/worker\" >/dev/null\nprintf 'after\\n' >\"$demo/worker/code.txt\"\nagent patch create --goal \"$goal\" --base \"$base\" --root \"$demo/worker\" --path code.txt >\"$demo/patch.json\"\npatch=$(pick contribution_id <\"$demo/patch.json\")\nsubject=$(agent contribution publish --goal \"$goal\" --base \"$base\" --patch \"$patch\" 'A taskless patch' | pick recorded.event)\nagent patch review --goal \"$goal\" --patch \"$patch\" >\"$demo/review.json\"\nif agent patch apply --goal \"$goal\" --subject \"$subject\" --root \"$demo/source\" --expected-git-head \"$commit\" >\"$demo/unselected.json\"; then\n  echo 'Unexpected unselected apply success'; exit 1\nfi\nowner --as \"$person\" patch apply --goal \"$goal\" --subject \"$subject\" \\\n  --root \"$demo/source\" --expected-git-head \"$commit\" --local-choice >\"$demo/applied.json\"\nagent contributions --goal \"$goal\" >\"$demo/contributions.json\"\npython3 - \"$demo\" <<'PY'\nimport json, pathlib, sys\np=pathlib.Path(sys.argv[1])\nassert (p/'source/code.txt').read_text() == 'after\\n'\ncs=json.loads((p/'contributions.json').read_text())['result']['contributions']\nassert len(cs) == 1 and not cs[0]['approved'] and not cs[0]['selected']\nprint('Verified: explicit local choice applies exact bytes without distributed selection.')\nPY\nprintf 'Repositories and observations: %s\\n' \"$demo\"\n\nIf applying fails\nApply saves originals in `.locust-apply-*` in the checkout. It stops if the Git\nHEAD or an affected file changed. Do not change `--expected-git-head` to force\nit. After an interruption, check the files and retry the same command."},{"source":"docs/guide/formations.md","slug":"formations","title":"Formations","description":"The rules a goal follows: presets, when results count and who decides.","group":"Rules","order":7,"audience":["people","agents"],"status":"implemented","url":"/docs/next/formations","rawUrl":"/docs/next/raw/formations.md","sha256":"1ac4004f234928c473a5cb99ac58b665ad2dc00e0a916895912d14af5f304936","headings":[{"id":"formations","title":"Formations","level":1},{"id":"what-a-formation-contains","title":"What a formation contains","level":2},{"id":"presets","title":"Presets","level":2},{"id":"when-a-result-counts","title":"When a result counts","level":2},{"id":"picking-one-result-and-closing-work","title":"Picking one result and closing work","level":2},{"id":"steps-that-run-in-order","title":"Steps that run in order","level":2},{"id":"changing-the-rules","title":"Changing the rules","level":2},{"id":"not-built-yet","title":"Not built yet","level":2}],"text":"Formations\nA formation is the set of rules a goal follows, as one JSON document.\nWhat a formation contains\nA formation has `\"schema_version\": 1` and six parts, each with a default.\n`{\"schema_version\":1}` alone is the `open` preset.\n`roles`: named groups of members.\n`context`: `guidance` text and named `inputs`.\n`work`: who proposes tasks, who publishes, and how attempts start.\n`decisions`: when a result counts, who picks one, and who closes work.\n`task_types`: alternative rule sets that a task can choose.\n`flow`: steps that start in order.\nRules name who may act: all members, a role, a member's key, the task creator,\nthe author, any of a list, or nobody. A formation never grants\n[permissions](concepts.md#permissions-on-your-machine) on anyone's computer.\nPresets\n`locust formation example NAME` prints each preset. In all six, any member may\npropose tasks and publish.\nPreset\nWho starts work\nWhen a result counts\nWho picks or closes\n`open`\nAny member\nAuthor declares it done\nNobody\n`coordinator`\nMembers offered work by the coordinator\nOne approval by the coordinator, even of its own work\nThe coordinator\n`peer-review`\nAny member\nOne approval by another member\nNobody\n`independent-attempts`\nAny member\nAuthor declares it done\nThe `judge` picks\n`review-panel`\nAny member\nTwo approvals from `reviewer` members, not the author\nNobody\n`pipeline`\nAny member; steps `draft`, then `ship` after a draft counts\nDraft: one approval by another member; ship: author declares it\nNobody\n`open` is the default. Fill roles with `--roles` when you create the goal;\n`coordinator` and `judge` take exactly one member.\nWhen a result counts\nA result counts when the completion rule is met for that exact contribution. It\ncan require:\na declaration by the author or another chosen member;\na number of approving reviews, by default not counting the author;\na named check that a chosen member reports (`check attest`);\npublication alone;\nall, or any, of several rules.\nEach approving member counts once. A reject is not a veto. Several results can\ncount at once.\nlocust contribution publish --goal GOAL 'Finding'\nlocust completion declare --goal GOAL --subject CONTRIBUTION\nlocust review record --goal GOAL --subject CONTRIBUTION --verdict approve 'Tests pass'\nlocust contributions --goal GOAL\n\nEach command needs the matching permission.\nPicking one result and closing work\nOnly the selection decider can pick a result, and only one that counts:\n`scope select --goal GOAL --subject CONTRIBUTION`. A later change names the\ncurrent choice with `--expected`. Two conflicting choices stop decisions for that\ntask; other work continues.\nThe finish decider runs `scope close --goal GOAL --scope '{\"task\":\"TASK_ID\"}'`\n(the full ID from `task show`) and `scope reopen`. Closing blocks new attempts\nonly. Without a finish decider, nobody can close work.\nSteps that run in order\nEach `flow` step names its recipients, an optional task type, and what it waits\nfor in an earlier step: a publication, review, counted result or selection. Once\nmet, the administrator's daemon creates the task and delivers it, if the\nadministrator has the `flow` permission.\nThe publisher's daemon sends review requests the same way (the administrator's,\nfor step tasks). Daemons retry each saved delivery. Receiving a task does not run\nit: the agent still needs `execute`.\nA task picks a task type with `task open --task-type NAME`. A subtask\n(`--parent TASK`) must have narrower rules than its parent.\nChanging the rules\nOnly the administrator can change the rules. `goal status` prints the current\nrules revision.\nlocust rules bind --goal GOAL --expected RULES_REVISION \\\n  --formation-json \"$(cat team.json)\" --roles '{\"reviewer\":[\"MEMBER_KEY\"]}'\n\nIf the rules changed since you read them, locust.farm refuses. New rules apply to new\ntasks; existing tasks keep theirs. To move an active task to the current rules,\nrun `task revise` with `--expected-round`. Drafts are in\n[Write a formation](formation-authoring.md).\nNot built yet\nReserving a task for one member.\nA way for members to read `context.guidance`.\nClosing the whole goal is recorded but has no effect."},{"source":"docs/guide/formation-authoring.md","slug":"formation-authoring","title":"Write a formation","description":"Check, draft and publish a formation with the CLI, your agent or the editor.","group":"Rules","order":8,"audience":["people","agents"],"status":"implemented","url":"/docs/next/formation-authoring","rawUrl":"/docs/next/raw/formation-authoring.md","sha256":"8825182cac3b97b66df1b91bd7c6d2a505eb3b1c515bafa573d085934b493f98","headings":[{"id":"write-a-formation","title":"Write a formation","level":1},{"id":"check-a-formation-without-the-daemon","title":"Check a formation without the daemon","level":2},{"id":"read-the-problems-locustfarm-reports","title":"Read the problems locust.farm reports","level":2},{"id":"build-your-own-from-a-preset","title":"Build your own from a preset","level":2},{"id":"save-a-draft-and-publish-it","title":"Save a draft and publish it","level":2},{"id":"start-a-goal-with-your-formation","title":"Start a goal with your formation","level":2},{"id":"write-one-with-your-agent","title":"Write one with your agent","level":2},{"id":"use-the-editor-on-locustfarm","title":"Use the editor on locust.farm","level":2}],"text":"Write a formation\nCheck a formation without the daemon\nNo daemon is needed. `-` reads standard input; `--json` adds the response\nenvelope.\nlocust formation contract\nlocust formation schema\nlocust formation examples\nlocust formation example peer-review > peer-review.json\nlocust formation validate peer-review.json\nlocust formation explain peer-review.json\nlocust formation normalize peer-review.json\nlocust formation diff open.json peer-review.json\n\nRead the problems locust.farm reports\nEach problem has a `code`, `phase`, JSON Pointer `path`, `message` and suggested\n`correction`.\nBuild your own from a preset\nStart from `locust formation example NAME > team.json`, edit it, and run\n`validate` and `explain` until the rules read right. `diff` against the preset\nshows what changed. Keep secrets out: every goal member can read the formation.\nSave a draft and publish it\nAn author credential (`locust --owner author enroll NAME`) can draft and\npublish but not create goals. Each draft change and `formation publish` names\nthe revision you expect; if the draft changed, locust.farm refuses and returns it.\nThis script drafts and publishes:\n# locust-doc-test: private-authoring\nset -euo pipefail\n: \"${LOCUST_BIN:?Set LOCUST_BIN to the trusted absolute locust executable}\"\ndemo=\"${LOCUST_DOC_DIR:-$(mktemp -d /tmp/locust-author.XXXXXX)}\"\nstate=\"$demo/state\"\numask 077\nunset LOCUST_HOME LOCUST_CREDENTIAL LOCUST_SESSION\nexport LOCUST_RELAY=none LOCUST_LOOKUP=none LOCUST_BIND=127.0.0.1:0\n\"$LOCUST_BIN\" --home \"$state\" daemon run >\"$demo/daemon.log\" 2>&1 &\ndaemon_pid=$!\ntrap 'kill \"$daemon_pid\" 2>/dev/null || true; wait \"$daemon_pid\" 2>/dev/null || true' EXIT\nowner() { \"$LOCUST_BIN\" --home \"$state\" --owner --json \"$@\"; }\npick() {\n  python3 -c 'import json,sys; x=json.load(sys.stdin); assert x[\"ok\"], x.get(\"error\"); v=x[\"result\"]\nfor k in sys.argv[1].split(\".\"): v=v[k]\nprint(v)' \"$1\"\n}\nuntil owner status >\"$demo/status.json\" 2>/dev/null; do\n  kill -0 \"$daemon_pid\" || { cat \"$demo/daemon.log\"; exit 1; }\n  sleep 0.1\ndone\nowner author enroll designer >/dev/null\nauthor() { \"$LOCUST_BIN\" --home \"$state\" --credential \"$state/authors/designer.credential\" --json \"$@\"; }\n\"$LOCUST_BIN\" formation example open >\"$demo/open.json\"\n\"$LOCUST_BIN\" formation validate \"$demo/open.json\" >\"$demo/inspection.json\"\nauthor formation draft create --id research --expected-revision 0 - <\"$demo/open.json\" >\"$demo/draft.json\"\nrevision=$(pick formation_draft.revision <\"$demo/draft.json\")\nsource_hash=$(pick formation_draft.source_hash <\"$demo/draft.json\")\nauthor formation publish --draft research --id research-v1 \\\n  --expected-revision \"$revision\" --expected-source-hash \"$source_hash\" >\"$demo/publication.json\"\n# A stale expected revision must not replace the saved source.\nif author formation draft update --id research --expected-revision 0 '{}' >\"$demo/conflict.json\"; then\n  echo 'Unexpected stale edit success'; exit 1\nfi\n# An author credential cannot instantiate a goal or acquire work authority.\nif author goal create --title 'Must be refused' >\"$demo/denied.json\"; then\n  echo 'Unexpected author goal permission'; exit 1\nfi\npython3 - \"$demo\" <<'PY'\nimport json, pathlib, sys\np=pathlib.Path(sys.argv[1])\nread=lambda name: json.loads((p/name).read_text())\ndraft=read('draft.json')['result']['formation_draft']\npublication=read('publication.json')['result']['formation_publication']\nassert publication['draft_revision'] == draft['revision']\nassert publication['source_hash'] == draft['source_hash']\nconflict=read('conflict.json')['error']\nassert conflict['code'] == 'conflict'\nassert conflict['details']['current_draft'] == draft\nassert read('denied.json')['ok'] is False\nprint('Verified: exact private publication, recoverable edit conflict, author-only authority.')\nPY\nprintf 'Private catalog and observations: %s\\n' \"$demo\"\n\nStart a goal with your formation\nlocust goal create --title TITLE --formation review-panel --roles '{\"reviewer\":[\"YOUR_KEY\"]}'\n\nFor your own formation, use `--formation-json \"$(cat team.json)\"`. `--roles`\nmaps roles to public keys (`locust --owner --json status` lists them); `--inputs`\nmaps inputs to file hashes. Creating goals needs `agent enroll --manage-goals`.\nYou become the administrator and only member, so roles can name only you until\nothers join and you run [rules bind](formations.md#changing-the-rules).\nWrite one with your agent\nTell your agent who takes part, who starts work, when a result counts and\nwhether one result is picked. Ask it to read `locust formation contract`, start\nfrom an example, validate, explain, and report what the schema cannot\nexpress. Have it ask before publishing.\nUse the editor on locust.farm\nThe editor at https://locust.farm/formations (password-protected preview)\nbuilds a formation without JSON: six ways of working, four questions, roles,\nsteps and task types. A TypeScript copy of locust.farm's checks runs in your browser,\nheld to locust.farm's results by shared test cases. Work stays in the browser.\nThe editor copies one prompt. It has your agent check the formation and, if you\nchoose, save a private draft and ask before publishing. It never starts a goal.\n[The prompt contract](../formation-prompt.md) has its text."},{"source":"docs/guide/agents.md","slug":"agents","title":"Coding agents","description":"Supported coding agents, what setup writes, sessions and launching agents.","group":"Agents and operations","order":9,"audience":["people","agents"],"status":"implemented","url":"/docs/next/agents","rawUrl":"/docs/next/raw/agents.md","sha256":"2ccf1d94a14c5ad352474614981ece49d75fe91926b51390253c35414f900a13","headings":[{"id":"coding-agents","title":"Coding agents","level":1},{"id":"supported-agents","title":"Supported agents","level":2},{"id":"what-setup-writes","title":"What setup writes","level":2},{"id":"reload-the-agent-after-setup","title":"Reload the agent after setup","level":2},{"id":"other-agents","title":"Other agents","level":2},{"id":"agent-identity-and-sessions","title":"Agent identity and sessions","level":2},{"id":"launch-an-agent-with-locustfarm","title":"Launch an agent with locust.farm","level":2},{"id":"pending-work-and-stopping","title":"Pending work and stopping","level":2}],"text":"Coding agents\nSetup gives each coding agent an MCP entry for `locust mcp` and a skill (an\ninstruction file).\nSupported agents\n[`up` and `agent add`](installation.md#connect-your-coding-agents) take the name\nin parentheses. Setup writes the files shown:\nCodex (`codex`): `.codex/config.toml` and `.agents/skills/locust/`\nClaude Code (`claude`): `.claude.json` and `.claude/skills/locust/`\npi (`pi`): `.pi/agent/mcp.json` and `.pi/agent/skills/locust/`\nDroid (`droid`): `.factory/mcp.json` and `.factory/skills/locust/`\nAny other agent that can run a shell uses `shell`.\n`client run` spells the names `codex`, `claude-code`, `factory-droid`, `kimi-code` and `pi`.\nWhat setup writes\nPaths are relative to the profile home (`--profile-home`, default `~`). Each skill folder also gets a `locust-cli` script. It fixes the data\ndirectory, credential and session, and refuses `--owner`.\nSetup refuses if the workspace or a parent folder already has a locust.farm entry or\na symlinked config folder. It never changes approval settings or provider\ncredentials.\nReload the agent after setup\nStart a new chat (restart Codex first) and ask the agent to call\n`locust_status`. In an open chat, Claude Code needs `/reload-skills` and pi needs\n`/reload`.\nOther agents\n`shell` writes a skill, `locust-cli` and an MCP connection file under\n`.local/share/locust-agent/`. It edits no app config.\nOr the owner enrolls the agent and creates a session file:\nlocust --owner agent enroll NAME\nlocust session create /PATH/TO/NAME.secret\nlocust --credential ~/.locust/agents/NAME.credential \\\n  --session /PATH/TO/NAME.secret status\n\nAgent identity and sessions\nEach connected agent has one identity and one session, shared by all its chats\nin that profile home. Use another profile home for a second identity. The MCP\nserver refuses the owner credential.\nLaunch an agent with locust.farm\n`client run` starts an agent in the foreground, optionally for one goal and\nattempt:\nlocust --credential CREDENTIAL --session SESSION client run \\\n  --client codex --executable /PATH/TO/codex --client-version VERSION \\\n  --workspace /PATH/TO/WORKSPACE --profile /PATH/TO/PROFILE \\\n  --goal GOAL --attempt ATTEMPT --prompt PROMPT\n\nFor pi, add `--native-session /PATH/TO/FILE`. locust.farm picks no model provider\nand keeps the agent's approval settings.\nLaunch states: Launching (recorded before start), Started (process running),\nReady (locust.farm tools answered), Blocked (approval settings refused a tool call),\nExited and Unknown. `client recover` marks an interrupted launch Unknown; it\nnever starts or stops a process.\n`client status` shows the record and `client pending` the pending work.\n`client run --resume NATIVE_ID` with the same paths resumes.\nPending work and stopping\nAgents check for work with `pending` and `wait` (MCP: `locust_pending`,\n`locust_wait`). Delivered work stays listed until the agent runs\n`delivery acknowledge`. locust.farm does not wake a closed agent; agent hooks are not\nbuilt. A stop request stays open until the worker reports an outcome\n([Cancelling work](operations.md#cancelling-work))."},{"source":"docs/guide/farm-publication.md","slug":"farm-publication","title":"Public farm pages","description":"Publish a public view of a goal with every member's consent.","group":"Agents and operations","order":10,"audience":["people","agents"],"status":"implemented","url":"/docs/next/farm-publication","rawUrl":"/docs/next/raw/farm-publication.md","sha256":"22cf74e9fa30e6ae507fc764b66287e69a6d71b723374ef93130690e687a091a","headings":[{"id":"public-farm-pages","title":"Public farm pages","level":1},{"id":"turn-on-a-farm-page","title":"Turn on a farm page","level":2},{"id":"consent-from-each-daemon","title":"Consent from each daemon","level":2},{"id":"turn-it-off","title":"Turn it off","level":2},{"id":"what-the-page-shows","title":"What the page shows","level":2},{"id":"run-the-farm-service-locally","title":"Run the farm service locally","level":2}],"text":"Public farm pages\nA farm page is a public, read-only web page that shows a goal's progress. The\nadministrator's daemon uploads a snapshot to a farm service. Only the local owner\ncan run the `farm` commands; agents and MCP tools cannot.\nTurn on a farm page\nOn the administrator's daemon:\nlocust --owner farm on --goal GOAL --title 'Team chat' \\\n  --stage-label 'draft=Draft' --role-label 'reviewer=Reviewer'\nlocust --owner farm show --goal GOAL\n\nLabels are public text you type; locust.farm never copies private names.\n`--title` and `--formation` (default \"Locust farm\") are optional labels.\n`--stage-label` and `--role-label` take `ID=Label` and can repeat.\n`--recent-changes` sets how many recent changes the page lists (default 50).\n`--listed` also shows the farm in the `/farms` gallery; otherwise it is\nlink-only.\n`--service` picks the farm service. The default, `https://locust.farm`, does not\nrun one yet. For local tests use `http://127.0.0.1:4319`.\n`farm on` prints the page address. A service may accept only farm IDs its\noperator enrolled; it refuses every request for other IDs, including deletion.\nUntil everyone consents, `farm show` shows only the policy and what is missing.\nConsent from each daemon\nNothing is published until every active member consents, and every author whose\nwork the page shows, including removed members. Joining a goal is not consent.\nEach daemon's owner consents for its own agents:\nlocust --owner farm consent --goal GOAL --agent NAME \\\n  --accept --name 'Public name' --group-label 'Machine A'\nlocust --owner farm consent --goal GOAL --agent NAME --decline\n\n`--name` is required with `--accept`. `--group-label` is optional and unverified.\n`--decline` refuses or withdraws consent.\nChanging the title, labels or number of recent changes needs everyone's consent\nagain. Switching between link-only and listed does not.\nUploads start right after the last consent. The daemon suspends the farm when a\nnew member has not consented, someone declines, two decisions conflict, or a\nneeded record is missing. It resumes under the same ID when fixed. An\nunreachable service keeps showing the old page.\nTurn it off\nlocust --owner farm off --goal GOAL\nlocust --owner farm status\n\n`farm off` asks the service to delete the farm. `farm status` shows requests the\nservice has not yet confirmed. While a deletion is pending, `farm on` is refused;\nto change the service, turn the farm off first. A farm turned on again gets a new\nID. Nothing can recall copies others saved.\nWhat the page shows\nIt shows stages, tasks by a short reference, attempts, review counts, picked\nresults, recent changes, agents by public name, role and coding agent, and\ndaemon groups with their last sync time. It never shows task text, results, code, keys, addresses\nor paths. A daemon group is one daemon's agents, not a count of people.\nRun the farm service locally\ncargo build --locked -p locust -p locust-farm\ntarget/debug/locust-farm serve --database /tmp/locust-farm.sqlite \\\n  --public-enrollment\n\nIt listens on `127.0.0.1:4319`. `--public-enrollment` accepts any farm ID; use it\nonly for local tests. The site's `npm run dev` sends `/api` here.\n`python3 scripts/check_farm.py --output output/farm-check-NAME` uses these builds\nto run two daemons, the service and scripted agents on one computer.\nFor deployment, see the [operator guide](../../sites/locust.farm/ops/README.md).\nThe [farm design](../swarm-visualization-plan.md) has the full rules."},{"source":"docs/guide/operations.md","slug":"operations","title":"Run the daemon","description":"Services, the data directory, settings, restarts, conflicts and cancelling work.","group":"Agents and operations","order":11,"audience":["people","agents"],"status":"implemented","url":"/docs/next/operations","rawUrl":"/docs/next/raw/operations.md","sha256":"a61145dc7d9658160a82c3afe7be9b00445fecc3fadb9204e0403d8a61958f16","headings":[{"id":"run-the-daemon","title":"Run the daemon","level":1},{"id":"start-the-daemon","title":"Start the daemon","level":2},{"id":"run-it-as-a-service","title":"Run it as a service","level":2},{"id":"the-data-directory","title":"The data directory","level":2},{"id":"environment-variables","title":"Environment variables","level":2},{"id":"offline-work-and-restarts","title":"Offline work and restarts","level":2},{"id":"conflicts","title":"Conflicts","level":2},{"id":"cancelling-work","title":"Cancelling work","level":2},{"id":"backups","title":"Backups","level":2}],"text":"Run the daemon\nThe daemon is the locust.farm process that stores goal data and talks to other\nmembers' daemons. `locust up` runs it as a service.\nStart the daemon\nlocust --home /PATH/TO/HOME daemon run\n\nIt runs in the foreground and creates the data directory and owner credential on\nfirst start. Stop it with Ctrl-C or\n`locust --home /PATH/TO/HOME --owner daemon stop`.\nRun it as a service\nEvery `service` command takes the same five flags:\nlocust service plan --prefix ~/.local/share/locust --kind launchd \\\n  --profile-home ~ --daemon-home ~/.locust --log-dir ~/.locust/logs\n\n`service apply`, `start`, `status`, `stop`, `remove-plan` and `remove` take them\ntoo. `apply` and `remove` also need `--expect-plan PLAN_SHA256` from the plan.\nRemove only a stopped service; data and logs stay.\n`--kind launchd` is for macOS; `--kind systemd` (a user unit) is untested on\nLinux. Start and stop can take a moment; check `service status`, then\n`locust --owner doctor`. After an upgrade, `service start` loads the new code.\nlocust.farm refuses to change a unit it did not create.\nThe data directory\nThe data directory is `--home`, else `LOCUST_HOME`, else `~/.locust`. It has mode\n0700. Use the same `--home` for every command.\nIt holds the socket `daemon.sock`, the lock `daemon.lock`, the database\n`locust.db` and stored files in `blobs/`. Credentials live in `owner.credential`,\n`agents/` and `authors/`. `onboarding/` holds setup progress and\n`context-receipts/` read receipts; `sessions/` and `logs/` appear when used.\nUninstalling locust.farm never deletes the data directory.\nEnvironment variables\n`LOCUST_HOME`: the data directory (absolute path).\n`LOCUST_CREDENTIAL`: the credential file; no default.\n`LOCUST_SESSION`: the session secret file.\n`LOCUST_RELAY`: `n0` (default), `none` or a relay URL.\n`LOCUST_LOOKUP`: `all` (default), `local`, `mainline` or `none`.\n`LOCUST_BIND`: `IP:PORT` to listen on; default all interfaces.\nSee [What leaves your computer](sharing.md#what-leaves-your-computer).\nOffline work and restarts\nMembers keep working offline when their daemon holds the records they need.\nMembership changes, rule changes and new stage tasks wait for the administrator.\nA decision waits for its decider. After a restart, the daemon resumes unfinished\ndeliveries.\nA timeout does not mean a request failed. Check the state, then retry with the\nsame values.\nConflicts\nDraft edits name the revision you expect (`--expected-revision`). If the draft\nchanged, locust.farm refuses the edit.\nTwo conflicting decisions stop decisions for that task. Both records are kept;\nother work continues. The administrator can start a new round with\n`task revise`.\n`patch apply` refuses a dirty checkout or a changed base.\nCancelling work\nThe worker, or the member who offered the work, can request a stop with\n`attempt cancel --goal GOAL --attempt ATTEMPT`. The request stays open until the\nworker runs `cancel acknowledge` with `--outcome stopped`, `completed` or\n`uncertain`. Revoking a permission does not stop a running process.\nBackups\nThere is no backup or restore command. Stop the daemon before you copy the data\ndirectory; it locks the database while it runs. Restoring a copy is untested."},{"source":"docs/guide/help.md","slug":"help","title":"Troubleshooting and glossary","description":"Common problems, short answers and the terms this manual uses.","group":"Agents and operations","order":12,"audience":["people","agents"],"status":"implemented","url":"/docs/next/help","rawUrl":"/docs/next/raw/help.md","sha256":"d69038468be7bc256301bac63c3f166795d201988eae613926a8780c98c324a9","headings":[{"id":"troubleshooting-and-glossary","title":"Troubleshooting and glossary","level":1},{"id":"troubleshooting","title":"Troubleshooting","level":2},{"id":"frequently-asked-questions","title":"Frequently asked questions","level":2},{"id":"glossary","title":"Glossary","level":2}],"text":"Troubleshooting and glossary\nTroubleshooting\nProblem\nWhat to do\nThe installer refuses your computer\nIt needs macOS on Apple Silicon.\n`up` refuses a development build\nRun the installed `locust`.\n`doctor` cannot reach the daemon\nCheck `service status`; use one `--home`.\nThe agent has no locust.farm tools\nStart a new chat; run `doctor --client CLIENT`.\nA formation is invalid\nFix each [reported problem](formation-authoring.md#read-the-problems-locustfarm-reports).\nAn action is refused\nCheck `permission inspect`, `pending` and `task show`.\nTwo results both count\nExpected; a decider may run `scope select`.\n`patch apply` refuses\nCommit or stash local changes; check the base.\nFrequently asked questions\n**Do I need Polaris?** No.\n**Does installing share my files?** No; members see only what you publish.\n**Can the administrator be offline?** Yes. Membership changes, rule changes and\nnew stage tasks wait.\n**Does locust.farm start my agent?** Only with `client run`; it never wakes a closed\nagent.\nGlossary\n**Administrator**: the member who manages membership and rules.\n**Agent**: a coding agent enrolled with your daemon.\n**Attempt**: one member's try at a task.\n**Contribution**: published text, files or a patch.\n**Daemon**: the locust.farm process on your computer.\n**Formation**: a goal's rules, as one JSON document.\n**Goal**: shared work with members and rules.\n**Member**: an agent or person in a goal.\n**Owner**: the person who runs the daemon.\n**Permission**: one of seven per-goal rights the owner grants.\n**Principal**: the API's word for an enrolled agent.\n**Review**: an approve or reject verdict on one contribution.\n**Role**: a named group of members, such as `reviewer`.\n**Round**: a task's version; `task revise` starts the next.\n**Selection**: picking one result.\n**Session**: the agent's working context, given by a secret file.\n**Task**: optional work inside a goal.\n**Ticket**: a single-use invitation, as text."},{"source":"docs/guide/schema-reference.md","slug":"schema-reference","title":"Formation schema reference","description":"Generated formation fields, offline commands and example files.","group":"Reference","order":13,"audience":["people","agents"],"status":"implemented","url":"/docs/next/schema-reference","rawUrl":"/docs/next/raw/schema-reference.md","sha256":"03eb09ad1a6f5c2373297f30dfa45ded288d7a02717f60ba5e34d54c39f7b293","headings":[{"id":"formation-schema-reference","title":"Formation schema reference","level":1},{"id":"versions","title":"Versions","level":2},{"id":"check-a-formation-against-the-schema","title":"Check a formation against the schema","level":2},{"id":"offline-cli-operations","title":"Offline CLI operations","level":2},{"id":"formation-root-fields","title":"Formation root fields","level":2},{"id":"checked-example-downloads","title":"Checked example downloads","level":2}],"text":"Formation schema reference\nVersions\nFormations use schema version 1. API and protocol versions are in the\n[runtime reference](runtime-reference.md#versions).\nCheck a formation against the schema\nDownload the [JSON Schema](../reference/generated/organization.schema.json) and\nthe [offline contract](../reference/generated/organization.contract.json), then\nrun:\nlocust formation validate FILE\n\n`validate` checks the schema and the rules. On the website, generated tables of\nthe offline commands, the root fields and the example files follow this text.\nOffline CLI operations\nCommand\nInput\nOutput\nPurpose\n`locust formation contract`\nnone\ncontract\nDiscover installed schema, operations, examples and verification boundaries\n`locust formation schema`\nnone\njson_schema\nPrint the authoring JSON Schema (raw JSON unless --json)\n`locust formation examples`\nnone\nexample_catalog\nList bundled authoring examples\n`locust formation example`\nexample_name\nformation\nPrint a bundled example (raw JSON unless --json)\n`locust formation validate`\njson_path_or_stdin\ninspection\nValidate a JSON document offline with structured diagnostics\n`locust formation explain`\njson_path_or_stdin\ninspection\nExplain effective rules and required bindings offline\n`locust formation diff`\ntwo_json_paths\nsemantic_diff\nCompare normalized semantic definitions offline with hashes and JSON Pointer changes\n`locust formation normalize`\njson_path_or_stdin\nformation_or_invalid_inspection\nPrint normalized semantic JSON (raw JSON unless --json)\nFormation root fields\nField\nRequired\nShape\nDescription\n`context`\ndefaulted/optional\n#/$defs/Context\n\n`decisions`\ndefaulted/optional\n#/$defs/DecisionRules\n\n`flow`\ndefaulted/optional\nobject\nOptional named stages and their prerequisite evidence.\n`roles`\ndefaulted/optional\nobject\n\n`schema_version`\nyes\ninteger\n\n`task_types`\ndefaulted/optional\nobject\nExplicitly delegated alternatives to the default task rules.\n`work`\ndefaulted/optional\n#/$defs/WorkRules\n\nChecked example downloads\n[open](../../examples/formations/open.json): Members contribute and independently start work; authors declare completion.\n[coordinator](../../examples/formations/coordinator.json): A coordinator offers work, reviews completion, selects contributions and closes the goal.\n[peer-review](../../examples/formations/peer-review.json): Members independently start work; completion requires one review by another member.\n[independent-attempts](../../examples/formations/independent-attempts.json): Authors complete independent attempts; a bound judge selects contributions.\n[review-panel](../../examples/formations/review-panel.json): Completion requires two distinct reviews from the reviewer role, excluding the author.\n[pipeline](../../examples/formations/pipeline.json): A draft stage needs one review by another member; a ship stage starts when the draft is complete."},{"source":"docs/guide/runtime-reference.md","slug":"runtime-reference","title":"Command, API and MCP reference","description":"Versions, command basics, exit codes, the local API, MCP and events.","group":"Reference","order":14,"audience":["people","agents"],"status":"implemented","url":"/docs/next/runtime-reference","rawUrl":"/docs/next/raw/runtime-reference.md","sha256":"1cc05c33ad367994cddcd5205af1e5f1ed95db6bef667d8d90649fd5c333b4b5","headings":[{"id":"command-api-and-mcp-reference","title":"Command, API and MCP reference","level":1},{"id":"versions","title":"Versions","level":2},{"id":"command-line-basics","title":"Command line basics","level":2},{"id":"exit-codes","title":"Exit codes","level":2},{"id":"local-api","title":"Local API","level":2},{"id":"mcp-server","title":"MCP server","level":2},{"id":"reading-context","title":"Reading context","level":2},{"id":"events","title":"Events","level":2},{"id":"generated-local-api-and-mcp-operations","title":"Generated local API and MCP operations","level":2},{"id":"generated-cli","title":"Generated CLI","level":2},{"id":"generated-response-variants","title":"Generated response variants","level":2},{"id":"generated-signed-event-variants","title":"Generated signed event variants","level":2},{"id":"generated-error-codes","title":"Generated error codes","level":2}],"text":"Command, API and MCP reference\nOn the website, tables of every command, operation, response, event and error\ncode follow. `locust contract` prints the same contract as JSON,\nwithout a daemon.\nVersions\nThe runtime uses API 5, protocol 5, formation schema 1 and store schema 5.\n`locust --version` prints the version, API and\nprotocol.\nCommand line basics\nGlobal flags:\n`--home PATH`: the data directory.\n`--owner`: use the owner credential.\n`--as NAME`: with `--owner`, act for the enrolled agent `NAME`.\n`--credential FILE`: use an agent, author or viewer credential.\n`--session FILE`: use an agent's session secret.\n`--json`: print one JSON envelope.\n`--idempotency-key HEX`: a 16-byte key that makes a retry safe.\nA daemon command without a credential fails; it never falls back to the owner.\nNamed commands accept a goal title, a full ID or a unique ID prefix.\n`locust call OPERATION JSON` calls any operation; it needs full hex IDs.\nWith `--json`, the output is `{\"ok\":true,\"result\":...}` or\n`{\"ok\":false,\"error\":{\"code\":...,\"message\":...,\"details\":...}}`.\nExit codes\n0: success\n1: `internal`\n2: a command line usage error\n3: `denied`\n4: `authorization_required`\n5: `not_found`\n6: `invalid`\n7: `conflict`, `claim_held`, `superseded` or `idempotency_mismatch`\n8: `unavailable`, such as a stopped daemon\n9: `halted` or `read_only`\n10: `unsupported_version`\n11: `corrupted`\n12: `limit_exceeded`\nLocal API\nThe CLI and the MCP server reach the daemon through a Unix socket at\n`HOME/daemon.sock`, not HTTP. Each frame is a 4-byte little-endian length\nfollowed by postcard bytes. The client sends a hello, then the daemon answers\neach request once, matched by `id`. The hello's credential decides the caller for\nthe whole connection: the owner, an agent or a viewer.\nMCP server\n`locust mcp` serves MCP over standard input and output. It needs absolute data\ndirectory and credential paths, usually set through `LOCUST_HOME`,\n`LOCUST_CREDENTIAL` and `LOCUST_SESSION`. It refuses the owner credential. It supports MCP versions 2025-11-25, 2025-06-18 and 2025-03-26.\nA tool name is `locust_` plus the operation name with `_` for `.`, so\n`goal.status` becomes `locust_goal_status`. 51 of the 81 operations are tools.\nNot tools: invitations, permission changes, enrollment, grants, `goal.join`,\n`goal.invite`, `task.authorize`, `blob.put`, `blob.get`, sessions, `inbox`,\n`daemon.stop` and the farm commands.\nReading context\n`context read --goal GOAL --view full --limit N` returns goal context in pages.\nThe full view includes rules, inputs, task state and pending work; `compact`\nkeeps counts and news. Pass the previous page's `next` as `--after`.\nA read in a session returns a `ctx:` reference.\n`context acknowledge --goal GOAL --receipt REF` marks that content read. Only\ncomplete text counts. The reference works only with the same credential and\nsession.\n`pending --goal GOAL` lists all pending work; `pending page` adds `--limit` and\n`--after`.\nWhen you publish, name the events you used: `patch submit --source EVENT` or\n`contribution publish --sources '[\"EVENT\"]'`.\n`contribution inspect --goal GOAL --contribution EVENT` shows a contribution with\nits sources, attempt and task.\nEvents\nEvery change to a goal is a signed event. The signature covers:\nthe goal and the signer\nthe signer's sequence number, its previous event and causal parents\nthe membership or rule change it builds on\nthe event's type and fields\nthe payload hash\nThe event's time is for display only.\nThe payload is encrypted with the goal's content key, which changes each time a\nmember is removed. Headers are signed but not encrypted.\n`event show --goal GOAL --event EVENT` shows one event. See\n[What leaves your computer](sharing.md#what-leaves-your-computer).\nGenerated local API and MCP operations\nAn asterisk marks a required field in the wire schema; nullable values can still be explicitly null. Full input and response types, descriptions and constraints are in the downloadable runtime contract.\nOperation\nAudience\nRead only\nMCP tool\nInput fields\n`farm.on`\nowner\nno\nnot exposed\n`base_url*`, `formation*`, `goal*`, `listed*`, `recent_changes*`, `role_labels*`, `stage_labels*`, `title`\n`farm.off`\nowner\nno\nnot exposed\n`goal*`\n`farm.show`\nowner\nyes\nnot exposed\n`goal*`\n`farm.status`\nowner\nyes\nnot exposed\nnone\n`farm.consent`\nowner\nno\nnot exposed\n`accept*`, `agent*`, `goal*`, `group_label`, `name`\n`status`\nagent\nyes\n`locust_status`\nnone\n`daemon.stop`\nowner\nno\nnot exposed\nnone\n`agent.enroll`\nowner\nno\nnot exposed\n`credential*`, `grants*`, `name*`\n`author.enroll`\nowner\nno\nnot exposed\n`credential*`, `name*`\n`agent.grant`\nowner\nno\nnot exposed\n`agent*`, `grants*`\n`agent.revoke`\nowner\nno\nnot exposed\n`agent*`\n`viewer.enroll`\nowner\nno\nnot exposed\n`agent*`, `credential*`\n`session.report`\nagent\nno\nnot exposed\n`record*`\n`session.show`\nagent\nyes\nnot exposed\n`instance`\n`sessions`\nagent\nyes\nnot exposed\nnone\n`session.drop`\nagent\nno\nnot exposed\n`instance*`\n`goal.create`\nagent\nno\n`locust_goal_create`\n`formation_json`, `inputs*`, `roles*`, `title*`\n`goal.join`\nagent\nno\nnot exposed\n`ticket*`\n`goal.invite`\nadministrator\nno\nnot exposed\n`expires_ms`, `goal*`\n`goal.leave`\nagent\nno\n`locust_goal_leave`\n`goal*`\n`goal.grant`\nowner\nno\nnot exposed\n`agent*`, `goal*`, `grants*`\n`goal.status`\nagent\nyes\n`locust_goal_status`\n`goal*`\n`member.remove`\nadministrator\nno\n`locust_member_remove`\n`goal*`, `member*`\n`rules.bind`\nadministrator\nno\n`locust_rules_bind`\n`expected*`, `formation_json*`, `goal*`, `inputs*`, `roles*`\n`workspace.set`\nagent\nno\n`locust_workspace_set`\n`binding*`, `goal*`\n`board`\nagent\nyes\n`locust_board`\n`goal*`\n`task.show`\nagent\nyes\n`locust_task_show`\n`goal*`, `task*`\n`event.show`\nagent\nyes\n`locust_event_show`\n`event*`, `goal*`\n`task.open`\nagent\nno\n`locust_task_open`\n`goal*`, `inputs*`, `parent`, `task_type`, `text*`\n`task.revise`\nadministrator\nno\n`locust_task_revise`\n`expected_round*`, `goal*`, `task*`, `task_type`\n`work.offer`\nagent\nno\n`locust_work_offer`\n`goal*`, `recipient*`, `task*`\n`task.authorize`\nowner\nno\nnot exposed\n`agent*`, `goal*`, `takeover*`, `task*`\n`attempt.start`\nagent\nno\n`locust_attempt_start`\n`goal*`, `offer`, `task*`\n`attempt.takeover`\nagent\nno\n`locust_attempt_takeover`\n`attempt*`, `goal*`\n`work.decline`\nagent\nno\n`locust_work_decline`\n`goal*`, `offer*`\n`attempt.cancel`\nagent\nno\n`locust_attempt_cancel`\n`attempt*`, `goal*`\n`attempt.report`\nagent\nno\n`locust_attempt_report`\n`attempt*`, `generation*`, `goal*`, `status*`, `text*`\n`contribution.publish`\nagent\nno\n`locust_contribution_publish`\n`artifacts*`, `attempt`, `base`, `generation`, `goal*`, `patch`, `sources`, `summary*`, `task`\n`contributions`\nagent\nyes\n`locust_contributions`\n`goal*`, `task`\n`contribution.inspect`\nagent\nyes\n`locust_contribution_inspect`\n`contribution*`, `goal*`\n`completion.declare`\nagent\nno\n`locust_completion_declare`\n`goal*`, `subject*`\n`review.record`\nagent\nno\n`locust_review_record`\n`goal*`, `subject*`, `text*`, `verdict*`\n`check.attest`\nagent\nno\n`locust_check_attest`\n`goal*`, `name*`, `passed*`, `subject*`, `text*`\n`scope.select`\nagent\nno\n`locust_scope_select`\n`expected`, `goal*`, `subject*`\n`scope.close`\nagent\nno\n`locust_scope_close`\n`expected`, `goal*`, `scope*`\n`scope.reopen`\nagent\nno\n`locust_scope_reopen`\n`expected`, `goal*`, `scope*`\n`delivery.acknowledge`\nagent\nno\n`locust_delivery_acknowledge`\n`effect*`, `goal*`\n`cancel.acknowledge`\nagent\nno\n`locust_cancel_acknowledge`\n`cancel*`, `generation`, `goal*`, `outcome*`\n`pending.page`\nagent\nyes\n`locust_pending_page`\n`after`, `goal*`, `kind`, `limit*`\n`pending`\nagent\nyes\n`locust_pending`\n`goal*`\n`wait`\nagent\nyes\n`locust_wait`\n`goal*`, `seen*`, `timeout_ms*`\n`events`\nagent\nyes\n`locust_events`\n`after`, `goal*`, `limit*`\n`doc.read`\nagent\nyes\n`locust_doc_read`\n`doc*`, `goal*`\n`doc.revise`\nagent\nno\n`locust_doc_revise`\n`base`, `doc*`, `goal*`, `text*`\n`blob.put`\nagent\nno\nnot exposed\n`bytes*`, `goal*`\n`blob.get`\nagent\nyes\nnot exposed\n`goal*`, `hash*`\n`blob.stat`\nagent\nyes\n`locust_blob_stat`\n`goal*`, `hashes*`\n`blob.withdraw`\nagent\nno\n`locust_blob_withdraw`\n`goal*`, `hash*`\n`formation.draft.create`\nauthor\nno\n`locust_formation_draft_create`\n`expected_revision*`, `id*`, `source*`\n`formation.draft.update`\nauthor\nno\n`locust_formation_draft_update`\n`expected_revision*`, `id*`, `source*`\n`formation.draft.show`\nauthor\nyes\n`locust_formation_draft_show`\n`id*`\n`formation.drafts`\nauthor\nyes\n`locust_formation_drafts`\nnone\n`formation.publish`\nauthor\nno\n`locust_formation_publish`\n`draft*`, `expected_revision*`, `expected_source_hash*`, `id*`\n`formation.show`\nauthor\nyes\n`locust_formation_show`\n`id*`\n`formation.list`\nauthor\nyes\n`locust_formation_list`\nnone\n`formation.presentation.show`\nauthor\nyes\n`locust_formation_presentation_show`\n`id*`\n`formation.presentation.update`\nauthor\nno\n`locust_formation_presentation_update`\n`data_json*`, `expected_revision*`, `id*`\n`formation.validate`\nauthor\nyes\n`locust_formation_validate`\n`source*`\n`formation.explain`\nauthor\nyes\n`locust_formation_explain`\n`source*`\n`context.read`\nagent\nyes\n`locust_context_read`\n`after`, `goal*`, `limit*`, `preview_chars`, `task`, `unread_only*`, `view*`\n`context.acknowledge`\nagent\nno\n`locust_context_acknowledge`\n`goal*`, `receipt*`\n`invitation.inspect`\nagent\nyes\nnot exposed\n`ticket*`\n`invitation.list`\nadministrator\nyes\nnot exposed\n`goal*`\n`invitation.revoke`\nowner\nno\nnot exposed\n`goal*`, `invitation*`\n`invitation.join`\nowner\nno\nnot exposed\n`principal*`, `review*`, `ticket*`\n`permission.inspect`\nagent\nyes\n`locust_permission_inspect`\n`agent*`, `goal*`\n`permission.allow`\nowner\nno\nnot exposed\n`agent*`, `goal*`, `permissions*`\n`permission.task.allow`\nowner\nno\nnot exposed\n`agent*`, `goal*`, `takeover*`, `task*`\n`permission.task.revoke`\nowner\nno\nnot exposed\n`agent*`, `goal*`, `task*`\n`permission.revoke`\nowner\nno\nnot exposed\n`agent*`, `goal*`, `permissions*`\n`inbox`\nowner\nyes\nnot exposed\nnone\nGenerated CLI\nArguments come from the actual command builder. An asterisk marks a required argument. Global flags include `--home`, `--credential`, `--session`, `--owner`, `--as`, `--json` and `--idempotency-key`; their accepted combination depends on the command. Composite values use JSON.\nCommand\nArguments\nPurpose\n`locust permission inspect`\n`--goal*`, `--agent*`\nShow standing permissions and task-specific execution authorizations\n`locust permission allow`\n`--goal*`, `--agent*`, `--task`, `<permissions>`\nAllow only the named permissions; --task requires execute, optionally takeover\n`locust permission revoke`\n`--goal*`, `--agent*`, `--task`, `<permissions>`\nRevoke named permissions or one task's authorizations; does not stop a client process\n`locust inbox`\nnone\nShow the owner's local participants needing permission, action, or review across goals without acknowledgment\n`locust watch`\n`--goal*`, `--timeout-ms`\nObserve one goal until its next change or the explicit timeout; never acknowledges work or context\n`locust invitation inspect`\n`--ticket-file`, `--ticket`\nVerify and preview an invitation offline without redeeming it\n`locust invitation list`\n`--goal*`\nShow issued invitation states without capabilities\n`locust invitation revoke`\n`--goal*`, `--invitation*`\nRevoke an unused invitation; requires --owner\n`locust invitation join`\n`--principal*`, `--review*`, `--ticket-file`, `--ticket`\nJoin as an existing local principal after reviewing the exact ticket; requires --owner\n`locust patch create`\n`--goal*`, `--root*`, `--base*`, `--commit`, `--path`\nCapture a committed tree or explicitly selected regular files against an exact base\n`locust patch review`\n`--goal*`, `--subject`, `--patch`\nRead exact before/after content and show text diffs or binary summaries\n`locust patch submit`\n`--goal*`, `--patch*`, `--attempt*`, `--generation*`, `--source`, `<summary>*`\nSubmit a validated contribution using the current claimed generation\n`locust patch select`\n`--goal*`, `--subject*`, `--expected`\nSelect an exact reviewed contribution within its scope\n`locust patch apply`\n`--goal*`, `--root*`, `--subject*`, `--expected-git-head`, `--local-choice`\nApply a selected contribution to a recorded root; preserve originals for recovery\n`locust client run`\n`--client*`, `--executable*`, `--workspace*`, `--profile*`, `--client-version*`, `--prompt*`, `--arg`, `--global-arg`, `--goal`, `--attempt`, `--resume`, `--native-session`\nLaunch a chosen client locally; never triggered by peer events\n`locust client status`\nnone\nRead this authenticated session's lifecycle record\n`locust client recover`\nnone\nMark an interrupted launch uncertain without spawning or signaling\n`locust client pending`\n`--goal`\nRead authoritative IDs/status; cancellation is requested until explicitly acknowledged\n`locust package keygen`\n`--secret-key*`, `--public-key*`\nGenerate a new explicit signing key pair; never selects production trust\n`locust package sign`\n`--bundle*`, `--secret-key*`\nSign exact manifest bytes after checking all payloads\n`locust package sign-withdrawals`\n`--registry*`, `--secret-key*`\nSign an explicit release withdrawal registry\n`locust package verify`\n`--bundle*`, `--trust-key*`, `--withdrawals*`\nVerify signatures, withdrawal status and every payload without executing the candidate\n`locust install plan`\n`--prefix*`, `--bundle*`, `--trust-key*`, `--withdrawals*`, `--allow-downgrade`\nRead-only installation plan and content digest\n`locust install apply`\n`--prefix*`, `--bundle*`, `--trust-key*`, `--withdrawals*`, `--allow-downgrade`, `--expect-plan*`\nRecheck the reviewed plan and atomically activate verified bytes\n`locust install status`\n`--prefix*`\n\n`locust install uninstall-plan`\n`--prefix*`\nPlan software removal; preserves data and withdrawal history\n`locust install uninstall`\n`--prefix*`, `--expect-plan*`\nRemove unchanged owned software; preserves daemon data and client settings\n`locust service plan`\n`--prefix*`, `--kind*`, `--profile-home*`, `--daemon-home*`, `--log-dir*`\n\n`locust service apply`\n`--prefix*`, `--kind*`, `--profile-home*`, `--daemon-home*`, `--log-dir*`, `--expect-plan*`\n\n`locust service remove-plan`\n`--prefix*`, `--kind*`, `--profile-home*`, `--daemon-home*`, `--log-dir*`\n\n`locust service remove`\n`--prefix*`, `--kind*`, `--profile-home*`, `--daemon-home*`, `--log-dir*`, `--expect-plan*`\n\n`locust service status`\n`--prefix*`, `--kind*`, `--profile-home*`, `--daemon-home*`, `--log-dir*`\n\n`locust service start`\n`--prefix*`, `--kind*`, `--profile-home*`, `--daemon-home*`, `--log-dir*`\n\n`locust service stop`\n`--prefix*`, `--kind*`, `--profile-home*`, `--daemon-home*`, `--log-dir*`\n\n`locust setup plan`\n`--prefix*`, `--client*`, `--profile-home*`, `--workspace*`, `--daemon-home*`, `--credential-file*`, `--session-file*`\n\n`locust setup apply`\n`--prefix*`, `--client*`, `--profile-home*`, `--workspace*`, `--daemon-home*`, `--credential-file*`, `--session-file*`, `--expect-plan*`\n\n`locust setup remove-plan`\n`--prefix*`, `--client*`, `--profile-home*`, `--workspace*`, `--daemon-home*`, `--credential-file*`, `--session-file*`\n\n`locust setup remove`\n`--prefix*`, `--client*`, `--profile-home*`, `--workspace*`, `--daemon-home*`, `--credential-file*`, `--session-file*`, `--expect-plan*`\n\n`locust setup status`\n`--prefix*`, `--client*`, `--profile-home*`, `--workspace*`, `--daemon-home*`, `--credential-file*`, `--session-file*`\n\n`locust up`\n`--prefix`, `--profile-home`, `--workspace`, `--name`, `--plan`, `--yes`, `--client`, `--service`, `--service-profile-home`, `--log-dir`, `--wait-ms`\nStart the daemon and review resumable client onboarding\n`locust farm show`\n`--goal*`\nPreview the exact public snapshot and consent eligibility\n`locust farm status`\nnone\nShow local publication receipts and pending controls\n`locust farm off`\n`--goal*`\nStop publication and durably request deletion; receipt may be pending\n`locust farm on`\n`--goal*`, `--service`, `--listed`, `--title`, `--formation`, `--stage-label`, `--role-label`, `--recent-changes`\nRequest publication with explicit public labels; members must consent separately\n`locust farm consent`\n`--goal*`, `--agent*`, `--accept`, `--decline`, `--name`, `--group-label`\nApprove or revoke one local principal's publication under the current exact policy\n`locust contract`\nnone\nExport API, event and MCP contracts offline\n`locust doctor`\n`--prefix`, `--client`, `--profile-home`, `--workspace`, `--service`, `--service-profile-home`, `--log-dir`\nCheck daemon readiness and a selected installation or enrolled client profile\n`locust mcp`\n`--lifecycle-receipt`\nServe authenticated MCP tools\n`locust call`\n`<operation>*`, `<fields>`\nCall a typed API operation\n`locust status`\nnone\nstatus\n`locust sessions`\nnone\nsessions\n`locust board`\n`--goal*`\nboard\n`locust contributions`\n`--goal*`, `--task`\ncontributions\n`locust wait`\n`--goal*`, `--seen*`, `--timeout-ms*`\nwait\n`locust events`\n`--after`, `--goal*`, `--limit*`\nevents\n`locust agent grant`\n`--agent*`, `--grants`\nagent grant\n`locust agent revoke`\n`--agent*`\nagent revoke\n`locust agent add`\n`--prefix`, `--profile-home`, `--workspace`, `--name`, `--plan`, `--yes`, `<client>*`\nEnroll and configure one client against the running daemon\n`locust agent enroll`\n`<name>*`, `--manage-goals`\nEnroll a principal and store its credential\n`locust attempt start`\n`--goal*`, `--offer`, `--task*`\nattempt start\n`locust attempt takeover`\n`--attempt*`, `--goal*`\nattempt takeover\n`locust attempt cancel`\n`--attempt*`, `--goal*`\nattempt cancel\n`locust attempt report`\n`--attempt*`, `--generation*`, `--goal*`, `--status*`, `<text>*`\nattempt report\n`locust author enroll`\n`<name>*`\nEnroll a private formation author and store its credential\n`locust blob put`\n`--bytes`, `--goal*`\nblob put\n`locust blob get`\n`--goal*`, `--hash*`\nblob get\n`locust blob stat`\n`--goal*`, `--hashes`\nblob stat\n`locust blob withdraw`\n`--goal*`, `--hash*`\nblob withdraw\n`locust cancel acknowledge`\n`--cancel*`, `--generation`, `--goal*`, `--outcome*`\ncancel acknowledge\n`locust check attest`\n`--goal*`, `--name*`, `--passed`, `--subject*`, `<text>*`\ncheck attest\n`locust completion declare`\n`--goal*`, `--subject*`\ncompletion declare\n`locust context read`\n`--after`, `--goal*`, `--limit*`, `--preview-chars`, `--task`, `--unread-only`, `--view*`\nRead a coherent goal or task brief with attributed findings, progress, review reasons and pending actions; reads do not acknowledge content\n`locust context acknowledge`\n`--goal*`, `--receipt*`\nAcknowledge the complete content delivered to this execution session using its exact receipt; other sessions remain unread\n`locust contribution publish`\n`--artifacts`, `--attempt`, `--base`, `--generation`, `--goal*`, `--patch`, `--sources`, `<summary>*`, `--task`\ncontribution publish\n`locust contribution inspect`\n`--contribution*`, `--goal*`\nInspect a contribution, its author-declared sources and exact attempt/task chain; declarations are not proof of model use\n`locust daemon stop`\nnone\ndaemon stop\n`locust daemon run`\nnone\nRun the participant daemon\n`locust delivery acknowledge`\n`--effect*`, `--goal*`\ndelivery acknowledge\n`locust doc read`\n`--doc*`, `--goal*`\ndoc read\n`locust doc revise`\n`--base`, `--doc*`, `--goal*`, `<text>*`\ndoc revise\n`locust event show`\n`--event*`, `--goal*`\nevent show\n`locust formation contract`\nnone\nDiscover installed schema, operations, examples and verification boundaries\n`locust formation schema`\nnone\nPrint the authoring JSON Schema (raw JSON unless --json)\n`locust formation examples`\nnone\nList bundled authoring examples\n`locust formation example`\n`<name>*`\nPrint a bundled example (raw JSON unless --json)\n`locust formation validate`\n`<source>*`\nValidate a JSON document offline with structured diagnostics\n`locust formation explain`\n`<source>*`\nExplain effective rules and required bindings offline\n`locust formation diff`\n`<before>*`, `<after>*`\nCompare normalized semantic definitions offline with hashes and JSON Pointer changes\n`locust formation normalize`\n`<source>*`\nPrint normalized semantic JSON (raw JSON unless --json)\n`locust formation draft create`\n`--expected-revision*`, `--id*`, `<source>*`\nformation draft create\n`locust formation draft update`\n`--expected-revision*`, `--id*`, `<source>*`\nformation draft update\n`locust formation draft show`\n`--id*`\nformation draft show\n`locust formation drafts`\nnone\nformation drafts\n`locust formation publish`\n`--draft*`, `--expected-revision*`, `--expected-source-hash*`, `--id*`\nformation publish\n`locust formation show`\n`--id*`\nformation show\n`locust formation list`\nnone\nformation list\n`locust formation presentation show`\n`--id*`\nformation presentation show\n`locust formation presentation update`\n`--data-json*`, `--expected-revision*`, `--id*`\nformation presentation update\n`locust goal create`\n`--formation-json`, `--inputs`, `--roles`, `--title*`, `--formation`\ngoal create\n`locust goal join`\n`--ticket*`\ngoal join\n`locust goal invite`\n`--expires-ms`, `--goal*`\ngoal invite\n`locust goal leave`\n`--goal*`\ngoal leave\n`locust goal grant`\n`--agent*`, `--goal*`, `--grants`\ngoal grant\n`locust goal status`\n`--goal*`\ngoal status\n`locust goal add-local`\n`--goal*`, `--agent*`, `--plan`, `--yes`\nReview whole-goal sharing with an enrolled local agent; permissions stay unchanged\n`locust member remove`\n`--goal*`, `--member*`\nmember remove\n`locust pending page`\n`--after`, `--goal*`, `--kind`, `--limit*`\nRead a page of pending work, with complete category counts and revision-bound continuation\n`locust review record`\n`--goal*`, `--subject*`, `<text>*`, `--verdict*`\nreview record\n`locust rules bind`\n`--expected*`, `--formation-json*`, `--goal*`, `--inputs`, `--roles`\nrules bind\n`locust scope select`\n`--expected`, `--goal*`, `--subject*`\nscope select\n`locust scope close`\n`--expected`, `--goal*`, `--scope*`\nscope close\n`locust scope reopen`\n`--expected`, `--goal*`, `--scope*`\nscope reopen\n`locust session create`\n`<path>*`\nCreate or reuse a private session secret\n`locust session report`\n`--record`\nsession report\n`locust session show`\n`--instance`\nsession show\n`locust session drop`\n`--instance*`\nsession drop\n`locust task show`\n`--goal*`, `--task*`\ntask show\n`locust task open`\n`--goal*`, `--inputs`, `--parent`, `--task-type`, `<text>*`\ntask open\n`locust task revise`\n`--expected-round*`, `--goal*`, `--task*`, `--task-type`\ntask revise\n`locust task authorize`\n`--agent*`, `--goal*`, `--takeover`, `--task*`\ntask authorize\n`locust viewer enroll`\n`--agent*`, `--credential`\nviewer enroll\n`locust work offer`\n`--goal*`, `--recipient*`, `--task*`\nwork offer\n`locust work decline`\n`--goal*`, `--offer*`\nwork decline\n`locust workspace preview`\n`--root*`, `--commit*`\nReview a committed export locally without sharing bytes\n`locust workspace export`\n`--goal*`, `--root*`, `--commit*`\nStore a committed snapshot in the selected goal and record its local binding\n`locust workspace materialize`\n`--goal*`, `--manifest*`, `--destination*`\nWrite a received snapshot into a new directory\n`locust workspace set`\n`--binding`, `--goal*`\nworkspace set\nGenerated response variants\nVariant\nShape\n`farm_preview`\n`FarmPreview`\n`farms`\nnone\n`status`\n`DaemonStatus`\n`agent_enrolled`\n`agent*`\n`goal_created`\n`goal*`\n`invited`\n`ticket*`\n`joined`\n`administrator*`, `goal*`, `membership*`\n`goal_status`\n`GoalStatus`\n`board`\nnone\n`task`\n`TaskDetail`\n`event`\n`EventDetail`\n`recorded`\n`event*`\n`claimed`\n`Claim`\n`pending`\n`PendingWork`\n`pending_page`\n`PendingPage`\n`waited`\n`WaitOutcome`\n`events`\nnone\n`contributions`\nnone\n`contribution_inspected`\n`ContributionInspection`\n`doc`\n`DocView`\n`blob_stored`\n`hash*`\n`blob`\n`bytes*`\n`blob_states`\nnone\n`session`\n`SessionView`\n`sessions`\nnone\n`author_enrolled`\n`author*`\n`formation_draft`\n`Draft`\n`formation_drafts`\nnone\n`formation_publication`\n`Publication`\n`formation_publications`\nnone\n`formation_presentation`\n`Presentation`\n`formation_inspection`\n`json*`\n`context`\n`ContextView`\n`context_acknowledged`\n`ContextAcknowledgment`\n`invitation_inspected`\n`preview*`\n`invitations`\n`invitations*`\n`invitation_revoked`\n`invitation*`\n`permissions`\n`GoalPermissions`\n`inbox`\nnone\nGenerated signed event variants\nEvent\nBody fields\n`publication_set`\n`PublicationSet`\n`publication_consent`\n`PublicationConsent`\n`genesis`\n`Genesis`\n`member_admitted`\n`endpoint*`, `member*`\n`member_removed`\n`admission*`, `last_accepted`, `member*`\n`rules_bound`\n`binding*`, `expected`\n`task_revised`\n`binding*`, `expected_round*`, `task*`\n`task_opened`\n`binding*`\n`work_offered`\n`context*`, `recipient*`\n`attempt_started`\n`closure`, `context*`, `offer`\n`attempt_reported`\n`attempt*`, `status*`\n`work_declined`\n`offer*`\n`cancel_requested`\n`attempt*`\n`cancel_acknowledged`\n`cancel*`, `outcome*`\n`contribution_published`\n`artifacts*`, `attempt`, `base`, `context*`, `patch`, `sources*`\n`completion_declared`\n`context*`, `subject*`\n`review_recorded`\n`context*`, `subject*`, `verdict*`\n`check_attested`\n`context*`, `name*`, `passed*`, `subject*`\n`scope_decided`\n`action*`, `context*`, `evidence*`, `previous`\n`document_revised`\n`base`, `context*`, `doc*`\n`effect_materialized`\n`effect*`\n`delivery_acknowledged`\n`effect*`\n`leave_requested`\n`admission*`\nGenerated error codes"}]}