How crouter works
Four parts of crouter, each shown with what it prints.
1. The harness is a CLI
Agents drive crouter through crtr, the same command you run. They can grep its output, pipe it into jq, and read its help one level at a time.
$ crtr --json canvas list --type node \ | jq -r '.items[] | select(.kind=="developer") | .id' \ | xargs -n1 crtr node inspect show \ | grep '^- status:' | sort | uniq -c 19 - status: canceled 6 - status: done/done 1 - status: done/parked 1 - status: idle/idle-releaseAn agent wrote this to check on 27 developer agents in one command. The answer is text it can keep piping.
crtr -h 261 lines 40 commands, one line eachcrtr node -h 29 lines node's 13 subcommandscrtr node new -h 50 lines the full contract for starting an agentcrtr node new --output-schema -h 15 lines one flag, explainedLine counts on one machine with plugins installed.
Each level of help points to the next. An agent reads the level it needs; the rest stays out of its context.
Any CLI you already have can become a crtr command without rewriting it. This is the whole definition of crtr dev grove, which hands every argument to Grove:
{ kind: "branch", name: "grove", description: "forward raw arguments to Grove's full current instance surface", whenToUse: "you need a Grove operation rather than a repository-defined development command, …", model: "This is a raw passthrough: Grove owns its grammar, parsing, effects, and output. …", passthrough: { bin: "bin/grove", installHint: "Install Grove, then run `grove setup` in the source repository.", }, children: [],}From plugins/dev/lib/commands.mjs in the official marketplace. After install, agents find grove in crtr dev -h beside the built-in commands, with the whenToUse line telling them when to reach for it.
2. Agents form a graph
An agent keeps working until it is done or one of three things is true: it needs a person, it is waiting on its parent, or the work should be split across new agents. Each has a command, and each answer wakes it.
$ crtr canvas dashboard --root <node-id>- nodes: 118● platform-shared-memory app-space-memory-sdk-gap [plan/orchestrator] ctx 0k├─ ✓ advisor-elegance rethink-crouter-cloud-platform-design [advisor/base] ctx 841k├─ ✓ advisor-blindspots crouter-cloud-platform-design-blind-spots [advisor/base] ctx 859k├─ ✓ advisor-sanity review-crouter-cloud-platform-design [advisor/base] ctx 194k├─ ✓ design: cycle 3 one permission model (design-permissions) design-cycle-3-permission-model [design/base] ctx 0k├─ ✓ build: cycle 3 one permission model U1–U6 (c3-build) cycle-3-unified-permission-model [developer/orchestrator] ctx 0k│ ├─ ✓ cycle3 boot-order regression + reparent check boot-order-regression-test-reparent-count [developer/base] ctx 0k│ ├─ ✓ cycle3 fix: documents under deleted nodes unreadable fix-docs-under-deleted-owner-nodes [developer/base] ctx 0k│ ├─ ✓ cycle3 fix: own-app documents under reaped nodes still unreadable fix-reaped-node-document-read-regression [developer/base] ctx 0k│ ├─ ✓ cycle3 preflight fixes A: /v1/check, attach hook, FakeCloud recursion fix-preflight-findings-permissions-pr [developer/base] ctx 0k│ ├─ ✓ cycle3 preflight fixes B: legacy friends inputs, field-only edit docs map-legacy-friends-privacy-private [developer/base] ctx 0k│ ├─ ✓ cycle3 preflight round 4: observer shutdown gate + friends in guides gate-broker-shutdown-fix-privacy-docs [developer/base] ctx 0k│ └─ ✓ directory #249 grant-sync teams: fix 'Runtime has no owner' pg tests fix-directory-pr-249-ci [developer/base] ctx 0k├─ ✓ design cycle 4: one ledger (design-ledger) design-cycle-4-money-ledger [design/base] ctx 0k├─ ✓ design cycle 5: the fleet (design-fleet) design-cycle-five-fleet [design/orchestrator] ctx 0k│ ├─ ✓ fleet: why broker boot is 12-94 s diagnose-crouter-broker-boot-latency [advisor/base] ctx 294k│ ├─ ✓ fleet fix: person stores (sign-ins, env vars, plugins) fleet-design-review-fixes-draft [design/base] ctx 0k│ ├─ ✓ fleet: broker-only memory spike spike-fleet-broker-memory-blaxel [developer/base] ctx 0k│ ├─ ✓ fleet: log and attachment storage evidence [explore/base] ctx 1442k│ └─ ✓ fleet: six build gaps proposal proposal-fleet-build-gaps [design/base] ctx 0k├─ ✓ design cycle 6: the import (design-import) design-cycle6-runtime-import [design/base] ctx 0k├─ ✓ build: cycle 4 one money ledger L1–L6 (c4-build) cycle-4-money-ledger-charges [developer/orchestrator] ctx 0k│ └─ ✓ c4 reconciliation (iv) cycle4-ledger-reconciliation-evidence [general/base] ctx 0k├─ ○ build: cycle 5 the fleet C-S + 5a–5e (c5-build) build-cycle-5-fleet-control-plane [developer/orchestrator] ctx 0k│ ├─ ✓ C-S S0 schema chain runner build-s0-schema-chain-runner [developer/base] ctx 0k│ ├─ ✓ G-1 GitHub installation token route github-installation-token-mint-route [developer/base] ctx 627k│ ├─ ✓ H-1 control plane deploy config build-h1-crouter-k8s-deploy-config [developer/base] ctx 0k│ ├─ ✓ Review G-1 PR github#51 github-installation-token-pr-review [review/base] ctx 443k│ ├─ ✓ Review C-S S0 schema chain runner postgres-schema-chain-release-review [review/base] ctx 475k│ ├─ ✓ C-S S0 review fixes fix-schema-chain-delta-lint [developer/base] ctx 0k│ ├─ ✓ Review H-1 PR hosting#372 crouter-kubernetes-deploy-review [review/base] ctx 383k│ ├─ ✗ C-S S1 002-fleet.sql build-fleet-schema-delta-s1 [developer/base] ctx 0k│ │ └─ ✓ s1-review fleet-postgres-schema-delta-review [review/base] ctx 620k│ ├─ ✓ C-S S2 removal delta 003 build-fleet-removals-schema-delta-003 [developer/base] ctx 0k│ ├─ ✓ Review S2 delta 003 (12ffc9a06) review-crouter-s2-schema-migration [review/base] ctx 429k│ ├─ ○ 5a node in a sandbox (C-A1..C-A5) crouter-cycle5a-fleet-build [developer/orchestrator] ctx 0k│ │ ├─ ○ C-A1 runner + rows build-c-a1-runner-interface [developer/base] ctx 0k│ │ ├─ ✓ C-A3 node files to rows build-node-files-to-rows-unit [developer/base] ctx 0k│ │ │ └─ ✓ review: jobs on rows (D7) review-background-bash-job-migration [review/base] ctx 533k│ │ ├─ ✓ C-A2 prechecks blaxel-runner-ca2-prechecks [general/base] ctx 0k│ │ ├─ ✗ C-A2 Blaxel runner + sandbox start blaxel-runner-sandbox-start-unit [developer/base] ctx 0k│ │ ├─ ✓ C-A4 transport + viewer relay build-ca4-transport-viewer-relay [developer/base] ctx 0k│ │ ├─ ✓ C-A5 recipe image build-recipe-image-reconciler-ca5 [developer/base] ctx 0k│ │ ├─ ✓ 5a combined review review-crouter-fleet-control-plane [review/orchestrator] ctx 307k│ │ │ ├─ ✓ Review 5a A1 runner-lifecycle-token-review [review/base] ctx 223k│ │ │ ├─ ✓ Review 5a A2 blaxel-runner-release-packaging-review [review/base] ctx 268k│ │ │ ├─ ✓ Review 5a A3 file-to-row-migration-review [review/base] ctx 209k│ │ │ ├─ ✓ Review 5a A4 api-url-viewer-relay-review [review/base] ctx 221k│ │ │ └─ ✓ Review 5a A5 recipe-image-pipeline-review [review/base] ctx 271k│ │ ├─ ✓ F-A2 start + image review fixes fix-5a-review-sandbox-start-findings [developer/base] ctx 0k│ │ ├─ ✓ 5a leaked-transaction diagnosis trace-crtrd-postgres-transaction-leak [advisor/base] ctx 753k│ │ ├─ ✓ 5a Linux CI diagnosis diagnose-crouter-linux-ci-failures [advisor/orchestrator] ctx 55k│ │ │ ├─ ✓ Diagnose runner contract Linux failures linux-ci-runner-process-failures [advisor/base] ctx 167k│ │ │ ├─ ✓ Diagnose sandbox and recipe integration failures diagnose-linux-ci-sandbox-wake-failures [advisor/base] ctx 29k│ │ │ └─ ✓ Diagnose Linux broker boot seam failures linux-ci-broker-boot-blocker [advisor/base] ctx 0k│ │ └─ ✓ 5a dismissal-wakes-parked-run race fix-flaky-dismissal-wakes-parked-run-test [developer/base] ctx 0k│ ├─ ✓ 5b blob store (C-B1, C-B2) cycle5-subcycle-5b-fleet-build [developer/orchestrator] ctx 0k│ │ ├─ ✓ C-B1 blob store + conversation store build-blob-and-conversation-store [developer/base] ctx 0k│ │ │ └─ ✓ review C-B1 conversation store conversation-store-commit-review [review/orchestrator] ctx 60k│ │ │ ├─ ✓ review conversation commit integrity row-store-mutation-correctness-review [review/base] ctx 695k│ │ │ ├─ ✓ review conversation reads and legacy import row-store-transcript-import-review [review/base] ctx 1042k│ │ │ ├─ ✓ review conversation reads and legacy import row-store-read-transcript-import-review [review/base] ctx 699k│ │ │ ├─ ✓ review conversation route authorization conversation-authorization-review [review/base] ctx 1215k│ │ │ ├─ ✓ review transaction I/O review-transaction-io-conversation-paths [review/base] ctx 638k│ │ │ ├─ ✓ review client queue and deadline client-worker-queue-ack-review [review/base] ctx 1031k│ │ │ └─ ✓ review route authorization and transaction I/O conversation-api-authorization-io-audit [review/base] ctx 1441k│ │ ├─ ✓ C-B2 run-event chunks, attachments cb2-run-event-chunks-attachments-blobs [developer/base] ctx 0k│ │ ├─ ✓ 5b seam tests: faulting store (a)-(g) + Linux transport conversation-store-seam-tests [developer/base] ctx 0k│ │ └─ ✓ 5b review: C-B2 + seam tests vs C-B1 interfaces crouter-5b-blob-migration-review [review/base] ctx 1280k│ ├─ ○ 5c reconcilers as processes (C-C1..C-C5) cycle5-subcycle-5c-fleet-build [developer/orchestrator] ctx 0k│ │ ├─ ✓ 5c C-C1 pool + lock canvas-db-connection-pool-replace-lock [developer/base] ctx 0k│ │ │ └─ ✓ wcw-audit canvas-transaction-hazard-audit [explore/base] ctx 1537k│ │ ├─ ✓ 5c C-C5 boot binding cuts broker-boot-binding-cuts [developer/base] ctx 0k│ │ ├─ ✓ 5c before measurements baseline-crtrd-stall-boot-metrics [general/base] ctx 0k│ │ ├─ ✓ 5c C-C2 lanes claim rows reconciler-lane-claim-rows [developer/base] ctx 0k│ │ ├─ ✓ 5c C-C3 roles + hot reads crtrd-roles-hot-reads-unit [developer/base] ctx 0k│ │ ├─ ✓ 5c C-C4 cross-process state [developer/base] ctx 0k│ │ ├─ ✓ 5c split-roles + second-boot seam split-roles-seam-integration-tests [developer/base] ctx 0k│ │ ├─ ✓ 5c C-C3 async git lookups async-repo-identity-git-lookups [developer/base] ctx 0k│ │ ├─ ✓ 5c C-C5 tool-guide startup event broker-startup-tool-guide-event [developer/base] ctx 0k│ │ ├─ ✓ 5c combined diff review cycle-5c-fleet-code-review [review/orchestrator] ctx 420k│ │ │ ├─ ✓ 5c C-C1 pool and signals review review-c-c1-fleet-commits [review/base] ctx 599k│ │ │ ├─ ✓ 5c C-C2 row-claim lanes review fleet-c-c2-commit-review [review/base] ctx 729k│ │ │ ├─ ✓ 5c C-C3 role and drain review cycle-five-fleet-commit-review [review/base] ctx 774k│ │ │ ├─ ✓ 5c C-C4 cross-process state review cycle-five-fleet-commit-review [review/base] ctx 1515k│ │ │ └─ ✓ 5c C-C5 boot binding review fleet-broker-commit-review [review/base] ctx 938k│ │ ├─ ✓ 5c fix C-C2 lease fencing + two-process test fix-reconciler-lanes-multiprocess-findings [developer/base] ctx 0k│ │ ├─ ✓ 5c fix C-C4 observer + hold + warm pool fix-cross-process-state-review-findings [developer/base] ctx 0k│ │ ├─ ✓ 5c fix C-C1/C-C3 guard, roles, roster, git, notices fix-5c-review-findings-fleet [developer/base] ctx 0k│ │ ├─ ⊘ 5c failing tests: push retry, profile pause, peer/outbox fix-crouter-cycle5-failing-tests [developer/base] ctx 0k│ │ ├─ ✓ 5c rollback test on pg_dump copy cycle5-5c-rollback-evidence-pgdump-copy [developer/base] ctx 0k│ │ ├─ ✓ bisect dismissal-wakes-parked-run regression bisect-dismissal-wakes-parked-run-test [developer/base] ctx 0k│ │ ├─ ✓ 5c Linux CI: split-roles request_key + stranded nudge fix-linux-ci-split-roles-failures [developer/base] ctx 0k│ │ └─ ✓ 5c Linux CI: peer-cross-machine seam case b bisect-linux-seam-test-failure [developer/base] ctx 0k│ ├─ ✓ C-S delta 004-fleet-blobs add-fleet-blobs-schema-delta-004 [developer/base] ctx 0k│ ├─ ✓ G-1b author in installation-token installation-token-author-field [developer/base] ctx 0k│ │ └─ ✓ review github#56 installation-token-author-pr-review [review/base] ctx 363k│ ├─ ✓ rebase feat/cycle5-fleet onto main 0.3.559 rebase-cycle5-fleet-renumber-schema [developer/base] ctx 0k│ ├─ ○ 5b soak checks soak-checks-blob-conversation-store [developer/base] ctx 0k│ ├─ ○ 5d one Postgres with the directory (C-D1..C-D4, L7, D-1..D-3) cycle5-subcycle-5d-fleet-delivery [developer/orchestrator] ctx 0k│ │ ├─ ✓ 5d C-D4 env vars + secrets key + Blaxel runner wiring env-vars-secrets-key-blaxel-runner [developer/base] ctx 0k│ │ ├─ ✓ 5d D-1 directory shared schema directory-d1-shared-grants-schema [developer/base] ctx 0k│ │ │ └─ ✓ review D-1 shared grants shared-grants-migration-review [review/base] ctx 491k│ │ ├─ ✓ 5d C-D1 tenant from token + TCP auth/TLS + seam un-skips tenant-from-token-tcp-auth [developer/base] ctx 0k│ │ ├─ ✓ 5d D-2 directory grant writers and readers directory-d2-grant-writers-readers [developer/base] ctx 0k│ │ │ └─ ✓ review D-2 PR 276 review-directory-grant-writers-pr [review/base] ctx 505k│ │ ├─ ○ 5d C-D2 grants from rows + grant-effects lane + G1–G4 grants-from-rows-grant-effects-reconciler [developer/base] ctx 0k│ │ └─ ● 5d C-D3 scoped state + model credentials into Postgres move-scoped-state-credentials-to-postgres [developer/base] ctx 0k│ └─ ○ H-3 gate stack (D104) build-h3-gate-stack-cycle-5 [developer/base] ctx 0k│ ├─ ✓ review infra#71 fleet gate review-fleet-gate-infrastructure-pr [review/base] ctx 469k│ ├─ ✓ review firstlight#201 gate overlay review-fleet-gate-overlay-pr [review/base] ctx 125k│ ├─ ✗ review search#36 gate overlay [review/base] ctx 0k│ ├─ ✗ review search#36 gate overlay [review/base] ctx 0k│ ├─ ✗ review search#36 gate overlay [review/base] ctx 0k│ ├─ ✗ review search#36 gate overlay [review/base] ctx 0k│ ├─ ✗ review search#36 gate overlay [review/base] ctx 0k│ └─ ✓ review search#36 gate overlay review-fleet-gate-overlay-pr [review/base] ctx 204k└─ ✓ remote test hosts (--host on test-isolated.mjs) remote-mac-test-hosts-isolated-lanes [developer/base] ctx 0kOne program on 2026-11-01: 118 agents across 14 days, still running. Names as the agents chose them; failed and open rows included.
$ crtr human send --page question.tsx --inbox # ask a person; their answer wakes this agent$ crtr node wait controller <parent-id> # sleep until the parent sends a message$ crtr node new --kind explore "map the auth code" # start a child; its report wakes this agentAny agent can be connected to any other, not only to its parent:
$ crtr node subscription add -hnode subscription add: make one node watch another so it receives that node's pushes — the subscriber can be you (default) or, with --subscriber, ANY node, to ANY publisher. --passive Passive subscription: pushes ACCUMULATE without waking the subscriber, then auto-inject as timestamped XML pre-text on its next message.An agent starts out doing the work itself. When the work splits into parallel parts, it promotes itself:
$ crtr node promote -hnode promote: promote yourself to an orchestrator when worthwhile parallel delegation should make coordination your primary job; task duration, sequential phases, or one helper do not qualify.A parent can require a child’s answer in a fixed shape:
$ crtr node new --output-schema result.schema.json "…"# the child must finish with `crtr push result`; crouter checks it against the schema# or the child declines: crtr push result --decline "<reason>" --code <token>The decline arrives as { reason, code, retryable }, so the parent can tell “blocked” from “bad input” without reading prose.
A person is part of the graph too. An agent can send a page with questions, or open a document for review with an agent beside the reader:
$ crtr human review new -hhuman review new: queue a live document review and return its ticket handle immediately.The person reviews the document in the attach viewer alongside a collaborating companion agent. … When the person submits, their edits are saved as a new revision of the document and the approval is pushed to your inbox.This page’s copy was approved that way.
3. Context is a document with rules
A document decides when it loads, how much of it the reader sees, and who hears about its edits. This is what crouter’s document model covers:
| Context needs to… | In crouter |
|---|---|
| Load on a condition | A rule fires when an agent starts, reads a matching file, runs a matching command, or reads another document |
| Load for the right reader | A rule can require the agent’s kind, mode, repo, profile, working directory or depth |
| Load at the right depth | A rule delivers the name, the one-line preview, or the whole body; a body already in context is not sent again |
| Link to other context | A [[name]] link attaches that document’s preview wherever this one is delivered in full |
| Tell readers it changed | Reading a document makes you a watcher, and every edit is pushed to its watchers |
| Have an owner and a history | A document belongs to an agent, a repo, a profile, an app or you; each revision records who changed it and why |
| Include agents | An agent is itself an object: you can read it, link to it, and watch it like a document |
| Include your services | A registered service is an object too, with its own events; it can watch and be watched |
Four rules from real plugins:
// web plugin: reading any .tsx, .jsx, .css or .html file loads the frontend guide{ "on": "file-read", "match": ["**/*.tsx", "**/*.jsx", "**/*.css", "**/*.html"], "deliver": "content" } // dev plugin: reading the pull-request workflow also loads the guide to PR descriptions{ "on": "document-read", "match": ["dev/pr-loop"], "deliver": "content" } // cloudflare plugin: running wrangler shows the setup guide's one-line preview{ "on": "command", "match": ["*wrangler *"], "deliver": "preview" } // built in: only agents of kind explore get this preview when they start{ "on": "boot", "deliver": "preview", "if": { "kind": "explore" } }What an agent receives at each depth:
<memory kind="knowledge" name="release-checklist" /> <memory kind="knowledge" name="engineering-foundations" readWhen="When you are setting up or changing a Northlight repo's template wiring (Renovate, compose, Prisma, tsconfig, Vitest, CI, secrets, local dev), read this because each of those choices was ruled when the repos were created, so wiring one differently drifts that repo from every other one." /> <memory kind="knowledge" name="demo/deploys">Deploy staging first and wait for the `finished` event before production.</memory>Name, preview, whole body. The agent opens the full document only when the preview says it should.
$ crtr canvas edges wiki/brand/positioning --type watches- watches: <agent> [[rename sweep: crouter cloud → Northlight]] → [[wiki/brand/positioning]]- watches: <agent> [[measure longest task trees]] → [[wiki/brand/positioning]]- watches: <agent> [[draft code.northlight.ai copy]] → [[wiki/brand/positioning]]… 11 watchersEleven agents read the positioning document behind this site. Every edit to it reaches all eleven.
4. Long work gets fresh windows
When an agent’s context fills, it writes where it stands into its roadmap document and starts over in a fresh window. The roadmap loads first; its other documents and its working directory carry over.
$ crtr node yield -hnode yield: request a fresh context window against your roadmap or original goal; mode stays unchanged unless --promote is passed.…(1) If you hold a document `roadmap`, bring it current (`crtr doc edit roadmap`). It, not the yield note, carries your task into the fresh window.$ crtr node inspect show <node-id>- kind/mode/lifecycle: developer / orchestrator / resident- status: active- cycles: 254 · created 2026-10-21T01:36:36.406Z# launched or woken 254 times since 21 Oct; its roadmap has been rewritten 160 timesOne agent on our machine, working on a product rebuild since 21 Oct and still active. Its roadmap is an ordinary document with a rule that loads it whenever the agent starts.