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
buzz in this agent's inbox. This
agent answers with amq reply --id <id>, and that reply is shown there. A reply with --kind status shows 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 run brew install avivsinai/tap/amq, then stop.
Connect.
- Default: run
amq-remote attach --self --json. It uses AM_ROOT and
AM_ME. If it says this session is not an AMQ participant, offer
--native.
--native: use $AM_ROOT when set, else $HOME/.amq/remote/root
(create it private with (umask 077 && mkdir -p "$HOME/.amq/remote/root")). Run
amq-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.json when set);
it always exits 0, and
amq-remote claude uninstall-stop-hook removes it. Ask once, run it,
then run the attach again.
- Any other failure: show its message and stop.
Tell the owner only what is still needed. The JSON has name,
label, agent, helper, machine, draft, reused, agent_name
when the session has its own agent, machine_name when there is a
machine agent, and, when the machine agent serves the session, channel,
channel_name, and channel_error and channel_retry when the channel
is uncertain or failed, and approval_reviewer when a Codex thread runs
Codex's automatic approvals reviewer. A machine agent that runs inside
amq-remote serve adds machine_host
(standalone), machine_refusal while serve refuses it, and
machine_line while 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:
agent is running: "DM in Buzz." Nothing else is
needed.
agent is idle: "DM 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).
machine is running and channel is active: "Open the
channel in Buzz." Nothing else is needed.
machine_host is standalone, machine is running and channel is
creating: "AMQ Remote is making the channel; it appears in Buzz within
a minute."
machine is running and channel is creating: "Buzz is making the
channel; it appears within a minute."
machine is not missing and the JSON has unproven: "The machine
agent makes a channel only for a session proven live, and this session
is not ()."
machine is offline or idle and channel is uncertain or
failed: "This machine's AMQ Remote agent is not running," then the
setup under machine is missing below.
channel is uncertain: "Buzz did not confirm the channel
(). AMQ keeps looking for it and will not make a second
one. If it never appears, run amq-remote channel reset <name>."
channel is failed: show channel_error, then "AMQ tries again in 10
minutes" when channel_retry is true, else "Run
amq-remote channel reset <name>."
channel is suspended: "This session's channel is suspended
(). Undo it in Buzz, or run amq-remote channel reset <name> for a new channel."
agent is offline and machine is missing: use the setup below.
machine is missing: 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.
machine is offline or idle: "This machine's AMQ Remote agent is
not running." Then the same one-time setup.
If the JSON has warning, show it too. If it has approval_reviewer,
say: "Buzz gets no Codex approvals: Codex's automatic reviewer answers
them (approvals_reviewer = )." It is the owner's
setting; do not change it.
Claude Code only: the approval hook (default and --native, after
a successful attach). Read approval_hook from the attach JSON: ok,
missing, stale, disabled or unreadable. An older amq-remote
gives no approval_hook: then run amq-remote doctor --json and use its
hooks row for this session's settings file (approval: installed
is ok, missing is missing; approval_form stale is stale), or
with an even older doctor treat a native_capability failure that names
the PermissionRequest hook as missing and anything else as ok.
ok: nothing to do.
disabled: say that this session's Claude settings set
disableAllHooks, 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 that
amq-remote doctor names it and the reason.
stale: say the installed hook is an older form, then run
amq-remote claude install-approval-hook, which replaces only that
entry. You may offer amq-remote doctor --fix as 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, and amq-remote claude uninstall-approval-hook
removes the hook." Ask once, then run
amq-remote claude install-approval-hook.
Codex needs no hook: its approvals reach Buzz only for a session on the
Codex app-server (the --native Codex path below); a plain codex TUI
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 off there, 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 plain
codex TUI 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.
1---2name: amq-remote3version: 0.152.0 # x-release-please-version4description: Let 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).5metadata:6 source: https://skillmd.com/skills/avivsinai/amq-remote7 short-description: Reach this agent from Buzz8 compatibility: claude-code, codex-cli9---1011# AMQ Remote1213`/amq-remote` gives this session its own private Buzz channel. One machine14agent per machine runs inside `amq-remote serve`; an owner-signed grant15configures it once. The owner reads and writes in the Buzz app. Several16sessions can be connected at once; each has its own channel. The same session connecting again gets17its own channel back. A resumed session gets its channel back by itself18unless the owner turned it off: a pi session within about 35 s; on macOS, a19Claude mailbox seat started directly by `amq coop exec claude` within about2035 s; any other Claude session at its first approval dialog. A Codex session21needs `$amq-remote` again. A different session never gets another22session's channel. A session that already has its own Buzz agent keeps its DM.2324In Codex the skill is invoked as `$amq-remote` (Codex does not register `/`25commands for skills); the commands below are the same. Codex runs sandboxed:26attach writes `~/.amq/remote`, so the first attach may be refused until the27user reruns it with approval — ask for that one approval, do not work around28it.2930- **Default (AMQ mailbox).** Each message the owner writes in the channel31 (or DM) arrives as an AMQ message from `buzz` in this agent's inbox. This32 agent answers with `amq reply --id <id>`, and that reply is shown there. A reply with `--kind status` shows as progress;33 any other reply is the final answer. No Stop hook and no wake are needed.34 Noticing the message is this agent's own business (a wake, a built-in35 consumer, monitor, or the next drain).36- **`--native`.** For a session that is not on AMQ: each message is typed37 into this exact conversation, and the harness's own final answer goes back.38 On Claude Code it needs the AMQ Stop hook.3940Run the steps in order. When a step says to stop, show the user the41command's own message. Do not work around a refusal.4243## `/amq-remote` (connect)44451. **Tools.** Run `command -v amq-remote`. If it is missing, tell46 the user to run `brew install avivsinai/tap/amq`, then stop.472. **Connect.**48 - Default: run `amq-remote attach --self --json`. It uses `AM_ROOT` and49 `AM_ME`. If it says this session is not an AMQ participant, offer50 `--native`.51 - `--native`: use `$AM_ROOT` when set, else `$HOME/.amq/remote/root`52 (create it private with `(umask 077 && mkdir -p "$HOME/.amq/remote/root")`). Run53 `amq-remote attach --self --native --root "$ROOT" --json`.54 - If it exits 6 and names `amq-remote claude install-stop-hook` (Claude55 Code with `--native`), tell the user this adds one Stop hook to56 `~/.claude/settings.json` (`$CLAUDE_CONFIG_DIR/settings.json` when set);57 it always exits 0, and58 `amq-remote claude uninstall-stop-hook` removes it. Ask once, run it,59 then run the attach again.60 - Any other failure: show its message and stop.613. **Tell the owner only what is still needed.** The JSON has `name`,62 `label`, `agent`, `helper`, `machine`, `draft`, `reused`, `agent_name`63 when the session has its own agent, `machine_name` when there is a64 machine agent, and, when the machine agent serves the session, `channel`,65 `channel_name`, and `channel_error` and `channel_retry` when the channel66 is uncertain or failed, and `approval_reviewer` when a Codex thread runs67 Codex's automatic approvals reviewer. A machine agent that runs inside68 `amq-remote serve` adds `machine_host`69 (`standalone`), `machine_refusal` while serve refuses it, and70 `machine_line` while it does not serve. Attach already waited up to 15 s71 for the channel.72 Say "Connected: <label>." and then exactly one of, the first that applies:73 - `agent` is `running`: "DM **<agent_name>** in Buzz." Nothing else is74 needed.75 - `agent` is `idle`: "DM **<agent_name>** in Buzz; Buzz starts it on the76 next message."77 - The JSON has `machine_line`: show it as it is (it says the machine agent78 runs inside amq-remote serve and is not running, with the next step).79 - `machine` is `running` and `channel` is `active`: "Open the80 **<channel_name>** channel in Buzz." Nothing else is needed.81 - `machine_host` is `standalone`, `machine` is `running` and `channel` is82 `creating`: "AMQ Remote is making the channel; it appears in Buzz within83 a minute."84 - `machine` is `running` and `channel` is `creating`: "Buzz is making the85 channel; it appears within a minute."86 - `machine` is not `missing` and the JSON has `unproven`: "The machine87 agent makes a channel only for a session proven live, and this session88 is not (<unproven>)."89 - `machine` is `offline` or `idle` and `channel` is `uncertain` or90 `failed`: "This machine's AMQ Remote agent is not running," then the91 setup under `machine` is `missing` below.92 - `channel` is `uncertain`: "Buzz did not confirm the channel93 (<channel_error>). AMQ keeps looking for it and will not make a second94 one. If it never appears, run `amq-remote channel reset <name>`."95 - `channel` is `failed`: show `channel_error`, then "AMQ tries again in 1096 minutes" when `channel_retry` is true, else "Run97 `amq-remote channel reset <name>`."98 - `channel` is `suspended`: "This session's channel is suspended99 (<channel_error>). Undo it in Buzz, or run `amq-remote channel reset100 <name>` for a new channel."101 - `agent` is `offline` and `machine` is `missing`: use the setup below.102 - `machine` is `missing`: this machine's one-time setup (no enrolled103 machine key):104 1. Run `amq-remote machine request > request.txt`.105 2. The owner runs `amq-owner-sign --machine request.txt --out grant.json106 --relay <wss-url>` in their own terminal. Only the owner runs this107 signing step; never run it for them.108 3. Run `amq-remote machine enroll --grant grant.json`.109 4. Run `amq-remote service install`; it starts the agent now and at each login.110 Every later session then gets its channel by itself.111 - `machine` is `offline` or `idle`: "This machine's AMQ Remote agent is112 not running." Then the same one-time setup.113 If the JSON has `warning`, show it too. If it has `approval_reviewer`,114 say: "Buzz gets no Codex approvals: Codex's automatic reviewer answers115 them (approvals_reviewer = <approval_reviewer>)." It is the owner's116 setting; do not change it.1174. **Claude Code only: the approval hook** (default and `--native`, after118 a successful attach). Read `approval_hook` from the attach JSON: `ok`,119 `missing`, `stale`, `disabled` or `unreadable`. An older amq-remote120 gives no `approval_hook`: then run `amq-remote doctor --json` and use its121 `hooks` row for this session's settings file (`approval`: `installed`122 is `ok`, `missing` is `missing`; `approval_form` `stale` is `stale`), or123 with an even older doctor treat a `native_capability` failure that names124 the PermissionRequest hook as `missing` and anything else as `ok`.125 - `ok`: nothing to do.126 - `disabled`: say that this session's Claude settings set127 `disableAllHooks`, so approvals stay in the terminal unless a project128 or managed setting turns hooks on.129 - `unreadable`: say that the Claude settings file cannot be read, and that130 `amq-remote doctor` names it and the reason.131 - `stale`: say the installed hook is an older form, then run132 `amq-remote claude install-approval-hook`, which replaces only that133 entry. You may offer `amq-remote doctor --fix` as a question (it also134 installs the other hooks and the login service); never run it without a yes.135 - `missing`: tell the user: "This adds one approval hook. The first136 approval dialog of each Claude Code session on this machine connects137 that session to its own Buzz channel, even one that never ran138 /amq-remote: an AMQ session gets its own binding (the mailbox one139 /amq-remote writes), any other session a native binding, where chat140 needs /amq-remote --native. Every dialog of the session then shows141 there; ✅ allows, ❌ denies, first answer wins. /amq-remote off stops it142 for that session, and `amq-remote claude uninstall-approval-hook`143 removes the hook." Ask once, then run144 `amq-remote claude install-approval-hook`.145146 Codex needs no hook: its approvals reach Buzz only for a session on the147 Codex app-server (the `--native` Codex path below); a plain `codex` TUI148 session answers approvals in the terminal.1495. Add one line for the carrier:150 - Default: "Buzz messages arrive in this agent's AMQ inbox. Stop in Buzz151 stops waiting; a delivered message may still be acted on."152 - Claude in mailbox mode: "In Buzz, a line starting with / is typed into153 the session like Remote Control; it waits while a dialog is open."154 - `--native`: "A message sent while this session is busy waits. Buzz Stop155 cannot interrupt a Claude turn."156 - Claude with the hook installed: "Every approval dialog of this session157 shows in its Buzz channel with its options. ✅ or ❌, or a reply with the option158 number, answers it. A question with one single-select question shows159 its choices; reply with the number or your own text. The first answer,160 in Buzz or in the terminal, wins."161 - Claude in a machine agent channel: "The channel also shows each turn this162 session finishes; type `mirror off` there, or run `/amq-remote mirror163 off`, to stop it."164 - Codex on the app-server: the same line, unless the JSON has165 `approval_reviewer` (then the reviewer line above replaces it). A plain166 `codex` TUI session: "Approvals stay in the terminal."167168Codex with `--native`: attach needs `CODEX_THREAD_ID` and a thread loaded in169the Codex app-server daemon. A session started with plain `codex` is not in170the daemon; start it with `codex app-server daemon start`, then171`codex --remote unix://`. Run `amq-remote` and `amq-acp` outside Codex's172sandbox (request escalation): the sandbox blocks the daemon socket.173174## Answering a Buzz message (default mailbox)175176A message from `buzz` with subject "Buzz DM" is the owner writing from Buzz,177in this session's channel or its agent's DM.178Do the work, then answer with `amq reply --id <that message id>`. Use179`--kind status` for an interim update. Keep the final answer short; it is180read in a chat.181182An image the owner sent arrives as a line `[image: <absolute path>]`: open183that file to see it. `[image not attached: <reason>]` means the image did not184arrive; say so in the answer and ask the owner to send it again if it matters.185186## `/amq-remote off`187188Run `amq-remote detach --self` and show its output. The session keeps189running. Its channel stops taking messages now, and the machine agent then190archives it; a session with its own agent has that agent archive itself, and191its DM answers "Not connected". When this session connects again, the same192channel or agent comes back.193194## `/amq-remote mirror on|off|status`195196Run `amq-remote mirror <on|off|status> --self` and show its output. It is197the same switch as typing `mirror on` or `mirror off` in the session's198channel: while it is off, the machine agent posts no turn of this session,199and turns that end while it is off are not posted later. Only a Claude,200Codex or pi session the machine agent serves has a mirror.201202## `/amq-remote status`203204Run `amq-remote bindings` and show its output. It lists the machine agent205and each connected session as `live` or `unknown` with its own agent206(`running`, `idle`, `offline` or `missing`) and its channel, prunes the207sessions proven ended, and names, once, old per-session agents the owner208should delete in Buzz.209210## Status line211212`amq-remote statusline` prints `📡 buzz` while this session is connected,213`📡 buzz (mirror off)` while its mirror is off, and nothing otherwise. It214always exits 0, reads only the binding files, and `--plain` drops the emoji.215AMQ never edits the user's `statusLine` setting; if the user asks for it,216show them the line to add to their own Claude Code status-line script, where217`$input` holds the JSON the script read from stdin:218219```bash220seg=$(amq-remote statusline <<<"$input" 2>/dev/null); [ -n "$seg" ] && out+=" | $seg"221```222223Any other harness that runs a command in its status line passes the session224id: `amq-remote statusline --session <id>`.225226## Trust limits227228The machine agent's key is in `~/.amq/remote/machine/`. The owner's229grant lets that key act as the owner's Buzz agent for every event kind230until its signed end date. A copied key and grant stay valid until that date; only231removing the agent's access on the relay ends them earlier.232See the233[Machine agent](https://github.com/avivsinai/agent-message-queue/blob/main/cmd/amq-remote/README.md#machine-agent).