omnish 1.6.6 → 2.0.0

package/dist/omnish-claude/skill/files-and-sharing.md

@@ -0,0 +1,94 @@
+# File sharing with Omnish
+
+Omnish moves files **host ↔ chat**. Per-chat cwd applies (same as `!` commands). Use **`/sendto *`** for broadcast to all allowlisted peers unless the user needs one recipient.
+
+## Outbound: host → chat
+
+### From chat (`/send` or `/file`)
+
+Works in the current chat's working directory:
+
+```text
+/send ./photo.png
+/send ./a.pdf,./b.png -- Two files
+/send *.mp4
+/send **/*.mp4
+/send "/path with spaces/file.bin" -- Caption here
+```
+
+Limits: `fileSendMaxBytes` in config (`0` = no omnish cap on standalone; platform hop may have separate relay limits).
+
+### From terminal (`omnish i` + `/sendto`)
+
+Requires **`omnish run`** on the same machine.
+
+```bash
+omnish i -c '/sendto * ./promo.mp4'
+omnish i -c '/sendto * intro.png,deck.pdf -- Launch materials'
+omnish i -c '/sendto wa ./photo.png'              # all allowlisted WA
+omnish i -c '/sendto tg **/*.mp4 -- Video batch'   # all allowlisted TG
+omnish i -c '/sendto +15551234567 ./file.pdf'      # explicit E.164
+omnish i -c '/sendto tg:123456789 ./report.pdf'    # explicit Telegram id
+```
+
+Plain text (not a file attachment):
+
+```bash
+omnish i -c '/sendto * --text Deploy finished OK'
+omnish i -c '/sendto * -t=Status OK'
+```
+
+| Destination | Meaning                             |
+| ----------- | ----------------------------------- |
+| `*`         | All allowlisted WhatsApp + Telegram |
+| `wa`        | All allowlisted WhatsApp            |
+| `tg`        | All allowlisted Telegram            |
+| `+E164`     | One WhatsApp number                 |
+| `tg:<id>`   | One Telegram chat id                |
+
+Change cwd in REPL: `!cd /path/to/project` before `/sendto`.
+
+## Inbound: chat → host
+
+```text
+/receive                       # show current save mode
+/receive here                  # save to this chat's cwd
+/receive default               # global default root
+```
+
+Inbound paths appear as `Saved: …` on **your machine** (even in platform attached mode).
+
+Config keys:
+
+- `fileReceiveRootMode`: `downloads`, `cwd`, `fixed`, etc.
+- `fileReceiveRootPath`: when mode is `fixed`
+- `fileReceiveMaxBytes`: size cap (`0` = unlimited)
+- `fileInboxSubdir`: subfolder under receive root
+
+## Platform attached mode differences
+
+| Feature                      | Standalone                  | Platform attached                               |
+| ---------------------------- | --------------------------- | ----------------------------------------------- |
+| `/send` in chat              | Direct to messenger on host | Device → platform WebSocket → relay → messenger |
+| Inbound media                | Saved locally               | Relay forwards bytes; **device** saves locally  |
+| `omnish i /sendto`           | Local control channel       | Same, via platform WebSocket                    |
+| Allowlists for `wa`/`tg`/`*` | Local config                | Platform `GET /v1/me` when credentials set      |
+
+Explicit `+E164` / `tg:id` always work on both.
+
+## Agent workflow: file round-trip test
+
+1. Confirm gateway: `omnish status`
+2. In chat cwd, create test file: `!echo test > omnish-file-test.txt`
+3. Send: `/send ./omnish-file-test.txt -- omnish test`
+4. Or CLI: `omnish i -c '/sendto * ./omnish-file-test.txt -- omnish test'`
+5. User confirms receipt on mobile
+
+## Troubleshooting
+
+- `No files matched` — wrong cwd; use `!pwd` or `!cd`
+- `wa`/`tg`/`*` recipient error — empty allowlist; configure on platform or `omnish allow`
+- File too large — raise `fileSendMaxBytes`; check platform `PLATFORM_REPLY_FILE_MAX_BYTES` if attached
+- File named `--text` — use path `./--text`
+
+Full reference: `docs/files-send-receive.md`, `docs/guides/interactive-cli.md`.

package/dist/omnish-claude/skill/notifications.md

@@ -0,0 +1,113 @@
+# Omnish notifications
+
+Keep terminal noise local; push **curated briefs** to mobile. Default destination: **`*`** (all allowlisted peers). Works on standalone and platform attached gateways.
+
+## Status message format
+
+```bash
+omnish i -c '/sendto * -t <title> -- <brief>'
+```
+
+Message types:
+
+| Type         | When                           |
+| ------------ | ------------------------------ |
+| **Ack**      | Task accepted                  |
+| **Progress** | Major phase change (sparingly) |
+| **Question** | Needs human input              |
+| **Done**     | Finished with outcome          |
+| **Blocked**  | Failure or dependency          |
+
+Rules:
+
+1. Do not stream raw logs to chat.
+2. One or two sentences; mobile-friendly.
+3. Ask before sending files unless requested.
+4. Include Cursor `conversation_id` when notifying from Cursor agent work.
+
+## IDE automatic notifications (Cursor / Claude Code)
+
+Install the bundle for your editor:
+
+```bash
+omnish agents install cursor   # ~/.cursor hooks + skill
+omnish agents install claude   # ~/.claude Stop hook + skill
+omnish agents install all      # both
+```
+
+Or from repo: `bash contrib/omnish-cursor/install.sh` · `bash contrib/omnish-claude/install.sh`
+
+Stop hook sends when agent work is substantive (tools used, real outcome). Skips trivial Q&A and aborted turns.
+
+Config `~/.cursor/omnish-notify.json` or `~/.claude/omnish-notify.json`:
+
+```json
+{
+  "enabled": true,
+  "peer": "*",
+  "min_assistant_chars": 120,
+  "notify_on_error": true,
+  "skip_aborted": true,
+  "include_full_chat_id": true
+}
+```
+
+Log: `~/.cursor/hooks/omnish-notify.log`
+
+## Manual and agent-driven sends
+
+Helper script (from omnish repo root):
+
+```bash
+bash scripts/agent-notify.sh "Deploy Done" "main branch live; chat abc123"
+```
+
+Uses `OMNISH_PEER_KEY` if set, else `OMNISH_JOB_OWNER_PEER`, else `*`.
+
+Env from `/run` and chat agent daemon:
+
+| Variable                     | Purpose                              |
+| ---------------------------- | ------------------------------------ |
+| `OMNISH_PEER_KEY`            | Initiator peer                       |
+| `OMNISH_NOTIFY_CMD`          | Template with `/sendto peer`         |
+| `OMNISH_COMMUNICATION_BRIEF` | Guidance when `recipesNotifyEnabled` |
+
+For broadcast, omit `OMNISH_PEER_KEY` and use `/sendto *` explicitly.
+
+## Chat-native notifications
+
+**Background jobs** — notify on completion:
+
+```text
+/bg -N -n deploy git pull && npm run build
+```
+
+**Cowork** — conditional notify:
+
+```text
+/cowork set backup when failure
+/cowork set heartbeat when state-change
+```
+
+**Board / specialists** — status via same `/sendto` pattern (see `docs/guides/system-agents-and-run.md`).
+
+## Test notification
+
+```bash
+omnish i -c '/sendto * -t Omnish Test -- cursor hook ok'
+```
+
+Requires `omnish run` and non-empty allowlist (or platform token routing).
+
+## Avoid duplicate pings
+
+When Cursor stop hook is installed, agents should not send a second **Done** for the same completion. Use Progress/Question/Blocked during work; let the hook handle final Done unless the user disables hooks.
+
+## Troubleshooting
+
+| Issue           | Check                                       |
+| --------------- | ------------------------------------------- |
+| No message      | `omnish status`; gateway running; allowlist |
+| Hook skips      | Log file; turn may be trivial or aborted    |
+| Wrong recipient | `peer` in `omnish-notify.json`              |
+| Platform mode   | Token + probe; allowlists on dashboard      |

package/dist/omnish-claude/skill/setup-paths.md

@@ -0,0 +1,81 @@
+# Omnish setup paths
+
+Choose exactly one primary path. All paths end with **`omnish run`** on the machine that executes shell commands.
+
+## Platform attached mode (recommended for multi-device)
+
+Messengers (WhatsApp/Telegram) link on the **hosted platform**; each device runs `omnish run` with an account token.
+
+1. Create account on platform dashboard (e.g. `https://tunnel.omnish.dev/dashboard/`).
+2. Link WhatsApp (QR) and/or Telegram (bot token) on the dashboard; save allowlists there.
+3. On each execution host:
+
+```bash
+npm install -g omnish
+omnish platform login --url https://tunnel.omnish.dev --token YOUR_ACCOUNT_TOKEN
+omnish config show platform    # verify URL + token source (masked)
+omnish platform probe          # connectivity check
+omnish run                     # foreground, or: omnish start
+```
+
+4. From allowlisted chat: `!pwd`, `!help`.
+
+**Notes:**
+
+- No local `omnish link` required for WhatsApp when fully platform-attached.
+- Files: outbound `/send` and `omnish i /sendto` use device → platform → messenger; inbound media saves on **your device** paths.
+- Docs: `docs/guides/platform-attached-mode.md`, `docs/guides/platform-reference.md`.
+
+## Standalone WhatsApp
+
+Shell and Baileys session on the same host.
+
+```bash
+npm install -g omnish
+omnish link                    # scan QR (Linked devices)
+omnish allow +15551234567      # E.164 allowlist
+omnish run
+```
+
+Private chats only (no groups). Session under data dir `auth/`. Re-link if session missing in `omnish status`.
+
+## Standalone Telegram
+
+```bash
+npm install -g omnish
+omnish link --tg YOUR_BOT_TOKEN
+# message bot /id to learn your tg id, then:
+omnish allow tg:123456789
+omnish run
+```
+
+Set `gatewayMode` to `telegram` or `both` in config if using both channels.
+
+## Background gateway
+
+```bash
+omnish start                   # background pidfile
+omnish stop
+omnish service install         # boot hints (systemd / LaunchAgent / Task Scheduler)
+```
+
+See `docs/guides/background-and-boot.md`.
+
+## Verify any path
+
+```bash
+omnish status
+omnish security --json         # optional scriptable audit
+```
+
+From chat (allowlisted): `!echo omnish-ok`
+
+## Common failures
+
+| Symptom                            | Fix                                                                    |
+| ---------------------------------- | ---------------------------------------------------------------------- |
+| `gateway process: not running`     | `omnish run` or `omnish start`                                         |
+| `session: missing` (standalone WA) | `omnish link`                                                          |
+| `denied` in logs                   | Add sender to allowlist; check LID mapping with `omnish run --verbose` |
+| Platform probe fails               | Check URL/token; `omnish config show platform`                         |
+| `/sendto` no delivery              | Gateway must run; allowlist non-empty for `*`                          |

package/dist/omnish-claude/uninstall.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Remove Omnish Claude Code bundle entries from ~/.claude (keeps unrelated hooks).
+set -euo pipefail
+
+CLAUDE_DIR="${CLAUDE_DIR:-$HOME/.claude}"
+SETTINGS_JSON="$CLAUDE_DIR/settings.json"
+HOOK_CMD="$CLAUDE_DIR/hooks/omnish-notify.sh"
+
+REMOVE_HOOKS=1
+REMOVE_SKILL=1
+REMOVE_CONFIG=0
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options]
+
+Remove Omnish Claude Code integration installed by install.sh.
+
+Options:
+  --hooks-only     Remove Stop hook + hook scripts only
+  --skill-only     Remove ~/.claude/skills/omnish only
+  --with-config    Also delete ~/.claude/omnish-notify.json
+  -h, --help       Show this help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --hooks-only)
+      REMOVE_HOOKS=1
+      REMOVE_SKILL=0
+      shift
+      ;;
+    --skill-only)
+      REMOVE_HOOKS=0
+      REMOVE_SKILL=1
+      shift
+      ;;
+    --with-config)
+      REMOVE_CONFIG=1
+      shift
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "error: unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ "$REMOVE_HOOKS" -eq 1 && -f "$SETTINGS_JSON" ]]; then
+  python3 - "$SETTINGS_JSON" "$HOOK_CMD" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+settings_path = Path(sys.argv[1])
+hook_cmd = sys.argv[2]
+if not settings_path.is_file():
+    raise SystemExit(0)
+data = json.loads(settings_path.read_text(encoding="utf-8"))
+hooks = data.get("hooks") or {}
+existing = hooks.get("Stop") or []
+if not isinstance(existing, list):
+    raise SystemExit(0)
+filtered = []
+changed = False
+for group in existing:
+    if not isinstance(group, dict):
+        filtered.append(group)
+        continue
+    inner = group.get("hooks") or []
+    new_inner = [
+        h for h in inner
+        if not (isinstance(h, dict) and h.get("command") == hook_cmd)
+    ]
+    if len(new_inner) != len(inner):
+        changed = True
+    if new_inner:
+        group = dict(group)
+        group["hooks"] = new_inner
+        filtered.append(group)
+if changed:
+    if filtered:
+        hooks["Stop"] = filtered
+    else:
+        hooks.pop("Stop", None)
+    settings_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    print(f"updated {settings_path} (removed omnish Stop hook)")
+else:
+    print(f"no omnish Stop hook in {settings_path}")
+PY
+fi
+
+if [[ "$REMOVE_HOOKS" -eq 1 ]]; then
+  rm -f "$CLAUDE_DIR/hooks/omnish-notify.sh" "$CLAUDE_DIR/hooks/omnish-notify.py"
+  echo "removed hook scripts"
+fi
+
+if [[ "$REMOVE_SKILL" -eq 1 ]]; then
+  rm -rf "$CLAUDE_DIR/skills/omnish"
+  echo "removed $CLAUDE_DIR/skills/omnish"
+fi
+
+if [[ "$REMOVE_CONFIG" -eq 1 ]]; then
+  rm -f "$CLAUDE_DIR/omnish-notify.json"
+  echo "removed $CLAUDE_DIR/omnish-notify.json"
+fi
+
+echo "Done. Restart Claude Code if hooks were removed."

package/dist/omnish-cursor/README.md

@@ -0,0 +1,176 @@
+# Omnish Cursor integration
+
+Install Omnish in Cursor for file sharing, mobile notifications, and Done briefs when Agent finishes useful work.
+
+Works with any Omnish setup:
+
+- Local WhatsApp / Telegram (`omnish link`, `omnish run`)
+- Platform attached mode (`platform_url` + `platform_token`, `omnish run`)
+- Mixed allowlists (`wa:+…`, `tg:…`, LID peers)
+
+Default notification target is `*` (all allowlisted peers). No channel-specific ids baked in.
+
+## Quick install
+
+**Offline (bundled with omnish — no omnish.dev):**
+
+```bash
+omnish agents install cursor
+omnish agents install claude
+```
+
+From allowlisted chat (when `agentInstallFromChat` is enabled):
+
+```text
+/agents install cursor
+```
+
+**Online (curl):**
+
+```bash
+curl -fsSL https://omnish.dev/downloads/omnish-cursor/install.sh | bash
+```
+
+From a local omnish clone:
+
+```bash
+bash contrib/omnish-cursor/install.sh
+```
+
+Partial install:
+
+```bash
+./install.sh --hooks-only   # Cursor hooks + rule + notify config
+./install.sh --skill-only   # Cursor skill + doctor script only
+```
+
+Requires: **Cursor** (hooks), **python3**, **omnish** on `PATH` for hooks install.
+
+## What it installs
+
+| Path                                        | Purpose                                |
+| ------------------------------------------- | -------------------------------------- |
+| `~/.cursor/skills/omnish/SKILL.md`          | Full setup/usage skill for the agent   |
+| `~/.cursor/skills/omnish/scripts/doctor.sh` | Health check script                    |
+| `~/.cursor/hooks/omnish-notify.py`          | Stop-hook logic (smart send / skip)    |
+| `~/.cursor/hooks/omnish-notify.sh`          | Stop hook wrapper                      |
+| `~/.cursor/hooks/omnish-session-start.sh`   | Injects notify policy each session     |
+| `~/.cursor/rules/omnish-notify.mdc`         | Always-on agent guidance               |
+| `~/.cursor/omnish-notify.json`              | Notify config (created if missing)     |
+| `~/.cursor/hooks.json`                      | Merges `sessionStart` + `stop` entries |
+
+Restart Cursor after install (or reload **Hooks** in Settings).
+
+## Verify
+
+```bash
+bash ~/.cursor/skills/omnish/scripts/doctor.sh
+```
+
+Test notify (gateway must run):
+
+```bash
+omnish i -c '/sendto * -t Omnish Test -- cursor bundle ok'
+```
+
+## Omnish skill
+
+The installed skill guides Cursor to:
+
+1. Choose setup path (platform / WhatsApp / Telegram)
+2. Configure gateway and allowlists
+3. Use chat commands (`!`, `/bg`, `/apps`, `/run`, `/cowork`)
+4. Share files (`/send`, `/receive`, `omnish i /sendto *`)
+5. Send curated notifications (hooks, manual, `/bg -N`)
+
+Reference files live beside the skill: `setup-paths.md`, `files-and-sharing.md`, `notifications.md`.
+
+## Notify config (`~/.cursor/omnish-notify.json`)
+
+```json
+{
+  "enabled": true,
+  "peer": "*",
+  "min_assistant_chars": 120,
+  "notify_on_error": true,
+  "skip_aborted": true,
+  "include_full_chat_id": true
+}
+```
+
+| Key                     | Default | Meaning                                  |
+| ----------------------- | ------- | ---------------------------------------- |
+| `enabled`               | `true`  | Master switch                            |
+| `peer`                  | `"*"`   | `/sendto` destination                    |
+| `min_assistant_chars`   | `120`   | Notify on long text-only completions     |
+| `notify_on_error`       | `true`  | Notify when agent ends with error        |
+| `skip_aborted`          | `true`  | Skip user-aborted turns                  |
+| `include_full_chat_id`  | `true`  | Full `conversation_id` in brief          |
+| `summary_max_chars`     | `300`   | Outcome summary length in main message   |
+| `followup_max_chars`    | `1000`  | Max chars per follow-up message          |
+| `max_followup_messages` | `2`     | Extra messages after main brief          |
+| `send_followups`        | `true`  | Send follow-ups for long request/outcome |
+
+## When stop-hook notifications send
+
+**Send** when the agent turn included real work (file edits, shell, subagents, substantive outcome).
+
+**Skip** when aborted or trivial Q&A.
+
+Example main brief (newlines render as title + body in chat):
+
+```
+Cursor Done: Fix auth hooks
+
+Status: Done
+Chat: 01866f06-…
+Workspace: omnish
+
+You asked:
+Fix notification messaging in cursor hooks and skill
+
+Outcome:
+Hook now sends structured multi-line briefs; long content goes in follow-up messages.
+
+Tools: 6 action(s)
+```
+
+Delivered as:
+
+```bash
+omnish i -c '/sendto * -t Cursor Done: Fix auth hooks -- Status: Done
+Chat: …
+…'
+```
+
+Long requests or outcomes may add `Cursor · Request` and `Cursor · Outcome` follow-ups.
+
+## Prerequisites
+
+1. `npm i -g omnish`
+2. Gateway: `omnish run` (or `omnish start`)
+3. Allowlist or platform token configured
+4. Cursor with hooks enabled
+
+Platform attached mode: [docs/guides/platform-attached-mode.md](../../docs/guides/platform-attached-mode.md)
+
+## Troubleshooting
+
+| Issue             | Check                                      |
+| ----------------- | ------------------------------------------ |
+| No mobile message | `omnish status`, allowlist, platform token |
+| Hook never runs   | Cursor Settings → Hooks; restart Cursor    |
+| Always skipped    | `~/.cursor/hooks/omnish-notify.log`        |
+| Skill not found   | `./install.sh --skill-only`                |
+
+## Uninstall
+
+```bash
+curl -fsSL https://omnish.dev/downloads/omnish-cursor/uninstall.sh | bash
+```
+
+Or from a downloaded copy: `./uninstall.sh` (add `--with-config` to remove notify json).
+
+## License
+
+Same as omnish (MIT). Share freely.