Components

Verbs

The 19 subcommands under python ujima.py. Each does exactly one mechanical thing — delivery, a timer, a state transition — so agents spend judgment on what to say, not on bookkeeping. Grouped here by job, matching the CLI's own --help ordering.

Boot & identity

Stand up a workspace, register an agent, and resolve who is acting — before anything else can happen.

init
Creates a new workspace: .ujima/, agents/, events/, checkpoints/, escalations/, broadcasts/, shared/, and workspace.json.
cli/ujima.py:321 cmd_init
Usage
python cli/ujima.py init "C:\path\to\workspace" --name my-team
👤
agent add / list / show
Registers an agent folder + agent.json, or lists/shows existing agents.
cli/ujima.py:348 cmd_agent
Usage
ujima agent add reva --role "COO / Orchestrator" ujima agent list ujima agent show reva
🪪
whoami
Prints the resolved agent identity: --as flag, else $UJIMA_AGENT, else .ujima/identity.
cli/ujima.py:396 cmd_whoami
Resolution order
--as <name> → $UJIMA_AGENT → .ujima/identity → die("no agent identity")
📋
brief
The session boot digest — GOALS head, latest checkpoint, team status, unread mail, open escalations, recent broadcasts, last 8 ledger notes. Replaces the 11-step boot ritual.
cli/ujima.py:583 cmd_brief · full render: surface-brief.html
Footer line, verbatim
Verbs: send/reply | inbox/read/archive | status set | log | checkpoint | sweep | doctor

Messaging

Atomic, addressed delivery with receipts — replaces the v1 directives folder and the v2 mailroom outbox→hub→inbox pipeline.

✉️
send
Delivers a message instantly to one recipient or '*' (broadcast). Body capped at 2,000 chars — longer content goes in notes/artifacts and gets referenced by path.
cli/ujima.py:401 cmd_send · deliver() at :280
Usage
ujima send --to jorin --subject "System live" --body "..." [--priority urgent]
Cap exceeded
ujima: error: body is 2143 chars (cap 2000). Put the detail in a file under agents/<sender>/artifacts/ or notes/ and reference the path in a shorter body.
↩️
reply
Replies within an existing thread id, reusing the thread's T- id rather than minting a new one.
cli/ujima.py:433 cmd_reply
Usage
ujima reply M-20260718T083200Z-k7m2 --body "Findings reviewed, escalating."
📥
inbox
Lists messages in the agent's own inbox/, optionally filtered to unread only.
cli/ujima.py:454 cmd_inbox
Usage
ujima inbox --unread
👁️
read
Prints a message body and emits message.read — the act of reading IS what marks it read; there is no separate mark-as-read step.
cli/ujima.py:479 cmd_read
Usage
ujima read M-20260718T083200Z-k7m2
🗄️
archive
Moves an inbox message file to archive/. Files are immutable after delivery — archiving moves, never edits.
cli/ujima.py:498 cmd_archive
Usage
ujima archive M-20260718T083200Z-k7m2

Shared state

Any agent can answer "who is doing what, what happened, is anyone blocked" without asking — state is an append-only event log; STATUS.md and LEDGER.md are generated renders of it, never hand-edited.

🚦
status set / show
Declares WORKING / IDLE / BLOCKED / WAITING / OFFLINE with a task or blocked_by note. Replaces the lock→edit→release dance on STATUS.md.
cli/ujima.py:511 cmd_status · STATES tuple :36
Usage
ujima status set WORKING --task "Wave-1 orchestration" ujima status set BLOCKED --blocked-by "waiting on jorin's audit"
📝
log
Appends one ledger note, capped at 300 chars, optionally with a workspace-relative --ref path. Replaces the lock→append→release dance on LEDGER.md.
cli/ujima.py:546 cmd_log · CAP_LEDGER=300 :26
Usage
ujima log "Triaged 14 tasks into Todo" --ref agents/reva/notes/2026-07-02.md
📖
ledger
Prints recent ledger notes read straight from the event log.
cli/ujima.py:557 cmd_ledger
Usage
ujima ledger --last 8
🧷
checkpoint
Writes the next checkpoint from stdin or --file, capped at 4,000 chars. sweep nudges when 50+ ledger notes have accrued since the last one.
cli/ujima.py:566 cmd_checkpoint · CAP_CHECKPOINT=4000 :28
Usage
ujima checkpoint --file CHECKPOINT-005.md

Cadence & health

Housekeeping and escalation that v1/v2 had no equivalent of at all — a health check, an adaptive polling cadence, and a scheduler-friendly sweep.

📶
poll check / reset / config / show
Adaptive check-in cadence: short interval at first (4 min default), doubles after a warmup of empty checks up to a 30-min cap, resets to short on any actionable input. Per-agent knobs in poll.json.
cli/ujima.py:722 cmd_poll · POLL_DEFAULTS :685
Defaults
base_min: 4, multiplier: 2.0, cap_min: 30, warmup_checks: 3
🧹
sweep
Housekeeping + escalations, meant to run from a scheduler: expires stale locks, escalates unread messages (urgent >30m, normal >4h), escalates stale status (>24h), nudges an overdue checkpoint. Full transcript: surface-doctor.html.
cli/ujima.py:837 cmd_sweep
Timers
ESC_URGENT_MIN=30, ESC_NORMAL_MIN=240, ESC_STALE_STATUS_MIN=1440, CHECKPOINT_DUE_NOTES=50
🩺
doctor
Validates the whole workspace — structure, agent identity cards, message parsing, event log integrity, encoding, secret patterns, size caps, generated-view drift, stale convenings. Exits 1 on any FAIL.
cli/ujima.py:1324 cmd_doctor
Secret patterns scanned
Slack token, Anthropic key, OpenAI key, GitHub token, Google API key, Asana PAT, PEM private key block
🔁
render
Regenerates STATUS.md and LEDGER.md from events/ — the only thing allowed to write those two files. Every generated file carries a DO-NOT-EDIT banner; doctor warns if it's missing.
cli/ujima.py:829 cmd_render
Banner, verbatim
<!-- GENERATED by `ujima render` - DO NOT EDIT. Source of truth: events/ -->

Shared-file locking

The only writable surface with more than one potential writer — everything else is owned by exactly one agent or one process. A rare, TTL'd escape hatch, not the default coordination mechanism.

🔒
lock
Locks a file under shared/ with a 10-minute TTL. sweep silently expires any lock older than the TTL, so a crashed agent can never strand a lock forever.
cli/ujima.py:1467 cmd_lock · LOCK_TTL_SEC=600 :30
Usage
ujima lock shared/WORKING-AGREEMENTS.md
🔓
unlock
Releases a lock held by the current agent before its TTL expires.
cli/ujima.py:1493 cmd_unlock
Usage
ujima unlock shared/WORKING-AGREEMENTS.md