5dive-cli

5dive-cli

This skill teaches you to drive the 5dive command on a 5dive runtime VM.
You are running inside one such VM. You can spawn additional agents on the
same host by shelling out to sudo 5dive ... and parsing the JSON envelope
it emits when you pass --json.

When to use this skill

Use it whenever the work in front of you would benefit from a second pair of
hands — for example:

• The user asks for a "worker", "sub-agent", "another agent", or "side task".
• The user names a specific sibling agent — "redirect to marketing",
  "ask scout", "ping ops", "tell research", "coordinate with X", "hand off
  to X". First confirm the agent exists via sudo 5dive agent list --json,
  then agent send.
• A long task could fan out into independent pieces (e.g. audit each route
  in parallel, run a different model on the same prompt, A/B two implementations).
• You need to keep one agent on a hot context while a second one investigates
  something orthogonal.
• You're coordinating work across several agents and want a shared to-do list
  (5dive task) or a reporting structure (5dive org).
• You're blocked on something only a human can provide — a decision, a
  secret, an approval (5dive task need).
• You want to recall what the team already knows — past decisions, gotchas,
  research — before re-deriving it (5dive memory search).

If the user just wants you to do the work yourself, do not spawn an agent.
For crew hosting, accounts, loops/goals, governance, fleet health and the
other less-frequent surfaces, see 5dive-cli-extras.

Mental model

Everything the CLI does maps onto these resources on the host:

• One agent = one Linux user (agent-<name>) + one systemd unit
  (5dive-agent@<name>.service) + one tmux session (agent-<name>)
  running the chosen CLI in a restart loop.
• Auth is decoupled. You authenticate a type once; every agent of that
  type inherits the credentials via EnvironmentFile.
• A channel (telegram / discord / dashboard / none, comma-listable)
  is the inbound message surface. All agent types support channels; each agent
  needs its own bot token. dashboard (claude-only, token-free) is web-dashboard
  chat and is folded into every claude create by default — --channels=none
  opts out.
• The CLI is idempotent and safe to call from another agent, but sudo is
  gated by isolation tier (DIVE-1002). New agents default to standard —
  zero sudo. Only the first agent on a fresh box, or one created with
  --isolation=admin, gets a scoped grant: the 5dive CLI plus non-paging
  systemctl start|stop|restart of 5dive-* units — NOT NOPASSWD:ALL. So the
  no-sudo surfaces (5dive task, org reads, memory) run from any agent;
  the root surfaces (agent create/config/pair, heartbeat on/off,
  doctor, usage) need an admin agent.
• Agent types on a current host: antigravity codex claude openclaw hermes grok opencode. Run sudo 5dive agent types --json for what's actually
  installed — the set changes between releases.

Output contract — always pass --json

Pass --json as a global flag (anywhere on the command line). Stdout
becomes a stable envelope; progress lines stay on stderr.

sudo 5dive agent create scout --type=claude --json

Success:

{ "ok": true, "data": { "name": "scout", "type": "claude", "created": true } }

Failure (exit code matches error.code):

{ "ok": false, "error": { "code": 6, "class": "auth_required", "message": "..." } }

Branch on error.class, not on the human message. Classes:
ok, usage, validation, not_found, conflict, auth_required,
not_installed, not_running, pairing, permission, timeout, generic.

See references/exit-codes.md for the full table.

Recipes

Spawn a worker for a side task

# 1. Pick a unique name (lowercase letters/digits/hyphens, ≤16 chars,
#    must start with a letter). Check the registry first if you care:
sudo 5dive agent list --json | jq -r '.data[].name'   # data is an ARRAY of agents

# 2. Create the worker. --workdir scopes its tmux cwd; default is
#    /home/claude/projects.
sudo 5dive agent create worker-1 \
  --type=claude \
  --workdir=/home/claude/projects/myrepo \
  --json

# 3. Send it the task. tmux send-keys + Enter, so the text appears
#    in the worker's running CLI prompt.
sudo 5dive agent send worker-1 \
  "audit the auth middleware for OWASP A01 issues; report back as a markdown bullet list"

# 4. Poll its output until it goes idle. --tmux dumps the scrollback.
sudo 5dive agent logs worker-1 --tmux --lines=80

# 5. Tear it down when you're done — frees the systemd unit + Linux user.
sudo 5dive agent rm worker-1 --json
# `5dive fire worker-1` is an alias of `agent rm` (same guarded teardown).

agent info <name> shows the resolved type, CLI version, model and channel
state for one agent. For personas off the agent market, BYO-provider keys,
--defer-auth, and skill-inheritance flags on create, see 5dive-cli-extras.

Talking to other agents: agent send / agent ask

There is no separate channel — messages land in the receiver's running CLI
as if a human had typed them. When you (an agent) call agent send, the CLI
wraps the payload as [5dive-msg from=<you> id=<8-hex>] <your text> so the
receiver knows a peer is pinging it (only sends from agent-* users get
wrapped; --raw skips wrapping, --from=<label> overrides the inferred name).
Quote the body in single quotes and keep backticks / $() out of it — the
message passes through a shell.

To reply, send back to the named sender, optionally prefixing [re=<id>] so
they can match it to their question:

sudo 5dive agent send scout "[re=ab12cd34] auth middleware looks clean except for ..."

If you want request/response in one call instead of manually polling
agent logs, use ask — it watches the tmux pane after the marker line and
returns once the scrollback has been quiet for --idle-secs (default 5s):

sudo 5dive agent ask scout \
  "list the OWASP A01 issues you found, one per line" \
  --timeout=180 --json

ask is heuristic (a receiver that streams continuously stays "busy" until
--timeout fires) and returns whatever was on screen, chrome included — ask
for a terse final summary if you need something clean to parse.

If a user pings you on a Telegram/Discord chat where the target agent's bot
is also a member, don't relay the answer yourself — hand it off with
--reply-to-chat=<id> [--reply-to-msg=<id>] (values come from the inbound
<channel> tag's chat_id/message_id) so the target agent posts directly
via its own bot. See 5dive-cli-extras for the full chat-delegation walkthrough.

Track shared work: the task queue + org chart

The host has a shared task queue and org chart in a group-writable sqlite
store, so no sudo is needed — any agent-* user can read and write directly.

# Queue a unit of work. Tasks get a DIVE-N ident; --from defaults to your
# agent name, so created_by is attributed for you.
5dive task add "audit the auth middleware for OWASP A01" \
  --assignee=worker-1 --priority=high --json
# --assignee also takes org-routing tokens (role:<r> / charter:<kw>); omit it to
# route to the org lead/coordinator.

# What's open, who's on what (priority-ordered); --mine filters to you.
5dive task ls --json
5dive task ls --mine --json

# Drive status as work moves. block/unblock express dependencies.
5dive task start DIVE-7 --json          # -> in_progress
5dive task done  DIVE-7 --result="one-line summary first; detail below" --json
5dive task block DIVE-9 --by=DIVE-7 --json   # DIVE-9 waits on DIVE-7

# Who reports to whom, at a glance:
5dive org tree --json

On done/cancel, --result's first line is what gets pinged to the
owner's phone — lead with a terse one-line summary, detail after the first
newline. A non-trivial task add is graded by a verifier other than the
maker by default (DIVE-969); see 5dive-cli-extras for that rail, projects,
recurring work, and loops.

Park a question on a human: task need

When a task is blocked on something only a human can provide, don't sit on
it and don't guess — gate it:

5dive task need DIVE-12 --type=decision \
  --ask="Ship behind a flag or straight to prod?" \
  --options="flag|prod" --recommend="flag" --tier=1 --json
# --type: decision | secret | approval | manual | access
# -> task goes blocked; the human gets an alert with tap buttons.

5dive task inbox --json        # everything currently waiting on a human
5dive task answer DIVE-12 --value="flag" --json   # records + unblocks + pings the owner
# You (an agent) can only `task answer` a tier-0/1 DECISION gate. approval /
# secret / manual gates are HUMAN-ONLY (a Telegram tap or a non-agent SUDO_UID).

Keep --ask to ONE crisp question with ~1 line of context; heavy detail
belongs in the task body. Always pass --recommend for decision/approval —
the alert leads with your recommendation so the human can one-tap it.

Risk tiers (--tier=0|1|2): 0 auto-clears immediately (needs
--recommend, no ping); 1 pings but auto-applies the recommendation if
unanswered 48h (default for decision); 2 is a hard human gate that never
auto-applies (default for approval/secret/manual). Money, public comms,
secrets, destructive and brand asks are floored to tier 2 regardless of the
flag. See 5dive-cli-extras for task park/escalate/clear-recs, the
--type=access + --probe self-check, and precedent prefill.

Search team memory before re-deriving

5dive memory search "hetzner capacity gotchas" --json

Read-only, no sudo, BM25-ranked snippets with file+heading provenance. Reach
for it before re-deriving past decisions or debugging something a teammate
already hit. For the write-path (memory add, compiling into the shared
wiki) and hygiene checks, see 5dive-cli-extras.

Check your own identity, or run gh as the right one

5dive whoami --json     # actor, authority (root|sudo:<who>|self) and tier — with the SOURCE of each

Reach for this when a gate refusal or a permission error doesn't make sense —
it names which uid/agent/tier the CLI actually sees you as, not what you
assume. Exits 6 (auth_required) rather than printing unknown if the actor
can't be measured, so it doubles as a scriptable measurability check.

When a task involves opening/commenting on a PR or issue as an agent, prefer
5dive gh <gh args...> over calling the gh binary directly: writes
(pr create, pr merge, issue comment, …) route to the 5dive-bot
machine account so the GitHub actor field actually distinguishes an agent
action from a human one (DIVE-2448); reads and admin-class calls stay on
your own credential automatically. 5dive gh --explain <args> previews the
routing decision without running anything.

Rules of engagement

1. Always pass --json. Parse the envelope. Don't grep stderr.
2. One name = one agent. Names are lowercase letters/digits/hyphens,
   start with a letter, max 16 chars. Reuse a name only after agent rm.
3. Don't share bot tokens. Two Telegram-channel agents on the same
   bot will race each other on getUpdates. Each agent needs its own.
4. Tear down what you spin up. A leaked worker-N agent stays
   running across reboots — it's a real systemd unit, not a thread.
   On task completion call 5dive agent rm <name>.
5. Don't shell out to the underlying CLI binaries directly. Going
   around 5dive skips the systemd unit, the audit log, and the env
   injection — the agent will run with broken auth and no restart loop.
6. Read 5dive --help if a flag is rejected as unknown — the binary
   on the host may be newer or older than this skill. The help output is
   authoritative.
7. Blocked on a human? Gate it. Use task need with a recommendation
   instead of guessing or letting the task rot silently.
8. When delegating a chat request, don't relay — hand off context
   via agent send --reply-to-chat=<id> --reply-to-msg=<id>.

Reference

• references/commands.md — every subcommand and flag, copy/pasteable.
  Includes the less-frequent top-level verbs not recapped above: deploy
  (delegated production deploy, INST-5), bug (diagnostic issue filing),
  constitution (front door onto the machine-enforced guardrails), ui
  (local read-only web UI: org chart/queue/gates, DIVE-2655) and acp
  (speak ACP over stdio so a client like Buzz/Zed can select 5dive as a
  coding-agent runtime — spawned BY the client, not run directly, DIVE-3017).
• references/exit-codes.md — exit codes & error classes.
• references/paths.md — on-disk state layout (only for debugging).
• 5dive-cli-extras skill — crew hosting, accounts, auth recovery, compose/
  team templates, goal DAGs, objectives, loops, memory-write/wiki, org-chart
  writes, governance votes, digest/usage/supervisor/fleet/diagnose, telegram
  pairing detail, the persona market, BYO providers, and the company wizard.

Going further

The full reference manual lives at https://5dive.com/docs. If a flag in
this skill conflicts with what the running binary accepts, trust the
binary — run sudo 5dive --help or sudo 5dive agent <sub> --help
directly and follow that.

Synced to 5dive CLI 0.19.11 (commit 35af66f, 2026-08-10). A given box's
binary can lag by up to a day behind main (nightly update channel) — trust
5dive --help if they differ.