amq-remote
Let the owner reach this running agent from Buzz, on the phone or in Buzz Desktop. Use when the user types /amq-remote (Claude Code) or $amq-remote (Codex), /amq-remote --native, /amq-remote off, or /amq-remote status, or asks to control this session from Buzz. Not for AMQ messaging between agents (use amq-cli).
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- amq-remote
- version
- 0.143.0
- metadata
- { "compatibility": "claude-code, codex-cli", "short-description": "Reach this agent from Buzz" }
- description
- Let the owner reach this running agent from Buzz, on the phone or in Buzz Desktop. Use when the user types /amq-remote (Claude Code) or $amq-remote (Codex), /amq-remote --native, /amq-remote off, or /amq-remote status, or asks to control this session from Buzz. Not for AMQ messaging between agents (use amq-cli).
03 SKILL.md 正文
AMQ Remote
/amq-remote gives this session its own private Buzz channel. One Buzz
agent per machine, "AMQ Remote @ <machine>", imported once, makes the
channel, adds the owner and mentions them. The owner writes in that channel
from the Buzz phone app or Buzz Desktop. Several sessions can be connected
at once; each has its own channel. The same session connecting again gets
its own channel back. A resumed session gets its channel back by itself
unless the owner turned it off: a pi session within about 35 s; on macOS, a
Claude mailbox seat started directly by amq coop exec claude within about
35 s; any other Claude session at its first approval dialog. A Codex session
needs $amq-remote again. A different session never gets another
session's channel. A session that already has its own Buzz agent keeps its DM.
In Codex the skill is invoked as $amq-remote (Codex does not register /
commands for skills); the commands below are the same. Codex runs sandboxed:
attach writes ~/.amq/remote, so the first attach may be refused until the
user reruns it with approval — ask for that one approval, do not work around
it.
- Default (AMQ mailbox). Each message the owner writes in the channel
(or DM) arrives as an AMQ message from
buzzin this agent's inbox. This agent answers withamq reply --id <id>, and that reply is shown there. A reply with--kind statusshows as progress; any other reply is the final answer. No Stop hook and no wake are needed. Noticing the message is this agent's own business (a wake, a built-in consumer, monitor, or the next drain). --native. For a session that is not on AMQ: each message is typed into this exact conversation, and the harness's own final answer goes back. On Claude Code it needs the AMQ Stop hook.
Run the steps in order. When a step says to stop, show the user the command's own message. Do not work around a refusal.
/amq-remote (connect)
-
Tools. Run
command -v amq-remote amq-acp. If either is missing, tell the user to runbrew install avivsinai/tap/amq, then stop. -
Connect.
- Default: run
amq-remote attach --self --json. It usesAM_ROOTandAM_ME. If it says this session is not an AMQ participant, offer--native. --native: use$AM_ROOTwhen set, else$HOME/.amq/remote/root(create it private with(umask 077 && mkdir -p "$HOME/.amq/remote/root")). Runamq-remote attach --self --native --root "$ROOT" --json.- If it exits 6 and names
amq-remote claude install-stop-hook(Claude Code with--native), tell the user this adds one Stop hook to~/.claude/settings.json($CLAUDE_CONFIG_DIR/settings.jsonwhen set); it always exits 0, andamq-remote claude uninstall-stop-hookremoves it. Ask once, run it, then run the attach again. - Any other failure: show its message and stop.
- Default: run
-
Tell the owner only what is still needed. The JSON has
name,label,agent,helper,machine,draft,reused,agent_namewhen the session has its own agent,machine_namewhen there is a machine agent, and, when the machine agent serves the session,channel,channel_name, andchannel_errorandchannel_retrywhen the channel is uncertain or failed, andapproval_reviewerwhen a Codex thread runs Codex's automatic approvals reviewer. Attach already waited up to 15 s for the channel. Say "Connected: <label>." and then exactly one of, the first that applies:agentisrunning: "DM <agent_name> in Buzz." Nothing else is needed.agentisidle: "DM <agent_name> in Buzz; Buzz starts it on the next message."machineisrunningandchannelisactive: "Open the <channel_name> channel in Buzz." Nothing else is needed.machineisrunningandchanneliscreating: "Buzz is making the channel; it appears within a minute."machineis notmissingand the JSON hasunproven: "The machine agent makes a channel only for a session proven live, and this session is not (<unproven>)."machineisofflineoridleandchannelisuncertainorfailed: "Start <machine_name> in Buzz Desktop (Agents, the agent, Start)." Then show the channel state andchannel_error, and say that nothing is done about it while the machine agent is stopped.channelisuncertain: "Buzz did not confirm the channel (<channel_error>). AMQ keeps looking for it and will not make a second one. If it never appears, runamq-remote channel reset <name>."channelisfailed: showchannel_error, then "AMQ tries again in 10 minutes" whenchannel_retryis true, else "Runamq-remote channel reset <name>."agentisofflineandmachineismissing: "DM <agent_name> first; if it does not answer within a minute, start it in Buzz Desktop (Agents, the agent, Start)."machineismissing: this machine's one-time setup. Runamq-acp setup --machine --out "$HOME/Downloads/AMQ Remote machine.agent.json"once, and show its printed steps as they are (Buzz Desktop: Agents, then + then Import, pick that file, then Start, and turn on Auto-start). Every later session then gets its channel by itself.machineisofflineoridle: "Start <machine_name> in Buzz Desktop (Agents, the agent, Start); it then makes this session's channel." If the JSON haswarning, show it too. If it hasapproval_reviewer, say: "Buzz gets no Codex approvals: Codex's automatic reviewer answers them (approvals_reviewer = <approval_reviewer>)." It is the owner's setting; do not change it.
-
Claude Code only: the approval hook (default and
--native, after a successful attach). Readapproval_hookfrom the attach JSON:ok,missing,stale,disabledorunreadable. An older amq-remote gives noapproval_hook: then runamq-remote doctor --jsonand use itshooksrow for this session's settings file (approval:installedisok,missingismissing;approval_formstaleisstale), or with an even older doctor treat anative_capabilityfailure that names the PermissionRequest hook asmissingand anything else asok.ok: nothing to do.disabled: say that this session's Claude settings setdisableAllHooks, so approvals stay in the terminal unless a project or managed setting turns hooks on.unreadable: say that the Claude settings file cannot be read, and thatamq-remote doctornames it and the reason.stale: say the installed hook is an older form, then runamq-remote claude install-approval-hook, which replaces only that entry. You may offeramq-remote doctor --fixas a question (it also installs the other hooks, the login service and the machine agent's import file); never run it without a yes.missing: tell the user: "This adds one approval hook. The first approval dialog of each Claude Code session on this machine connects that session to its own Buzz channel, even one that never ran /amq-remote: an AMQ session gets its own binding (the mailbox one /amq-remote writes), any other session a native binding, where chat needs /amq-remote --native. Every dialog of the session then shows there; ✅ allows, ❌ denies, first answer wins. /amq-remote off stops it for that session, andamq-remote claude uninstall-approval-hookremoves the hook." Ask once, then runamq-remote claude install-approval-hook.
Codex needs no hook: its approvals reach Buzz only for a session on the Codex app-server (the
--nativeCodex path below); a plaincodexTUI session answers approvals in the terminal. -
Add one line for the carrier:
- Default: "Buzz messages arrive in this agent's AMQ inbox. Stop in Buzz stops waiting; a delivered message may still be acted on."
- Claude in mailbox mode: "In Buzz, a line starting with / is typed into the session like Remote Control; it waits while a dialog is open."
--native: "A message sent while this session is busy waits. Buzz Stop cannot interrupt a Claude turn."- Claude with the hook installed: "Every approval dialog of this session shows in its Buzz channel with its options. ✅ or ❌, or a reply with the option number, answers it. The first answer, in Buzz or in the terminal, wins."
- Claude in a machine agent channel: "The channel also shows each turn this
session finishes; type
mirror offthere, or run/amq-remote mirror off, to stop it." - Codex on the app-server: the same line, unless the JSON has
approval_reviewer(then the reviewer line above replaces it). A plaincodexTUI session: "Approvals stay in the terminal."
Codex with --native: attach needs CODEX_THREAD_ID and a thread loaded in
the Codex app-server daemon. A session started with plain codex is not in
the daemon; start it with codex app-server daemon start, then
codex --remote unix://. Run amq-remote and amq-acp outside Codex's
sandbox (request escalation): the sandbox blocks the daemon socket, and
amq-acp setup writes files outside the workspace.
Answering a Buzz message (default mailbox)
A message from buzz with subject "Buzz DM" is the owner writing from Buzz,
in this session's channel or its agent's DM.
Do the work, then answer with amq reply --id <that message id>. Use
--kind status for an interim update. Keep the final answer short; it is
read in a chat.
An image the owner sent arrives as a line [image: <absolute path>]: open
that file to see it. [image not attached: <reason>] means the image did not
arrive; say so in the answer and ask the owner to send it again if it matters.
/amq-remote off
Run amq-remote detach --self and show its output. The session keeps
running. Its channel stops taking messages now, and the machine agent then
archives it; a session with its own agent has that agent archive itself, and
its DM answers "Not connected". When this session connects again, the same
channel or agent comes back.
/amq-remote mirror on|off|status
Run amq-remote mirror <on|off|status> --self and show its output. It is
the same switch as typing mirror on or mirror off in the session's
channel: while it is off, the machine agent posts no turn of this session,
and turns that end while it is off are not posted later. Only a Claude,
Codex or pi session the machine agent serves has a mirror.
/amq-remote status
Run amq-remote bindings and show its output. It lists the machine agent
and each connected session as live or unknown with its own agent
(running, idle, offline or missing) and its channel, prunes the
sessions proven ended, and names, once, old per-session agents the owner
should delete in Buzz Desktop.
Status line
amq-remote statusline prints 📡 buzz while this session is connected,
📡 buzz (mirror off) while its mirror is off, and nothing otherwise. It
always exits 0, reads only the binding files, and --plain drops the emoji.
AMQ never edits the user's statusLine setting; if the user asks for it,
show them the line to add to their own Claude Code status-line script, where
$input holds the JSON the script read from stdin:
seg=$(amq-remote statusline <<<"$input" 2>/dev/null); [ -n "$seg" ] && out+=" | $seg"
Any other harness that runs a command in its status line passes the session
id: amq-remote statusline --session <id>.
Trust limits
The Buzz agent's identity belongs to Buzz Desktop. Its grant has no kind limit and no expiry. Archiving the agent does not invalidate a copied key and grant; only removing the agent's relay access does that. Buzz "owner only" also admits the owner's other agents. See the amq-acp README.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.