hashgraph-online/awesome-codex-plugins / plugins/avivsinai/agent-message-queue/skills/amq-remote
amq-remote
UnverifiedLet the owner reach this running agent from the Buzz app, on the phone or a computer. 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).
AMQ Remote
/amq-remote gives this session its own private Buzz channel. One machine
agent per machine runs inside amq-remote serve; an owner-signed grant
configures it once. The owner reads and writes in the Buzz app. 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. If it 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. A machine agent that runs insideamq-remote serveaddsmachine_host(standalone),machine_refusalwhile serve refuses it, andmachine_linewhile it does not serve. Attach already waited up to 15 s for the channel. Say "Connected: ." 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."- The JSON has
machine_line: show it as it is (it says the machine agent runs inside amq-remote serve and is not running, with the next step). machineisrunningandchannelisactive: "Open the <channel_name> channel in Buzz." Nothing else is needed.machine_hostisstandalone,machineisrunningandchanneliscreating: "AMQ Remote is making the channel; it appears in Buzz within a minute."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 ()."machineisofflineoridleandchannelisuncertainorfailed: "This machine's AMQ Remote agent is not running," then the setup undermachineismissingbelow.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>."channelissuspended: "This session's channel is suspended (<channel_error>). Undo it in Buzz, or runamq-remote channel reset <name>for a new channel."agentisofflineandmachineismissing: use the setup below.machineismissing: this machine's one-time setup (no enrolled machine key):- Run
amq-remote machine request > request.txt. - The owner runs
amq-owner-sign --machine request.txt --out grant.json --relay <wss-url>in their own terminal. Only the owner runs this signing step; never run it for them. - Run
amq-remote machine enroll --grant grant.json. - Run
amq-remote service install; it starts the agent now and at each login. Every later session then gets its channel by itself.
- Run
machineisofflineoridle: "This machine's AMQ Remote agent is not running." Then the same one-time setup. 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 and the login service); 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. A question with one single-select question shows its choices; reply with the number or your own text. 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.
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.
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 machine agent's key is in ~/.amq/remote/machine/. The owner's
grant lets that key act as the owner's Buzz agent for every event kind
until its signed end date. A copied key and grant stay valid until that date; only
removing the agent's access on the relay ends them earlier.
See the
Machine agent.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |