From f66b62c551cd931cef1661fba19c69f3982165c9 Mon Sep 17 00:00:00 2001 From: 28allday Date: Sun, 31 May 2026 13:44:38 +0100 Subject: [PATCH] skill: trim baked omarchy-send docs to the live release; drop dead reply plumbing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The installer pulls omarchy-send from its public `main` (live release e66662f), which has headless send (--to/--message/--send-pin/--wait), TUI messaging, and desktop notifications — but NOT the message log, AI auto-reply, agentic mode, or --to-ip/--to-fingerprint reply flags (those are unreleased). The baked SKILL.md and CLAUDE.md were documenting the unreleased features, over-promising on a real install. - SKILL.md: remove the messages.jsonl log section, the AI auto-reply + agentic sections, and the --to-ip/--to-fingerprint examples; keep TUI, headless send, notifications. - CLAUDE.md: drop the JSONL log + auto-reply paragraph; messages show in the TUI Messages tab (no on-disk log). - Installer: remove the ~/.local/bin/omarchy-send-reply generator and the config.json replyCmd seed (live ignores replyCmd; dead plumbing). The ~/.config chown fix goes too — nothing creates ~/.config/~/.local as root during install anymore (OMATERM creates them as the user). Co-Authored-By: Claude Opus 4.8 (1M context) --- omalocal.sh | 187 +++++----------------------------------------------- 1 file changed, 16 insertions(+), 171 deletions(-) diff --git a/omalocal.sh b/omalocal.sh index ec54921..aa16298 100755 --- a/omalocal.sh +++ b/omalocal.sh @@ -857,98 +857,24 @@ headless box — ideal for pinging your desktop or phone from the server: omarchy-send --to "" --message "backup finished" omarchy-send --to "Slate Starburst" --message "deploy done" --wait 20s # peer-discovery timeout (default 15s) omarchy-send --to "" --message "hi" --send-pin 2468 # if the target requires a PIN -omarchy-send --to-ip 192.168.1.40 --message "on it" # reply straight to an IP (no discovery wait) -omarchy-send --to-fingerprint AB12… --message "on it" # reply to a stable fingerprint (robust) ``` Matches the target by display name (case-insensitive), discovers it over multicast (waits up to `--wait`), sends, prints a one-line result, and exits non-zero if the peer isn't found or the send fails. Discovery-only — it doesn't bind the receiver port, so it's safe to run while the TUI is also up. File -sending stays in the TUI for now. To reply to someone who messaged you, prefer -`--to-ip`/`--to-fingerprint` with the values from the message log (below) — -aliases aren't unique and can change. +sending stays in the TUI for now. -### Reading messages people send you (where an agent looks) +### Reading messages people send you -Two places: - -- **The Messages tab** in the TUI (interactive). -- **The message log** — a JSON Lines file at - **`~/.local/state/omarchy-send/messages.jsonl`** (honours `XDG_STATE_HOME`). - This is where a script/agent should look. One JSON object per received message - *or* file, appended and `fsync`'d the instant it arrives, recording **who** sent - it — not just the text: - - ```json - {"ts":"2026-05-30T10:42:01Z","dir":"in","type":"message","id":"01J…", - "text":"are the movies up?","from_alias":"Slate Starburst", - "from_fingerprint":"AB12…","from_ip":"192.168.1.40", - "device_model":"pixel","device_type":"mobile"} - ``` - - Files appear as `"type":"file"` with `filename`/`size`; the file bytes land in - `~/Omarchy-Send/`. To consume: `tail -F ~/.local/state/omarchy-send/messages.jsonl`, - filter `type=="message"`, dedupe by `id` (sortable by time), and reply with - `omarchy-send --to-ip --message "…"`. +- **The Messages tab** in the TUI shows messages people have sent you (interactive). +- **Files** anyone sends land in **`~/Omarchy-Send/`**. > **The receiver only runs while the TUI is open.** omarchy-send has NO background -> daemon: it receives, logs, and can be replied-to **only while `omarchy-send` is -> running in a terminal** (e.g. under `tmux new -s oms 'omarchy-send'`). When the -> TUI is closed, nothing is received and the log does not grow — treat "TUI not -> running" as "offline, nothing to do". - -### Auto-reply to messages (opt-in, AI-powered) - -omarchy-send has a built-in **AI auto-reply** toggle. Open the TUI, go to the -**Settings** tab, and press **`r`** to turn it on (the row shows `on`). While it's -on, each incoming message is answered by the local `claude` CLI and the reply is -sent back to the sender automatically. Run the TUI under tmux so it persists: - -```bash -tmux new -s oms 'omarchy-send' # then: Settings tab → press r to enable AI auto-reply -``` - -How it works: a reply *generator* (`~/.local/bin/omarchy-send-reply`, pre-seeded -as the config's `replyCmd`) gets the message in `OMARCHY_MSG_*` env and prints a -reply; omarchy-send sends it. It is: - -- **A runtime toggle** — flip it in Settings (`r`); the state persists in config. - Plain receiving (toggle off) never auto-replies. -- **Reply-only by default** — the generator gives the model no tools, so an - unauthenticated LAN sender can't make this box do anything but emit a text reply. -- **Tied to the TUI** — auto-reply (like all receiving) happens only while the TUI - is open; quit it (`q`) and the box stops replying. No background daemon. - -Requires the `claude` CLI installed and authenticated for this user (omaterm -installs it; run `claude` once interactively to log in). The generator resolves -`claude` from PATH or `mise`. - -#### Agentic mode (the AI can run commands — PIN-gated) - -A second Settings toggle, **`g`**, switches on **agentic** mode: the AI may use -its tools to *act* on this box (run commands, deploy, inspect) in response to a -message, then reply with the result. It is **off by default**. - -- Because this is **remote command execution driven by LAN messages**, omarchy-send - only lets you enable it **while a PIN is set** (`e` to set one). The PIN gates who - can trigger it — only senders who know it can message the box. Enabling agentic - also turns AI auto-reply on; clearing the PIN turns agentic back off. -- Keep it to a **trusted LAN**; never expose port 53317 to the internet. -- Internally, omarchy-send sets `OMARCHY_AGENTIC=1` so the generator runs `claude` - with its tools; otherwise it stays reply-only. - -> Don't enable AI auto-reply on two boxes pointed at each other — each would -> reply to the other's reply forever. Phones / desktops running plain LocalSend -> don't auto-reply, so messaging with them is fine. - -**If a user asks you (the AI) to "monitor and reply to messages": tell them to -enable AI auto-reply in the Settings tab** (or, if asked, `omarchy-send` with -`AutoReply` set). That is the supported mechanism and it switches off cleanly when -the TUI closes. Do NOT build a polling loop, a `tail -F` watcher, or a background -process to do it yourself — those miss messages in bursts, outlive their purpose, -and contradict the TUI-only model. (For a brief, supervised look within your own -session you may tail the JSON Lines log and stop when the user is done.) +> daemon: it receives **only while `omarchy-send` is running in a terminal** (e.g. +> under `tmux new -s oms 'omarchy-send'`). When the TUI is closed, nothing is +> received — treat "TUI not running" as "offline, nothing to do". Don't build a +> polling loop or background watcher to receive messages — there's nothing to tail. ### Desktop notifications @@ -1108,35 +1034,26 @@ Firewall already opens **53317/tcp+udp**. - **Files** anyone sends land in **`~/Omarchy-Send/`** (sub-folder structure preserved) — first place to look for files a user "just sent over". -- **Messages** are appended to **`~/.local/state/omarchy-send/messages.jsonl`** - (JSON Lines, one object per message/file, with sender `from_ip`/`from_fingerprint`) - — that's where to look for messages, and where an agent should tail. +- **Messages** show in the **Messages tab** of the TUI (there is no on-disk + message log; receiving happens only while the TUI is open). ```bash -ls -la ~/Omarchy-Send/ # received files -tail -n 20 ~/.local/state/omarchy-send/messages.jsonl # received messages (and file events) -omarchy-send # open the TUI (Devices / Transfers / Messages / Manage / Settings) +ls -la ~/Omarchy-Send/ # received files +omarchy-send # open the TUI (Devices / Transfers / Messages / Manage / Settings) ``` -**Critical:** there is NO background receiver — omarchy-send only receives, -logs, and is reachable **while the TUI is running** (e.g. `tmux new -s oms -'omarchy-send'`). If it isn't open, nothing arrives and the log doesn't grow. +**Critical:** there is NO background receiver — omarchy-send only receives and is +reachable **while the TUI is running** (e.g. `tmux new -s oms 'omarchy-send'`). If +it isn't open, nothing arrives. The TUI needs a real TTY — over SSH that means an interactive session (or `ssh -tt user@host omarchy-send`). To send a one-off message with NO TTY (from -a script/cron on this headless box — e.g. ping a desktop/phone), or to reply to -a logged sender, use headless send: +a script/cron on this headless box — e.g. ping a desktop/phone), use headless send: ```bash omarchy-send --to "" --message "backup finished" # also --send-pin, --wait; file send stays TUI-only -omarchy-send --to-ip --message "on it" # reply to a sender from the message log ``` -To **auto-reply** to incoming messages, open `omarchy-send`, go to the Settings -tab and press `r` (built-in AI auto-reply, reply-only, live only while the TUI is -open). If a user asks you to "monitor and reply to messages", enable that toggle; -do NOT build a poll-loop, `tail -F` watcher, or background daemon to do it. - If install was skipped, run: ```bash @@ -1154,78 +1071,6 @@ CLAUDE_MD arch-chroot /mnt chown -R "$USERNAME:$USERNAME" "/home/$USERNAME/.claude" -# ---------------------------------------------- omarchy-send AI auto-reply ---- -# omarchy-send has a built-in "AI auto-reply" toggle (Settings tab → `r`): when -# on, it runs the configured ReplyCmd for each received message and sends the -# printed reply back to the sender. We ship a reply *generator* script and point -# ReplyCmd at it, so the user only has to flip the switch. The generator only -# prints text (omarchy-send does the sending) and gives the model no tools, so a -# LAN message can't make this box take any action. Auto-reply runs only while -# the TUI is open — close it and it stops. -echo "==> Installing omarchy-send AI reply generator for $USERNAME..." -install -d -m 755 "/mnt/home/$USERNAME/.local/bin" - -cat > "/mnt/home/$USERNAME/.local/bin/omarchy-send-reply" <<'OMS_REPLY' -#!/usr/bin/env bash -# omarchy-send-reply — reply generator for omarchy-send's AI auto-reply toggle. -# omarchy-send runs this for each received message (message in OMARCHY_MSG_* env) -# and sends whatever we print on stdout back to the sender. It does no sending -# itself. Two modes, chosen by omarchy-send via OMARCHY_AGENTIC: -# unset/0 — reply-only: no tools, the model can only emit text (safe default). -# 1 — agentic: the model may use its tools to ACT on this box, then -# report. omarchy-send only sets this when agentic mode is enabled in -# Settings, which it gates on a PIN — so only senders who know the PIN -# can reach this path. Still: this is remote command execution. -set -uo pipefail - -text="${OMARCHY_MSG_TEXT:-}" -who="${OMARCHY_MSG_FROM_ALIAS:-a device}" -[ -n "$text" ] || exit 0 - -# Resolve the AI CLI: PATH first, then mise (omaterm installs agents as mise -# tools, whose shims aren't on a non-interactive PATH). -if command -v claude >/dev/null 2>&1; then - ai=(claude) -elif command -v mise >/dev/null 2>&1 && mise which claude >/dev/null 2>&1; then - ai=(mise exec -- claude) -else - exit 0 # no AI available; omarchy-send logs the empty reply and skips the send -fi - -# --permission-mode bypassPermissions never blocks on the first-run folder-trust -# prompt (there's no TTY to answer it). -if [ "${OMARCHY_AGENTIC:-0}" = "1" ]; then - prompt="You are an assistant running on a LAN server. \"$who\" sent: \"$text\". Do what they ask using your tools, then reply with a brief plain-text summary of what you did or found. Output only that summary." - "${ai[@]}" -p "$prompt" --permission-mode bypassPermissions 2>/dev/null \ - | tr -d '\000' | head -c 2000 -else - # --tools "" → no tools, so the model can ONLY emit text. - prompt="You are an automatic responder for a LAN file-transfer tool. \"$who\" sent: \"$text\". Reply in one or two short, friendly plain-text sentences. Output only the reply." - "${ai[@]}" -p "$prompt" --tools "" --permission-mode bypassPermissions 2>/dev/null \ - | tr -d '\000' | head -c 1000 -fi -OMS_REPLY - -arch-chroot /mnt chmod 755 "/home/$USERNAME/.local/bin/omarchy-send-reply" - -# Seed omarchy-send's config with ReplyCmd pointing at the generator (via $HOME, -# expanded at run time, so no username is baked in). omarchy-send fills the rest -# of the config — alias, TLS identity, etc. — on first run and preserves this. -# AutoReply stays off until the user turns it on in Settings. -install -d -m 755 "/mnt/home/$USERNAME/.config/omarchy-send" -cat > "/mnt/home/$USERNAME/.config/omarchy-send/config.json" <<'OMS_CONFIG' -{ - "replyCmd": "$HOME/.local/bin/omarchy-send-reply" -} -OMS_CONFIG -arch-chroot /mnt chmod 600 "/home/$USERNAME/.config/omarchy-send/config.json" -# chown the WHOLE ~/.config (not just .config/omarchy-send): the host-side -# `install -d` above created the ~/.config PARENT as root, and a -R chown of the -# omarchy-send subdir alone leaves ~/.config itself root-owned. That blocks the -# user from creating anything else under ~/.config later — e.g. OMATERM's -# LazyVim step (`git clone ~/.config/nvim`) fails with "Permission denied". -arch-chroot /mnt chown -R "$USERNAME:$USERNAME" "/home/$USERNAME/.local" "/home/$USERNAME/.config" - echo "==> Writing pre-login console banner (hostname + IPv4 + ssh hint)..." # agetty expands these escapes when it prints /etc/issue: # \n = hostname, \4 = primary IPv4, \r = kernel, \l = tty