5dive-cli
GitHub用于在5dive运行时VM中通过CLI管理子代理。支持创建、发送消息、检查状态及销毁代理，特别适用于并行任务、委托或需保持聊天上下文转发的场景。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill 5dive-cli -g -y
SKILL.md
Frontmatter
{
"name": "5dive-cli",
"description": "Use the local `5dive` CLI on a 5dive runtime VM to spawn, inspect, send to, and tear down sibling agents. Trigger this skill whenever the user asks for a worker, sub-agent, side task, parallel run, \"another agent\", \"fan out\", \"delegate\", or names a sibling agent in natural language (\"redirect to X\", \"ask X\", \"ping X\", \"tell X\", \"coordinate with X\", \"hand off to X\") — in those cases confirm the agent exists with `5dive agent list --json` first, then `agent send`. Also trigger when the user asks to inspect, restart, or pair an existing agent, when they mention `\/var\/lib\/5dive\/`, or when they need a machine-readable health check (`5dive doctor --json`). When the user's request arrived over a chat channel (Telegram\/Discord `<channel>` tag) and they want another agent involved, hand off the chat context via `--reply-to-chat=<id> --reply-to-msg=<id>` so the target agent replies directly in the chat from its own bot — don't relay. Always prefer `5dive` over running coding CLIs by hand — it is the only sanctioned way to keep agents under systemd."
}
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, thenagent send(and pass chat context if the request came from a channel — see "Delegating a request that came in over a channel" below). - 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.
- The user wants to inspect / restart / pair / tear down an agent that already exists on the host.
- You need a machine-readable health check of the host's coding-CLI stack.
If the user just wants you to do the work yourself, do not spawn an agent.
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/none) is the inbound message surface. Channels are only supported byclaude,openclaw,hermes. - The CLI is idempotent and safe to call from another agent — your agent
user is in the
claudegroup and hassudo 5dive ...whitelisted.
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 '.data.agents | keys'
# 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
Skill inheritance on agent-spawned children
When an agent (you, SUDO_USER=agent-*) creates another agent of any
supported type, the CLI auto-installs the 5dive-cli skill into the child
so it inherits inter-agent comms knowledge. Humans creating from the
dashboard don't get this default. Override either way:
--with-skills=<spec>[,<spec>...]— explicit list. Each spec is a bare id (defaults to5dive-com/skills) or<owner/repo>:<id>. Example:--with-skills=5dive-cli,acme/skills:db-tools.--no-skills— opt out, even when called from another agent.
Create-then-auth: --defer-auth
Use when you want the agent registered before its credentials are wired up
(e.g. the agent's own first-run UI will handle sign-in). Skips the auth gate
on agent create; combine with --auth-profile=<name> to bind a profile slot
that doesn't yet have a combined.env.
sudo 5dive agent create draft-bot --type=claude --defer-auth --json
Fan out: same prompt, three different models
Useful for "let me see how Codex/Gemini/Claude each approach this".
for type in claude codex gemini; do
sudo 5dive agent create "fan-${type}" --type="${type}" --json
sudo 5dive agent send "fan-${type}" "$PROMPT"
done
# Wait, then collect the last 200 lines of each:
for type in claude codex gemini; do
echo "=== ${type} ==="
sudo 5dive agent logs "fan-${type}" --tmux --lines=200
done
# Cleanup.
for type in claude codex gemini; do
sudo 5dive agent rm "fan-${type}" --json
done
Recover from auth_required
# If create fails with error.class=auth_required, the type isn't authenticated.
# Two paths — pick by what credentials you have:
# A) Static API key in $KEY (preferred for automation)
echo "$KEY" | sudo 5dive agent auth set claude --api-key=- --json
# B) Device-code flow (when only a human can complete login)
sudo 5dive agent auth start claude --json
# -> session id; give the URL from `auth poll` to the user; they paste the
# callback code back via `auth submit`.
Never call 5dive agent auth login <type> from your own process — it
hands the TTY off to the upstream CLI's interactive flow and hangs your
agent. Use auth start / auth set instead.
Multi-account: the account noun
A 5dive account is a named auth profile — one bag of credentials that any
number of agents can share via --auth-profile=<name>. Use it when the host
has more than one human / billing identity (e.g. work + personal Anthropic
sign-ins) and different agents should use different ones.
5dive account ... is the user-facing surface; the lower-level
agent auth start|poll|submit|cancel verbs are still what the dashboard's
device-code flow uses, and what you should use from a script.
# Inventory: which named accounts exist, what types each is signed into,
# and how many agents are bound to each.
sudo 5dive account list --json
# Detail for one account, including which env keys are populated.
sudo 5dive account show acme-prod --json
# Provision a new empty account, then sign it in (TTY-only — humans).
sudo 5dive account add acme-prod
sudo 5dive account login acme-prod --type=claude
# Rebind an existing agent to a different account. Restarts the agent so
# the new EnvironmentFile takes effect.
sudo 5dive agent set-account worker-1 acme-prod --json
sudo 5dive agent set-account worker-1 default --json # clears the override
# Rename / remove. `remove` refuses while any agents are still bound.
sudo 5dive account rename acme-prod acme-staging --json
sudo 5dive account remove acme-staging --json
The reserved name default is rejected by account add / rename — at the
agent level, auth-profile=default already means "no override, use the shared
/etc/5dive/connectors/<type>.env".
Pair a Telegram channel without a bot reply
agent pair accepts three input shapes:
# A) Classic — return a pairing code, user DMs the bot, paste the bot reply.
sudo 5dive agent pair worker-1 --json
sudo 5dive agent pair worker-1 --code=AB12CD --json
# B) Auto-detect — long-poll Telegram for the next inbound message and
# seed access.json from whoever DMs the bot first. Useful in onboarding
# flows where the user has the bot open already.
sudo 5dive agent telegram-discover --token="$BOT_TOKEN" --poll-secs=60 --json
# -> {found:true, userId, chatId, ...}; re-poll on {found:false}.
sudo 5dive agent pair worker-1 --user-id=<userId> --chat-id=<chatId> --json
# C) Bot identity for deep links — fast getMe lookup so the dashboard can
# render a tappable t.me/<bot> link alongside the "send /start" prompt.
sudo 5dive agent telegram-getme --token="$BOT_TOKEN" --json
# -> {ok:true, data:{botId, username, firstName}}
telegram-discover and telegram-getme are read-only (no registry mutation,
no audit log) and do not require a bound agent.
Talking to other agents (inter-agent comms)
agent send and agent ask work as a tiny message bus between agents on the
same host. There is no separate channel — messages land in the receiver's
running CLI as if a human had typed them.
Sending: attribution is automatic
When you (an agent) shell out to sudo 5dive agent send <name> "...", the CLI
sees that $SUDO_USER is agent-<you> and wraps the payload as:
[5dive-msg from=<you> id=<8-hex>] <your text>
so the receiver can tell it's being pinged by a peer agent and which one.
Override the inferred name with --from=<label>. Skip wrapping with --raw
(useful when you're piping a prompt that already has its own structure).
Humans running sudo 5dive agent send directly never get auto-wrapped — only
sends from agent-* users do.
Receiving: recognise the envelope and reply by name
When a line like
[5dive-msg from=scout id=ab12cd34] please summarise the auth middleware audit
appears as your input, treat it as an inter-agent request. To reply, send back to the named sender:
sudo 5dive agent send scout "[re=ab12cd34] auth middleware looks clean except for ..."
The [re=<id>] prefix is convention, not enforced — it lets the original
sender match your reply to their question when they're juggling several at
once. Drop it for casual back-and-forth.
One-shot synchronous calls: agent ask
If you want a request/response in one CLI call (no manual polling of
agent logs), use ask:
sudo 5dive agent ask scout \
"list the OWASP A01 issues you found, one per line" \
--timeout=180 --json
It sends the wrapped envelope, then watches tmux capture-pane after the
marker line and returns once the scrollback has been quiet for --idle-secs
(default 5s). Stdout (text mode) is just the reply body; in --json mode the
envelope is {ok:true, data:{name, from, msg_id, reply}}.
Caveats — read these before leaning on ask:
- Idle-by-stability is heuristic. A receiver that streams progress
continuously will keep
askawake until--timeoutfires. If you're asking for something the receiver might narrate (long agentic work), prompt it for a terse final summary or use plainsend+logs. - The reply is whatever was on screen. It includes any chrome the receiver CLI prints (cursor lines, status hints) — don't expect a clean JSON body unless the prompt asks for one.
- No retries, no delivery confirmation. If the receiver crashed mid- reply you'll get a partial slice or a timeout, nothing in between.
Delegating a request that came in over a channel
If a user pings you on a Telegram/Discord chat where the target agent's bot is also a member, do not relay the answer yourself. Hand the target agent the chat context and tell it to post directly via its own bot — attribution stays clean, the conversation reads naturally, and you stop being a middleman.
The CLI has structural support for this: --reply-to-chat=<id> (and
optional --reply-to-msg=<id> for thread replies) stamps the envelope so
the receiver gets a machine-readable hint instead of relying on you
describing the chat in prose.
Where the chat_id and message_id come from. When the user's request
arrives via the channel plugin (Telegram or Discord), it's surfaced to you
wrapped in a <channel> tag whose attributes already carry exactly what
the flags want:
<channel source="plugin:telegram:telegram" chat_id="433634012" message_id="4671" user="..." ts="...">
redirect to marketing
</channel>
The mapping is one-for-one:
chat_idattribute →--reply-to-chat=<chat_id>message_idattribute →--reply-to-msg=<message_id>(optional; threads the reply)
So the handoff looks like:
sudo 5dive agent send marketing \
--reply-to-chat=433634012 --reply-to-msg=4671 \
"User @alice asked your take on the Q3 launch copy. Reply in the chat
via your own bot — do not reply back to me."
Receiver-side, the inbound envelope looks like:
[5dive-msg from=ops id=ab12cd34 reply-to-chat=433634012 reply-to-msg=4671] ...
When you see reply-to-chat=<id> on an incoming message, post your answer
directly in that chat via your own Telegram/Discord tool. Use
reply-to-msg=<id> as the threaded reply_to so the message lands as a
quote-reply. Do not also send a peer reply back to the sender — they have
opted out of being a relay.
If the target agent's bot is not in the chat, omit the flag, relay the reply yourself, and tell the user the bot needs to be added.
Rules of thumb
- For "fire-and-forget delegate, I'll check later":
agent send+ pollagent logs --tmuxwhen it suits you. - For "I need an answer to continue":
agent ask. - For broadcast / fan-out across N agents: loop
agent send(oragent askin parallel via&+wait). Each call is independent. - Don't reuse
--fromlabels for unrelated agents — pick a label that names you, so receivers can address replies correctly. - When a request originates from a chat the target agent can post to, prefer direct reply over relay (see above).
Diagnose a sick host
sudo 5dive doctor --json
Envelope is always { ok: true, data: { summary, checks } } with exit 0.
Branch on data.summary.errors > 0. Add --repair to attempt reversible
fixes (apt installs, type installer recipes, registry reseed).
Rules of engagement
- Always pass
--json. Parse the envelope. Don't grep stderr. - One name = one agent. Names are lowercase letters/digits/hyphens,
start with a letter, max 16 chars. Reuse a name only after
agent rm. - Don't share bot tokens. Two Telegram-channel agents on the same
bot will race each other on
getUpdates. Each agent needs its own. - Tear down what you spin up. A leaked
worker-Nagent stays running across reboots — it's a real systemd unit, not a thread. On task completion call5dive agent rm <name>. - Don't shell out to the underlying CLI binaries directly. Going
around
5diveskips the systemd unit, the audit log, and the env injection — the agent will run with broken auth and no restart loop. - Read
5dive --helpif a flag is rejected as unknown — the binary on the host may be newer or older than this skill. The help output is authoritative. - The
auth login <type>path is interactive only. Never call it from your own session. - When delegating a chat request, don't relay — hand off context.
If a user pings you in a Telegram/Discord chat that another agent's
bot also belongs to and asks you to involve that agent, use
agent send --reply-to-chat=<id> --reply-to-msg=<id>(values come straight from the inbound<channel>tag's attributes). The target replies directly in the chat from its own bot — relaying through you adds latency, breaks attribution, and makes the user re-read your paraphrase of the answer.
Reference
references/commands.md— every subcommand and flag, copy/pasteable.references/exit-codes.md— exit codes & error classes.references/paths.md— on-disk state layout (only for debugging).
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.
Version History
- e0220ca Current 2026-07-05 21:22
