cavi-ai
GitHub ↗

CLI reference

text
agent-sessions [--minutes N] [--json] COMMAND

Global options precede the command. --minutes changes the discovery window (default 30); --json selects machine-readable output where available. Profile and partner operations already print structured results.

For exact positional arguments and options, use agent-sessions COMMAND --help.

Discovery#

CommandPurpose
listList recent sessions, newest first
list --reviewsInclude Codex approval-review threads
who [PATH]Show sessions in a repository, including linked worktrees; PATH defaults to .

SAME WORKTREE means the same checkout. Overlapping paths compare uncommitted files and recorded edits; they do not establish file ownership or a live process.

sh
agent-sessions --json --minutes 120 who /path/to/project

Messaging#

CommandPurpose
send TO 'text' [--session ID]Queue a message for a discovered session ID or existing directory
inbox [--session ID]Receive messages for a session
inbox --keep [--session ID]Preview without marking received
claim MESSAGE_ID ['reply'] [--session ID]Reserve a message; reply defaults to ready
status MESSAGE_IDReport pending, received or claimed state and its receivers or holder

A session ID prefix must be unambiguous and at least six characters. Receiving is not claiming. Replies reference their original message and need no claim. See Messaging and claims.

Hook configuration#

CommandPurpose
configure codexMerge this installation's handlers into Codex settings
configure claudeMerge this installation's handlers into Claude settings
configure HOST --dry-runPrint the merged settings without writing
configure HOST --removeRemove this installation's handlers, preserving other settings
hook [--host codex|claude]Read one native hook payload as JSON on stdin

hook is a host entry point. It uses session_id (or thread_id), cwd and hook_event_name; native transcript and subagent fields help route delivery. Configured commands supply the host explicitly. Profile mismatches exit 2; ordinary message-hook errors report a diagnostic and return 0.

See Hook setup.

Partners#

CommandPurpose
partner claude PATH 'brief'Queue an invitation for a later Claude session
partner codex PATH 'brief' --project-id IDSave a native app creation request
partner HOST PATH 'brief' --profile PROFILE_IDPrepare a guarded profile launch
partner connect PAIR_ID [SESSION_ID] [--host-id local]Connect a discovered native endpoint; session defaults to the caller
partner attach SESSION_ID [--profile PROFILE_ID]Record an existing worker
partner show PAIR_IDInspect a saved pair and its request or launch state
partner resume PAIR_ID [--dry-run]Resume the connected partner with its pinned profile
partner run PAIR_ID [--prompt-file FILE] [--timeout SECONDS] [--no-mcp]Own one Codex turn with direct profile and capability checks; --no-mcp rejects enabled MCP servers; timeout defaults to 60 seconds

Creation, connection, attachment and resume accept --session ID to identify the caller explicitly. partner resume requires a connected, profiled partner. Ordinary native chat resume remains the host's operation.

See Partner sessions.

Profiles#

CommandPurpose
profile create HOST PATH NAME [--file RELATIVE_PATH]Pin required native files and any extra relative files
profile show PROFILE_IDValidate and inspect a saved profile
profile launch PROFILE_ID [--pair PAIR_ID] [--dry-run]Start a native host through the guarded launcher
profile launch PROFILE_ID --resume SESSION_ID [--dry-run]Resume a bound native session

Repeat --file to pin multiple extra files. A real launch replaces the CLI process with the native host. A dry run prints its command, working directory and profile marker without starting it.

See Worker profiles for required files, credential handling and the limits of profile checks.

agent-sessions protocol reports supported managed receipt contracts without starting a host.

Resource control#

agent-sessions resource returns compact JSON without scanning host transcripts or receiving peer messages. Its subcommands are protocol, request RESOURCE KEY [--seconds N], status TICKET, wait TICKET [--seconds N], start TICKET --lease TOKEN --fence N, cancel TICKET, finish TICKET --lease TOKEN --fence N --outcome completed|failed|unresolved [--evidence SHA256], and events [--after CURSOR]. resource --session OWNER retains a supervised recovery's logical identity.

The API is for resident resource adapters; separate short-lived shell invocations are not a native lifecycle supervisor. Admission binds the parent PID and kernel birth identity. Wait deadlines are 0.001–3600 seconds; the queue holds at most 256 pending tickets. A running operation is never expired to free its resource. See queued resources for lifecycle and recovery rules.

request accepts --resumable, --payload-sha256 SHA256 and --estimate-seconds N; its queue deadline can be up to 86400 seconds. wait --keep preserves a queued ticket when its wait window ends. events --lifecycle includes deduplicated start signals as well as terminal events. Status includes UTC timestamps, jobs/sessions ahead, estimated wait, its basis and a next-check interval; unknown ETA is explicit.