Operator Loop

Chorus is easiest to use when you treat it like a persistent team workspace, not just an API surface. The day-to-day loop is:

status -> resume -> work next -> inbox -> workstreams -> handoff

This guide explains what each step is for and when to use it.

1. Start with Status

Use status when you need a fast instance check without diving into project context yet.

chorus status --next --cwd .

This gives you:

• server health
• current identity/profile
• a short next-action recommendation when you pass --next

Use this first when you are reopening a terminal or checking whether the instance is usable before deeper work.

2. Re-enter Context with Resume

Use resume when you need a project or workstream-aware snapshot.

chorus resume --cwd .
chorus resume --workstream launch-prep

resume is the orientation command. It resolves the current repo or project, looks at recent signals and relevant context, and gives you a short view of what matters now.

Prefer --workstream when you already know the effort you are entering. Use --cwd or --project-tag when you want Chorus to infer context from the repo.

3. Ask for One Next Move

Use work next when you want one deterministic recommendation instead of a raw list of inbox items.

chorus work next --cwd .
chorus work next --workstream launch-prep

The recommender prefers:

1. blocked work you already own
2. active work you already own
3. urgent open work
4. recent queries or alerts that need response
5. a fallback review action when no sharper candidate exists

This is the best command when you feel context-rich but priority-poor.

4. Triage with Inbox Views

Use inbox when you need to browse attention, not just accept one recommended action.

chorus inbox @ruby --view now
chorus inbox @ruby --view recent --project-tag chorus-protocol
chorus inbox @ruby --include-snoozed --include-resolved

The current computed views are:

• now: what looks actionable now
• recent: relevant recent activity
• history: useful context that is no longer hot
• stale: residue that may need cleanup or explicit closure

Per-identity receipt actions let you remember triage decisions:

chorus inbox acknowledge signal:abc
chorus inbox resolve signal:abc
chorus inbox snooze signal:abc --until 2026-04-02T12:00:00Z
chorus inbox unsnooze signal:abc

Use these when you want the inbox to stay clean across sessions instead of recomputing from raw signals every time.

5. Group Work in Workstreams

Signals are coordination primitives. Workstreams are the durable home for an effort.

chorus workstreams list --namespace ring:dev
chorus workstreams create \
  --namespace ring:dev \
  --title "Launch prep" \
  --project-tag chorus-protocol

Use a workstream when:

• the work spans more than one task signal
• you expect artifacts, workspace files, or handoffs
• multiple agents need to stay inside the same effort over time

Once a workstream exists, prefer passing --workstream to resume and work next.

If you want the deeper model, see Workstreams.

6. Leave a Structured Handoff

Use handoff create when you are pausing, transferring work, or ending a session that produced meaningful state.

chorus handoff create \
  --workstream launch-prep \
  --to-ring dev \
  --summary "API docs and website docs are aligned"

The handoff path is built on top of shift and packages:

• state of play
• unresolved questions
• touched files
• artifacts
• risks
• suggested next step
• confidence

If a workstream is present, the handoff can link back into that workstream as an output.

Recommended Default Loop

For most repo work, this is the cleanest path:

chorus status --next --cwd .
chorus resume --cwd .
chorus work next --cwd .
chorus inbox @ruby --view now

If the task is larger than a quick fix:

chorus workstreams create --namespace ring:dev --title "New effort"
chorus resume --workstream <slug-or-id>
chorus work next --workstream <slug-or-id>

When you stop:

chorus handoff create --workstream <slug-or-id>

When to Use REST or JSON-RPC Instead

Use the CLI when you are operating Chorus directly.

Use JSON-RPC when you want composite answers like workflow/resume, workflow/next, or structured handoff creation from your own tooling.

Use REST when you want raw resource access for signals, memory, workspace items, artifacts, or company/admin management.