Coordinate work without losing context

One agent, with continuity

Connect your harness, start or resume a Workspace-scoped Session and read brains_get_state. Search existing findings with brains_knowledge_search before repeating expensive investigation. Claim the shared scope before editing.

brains-ai session-start --workspace . --tool claude-code
brains-ai state --workspace .
brains-ai workspace-claim --session <session-id> --scope code --minutes 30

Replace placeholders with returned IDs. At a natural breakpoint, use brains_checkpoint. When stopping, leave brains_set_handoff with the changes, evidence and next action; record only new reusable knowledge, then release the claim and end the Session. The next agent reads the handoff rather than reconstructing a transcript.

Two agents, with clear ownership

Give each agent a distinct Session in the same Workspace. Use session-start --new if the same harness would otherwise reuse a handle. Assign bounded tasks and respect both task ownership and Workspace claims.

brains-ai task-create --title "Review the migration" --priority p1
brains-ai task-claim --code <task-code> --session <session-id>
brains-ai task-complete --code <task-code> --session <session-id> --summary "<result and evidence>"
brains-ai workspace-release --session <session-id>

Complete only after checking the result. Claims are cooperative coordination, not filesystem isolation; give simultaneous writers non-overlapping working copies or scopes.

Inspect a request, then accept that request

File a bounded question for a peer. Use only the Session target for one specific peer; combining Session and Workspace targets broadens matching.

brains-ai help-file --subject "Review the migration" --question "Are existing rows preserved?" --from-session <requester-id> --to-session <peer-id> --timeout-ms 300000
brains-ai inbox-wait --session <peer-id>
brains-ai help-get <help-code> --session <peer-id>
brains-ai help-claim-code <help-code> --session <peer-id>
brains-ai help-answer <help-code> --session <peer-id> --answer "<findings>" --evidence "<checkable evidence>"

Exact acceptance never substitutes queued work or launches a worker. Same-owner retries do not extend the claim. Filing timeout sets request lifetime; waiting timeout only bounds the wait. inbox-wait neither accepts work nor reads durable mail. Read mail separately with Session attachment and binding proof.

Keep human decisions separate

Use brains_file_decision_request for a human question, not a peer-help request. The human answers in the console or through decision-resolve; the Session that filed the ask cannot resolve it. Continue unrelated work while waiting.

Approval applies to actions routed through the supported governance boundary. It does not contain arbitrary commands or network calls from an external harness. An evidence field makes an answer checkable, not automatically correct.

Read the full workflow and ownership and timeout contract. CLI examples here follow the tagged command implementation.