Omnish skill

Omnish setup and usage

Help the user install, configure, and use omnish — a messaging-to-shell gateway (WhatsApp, Telegram, or platform attached mode). Chat is the primary UX; emphasize file sharing and notifications as high-value extras.

First step: triage

Run the bundled doctor (after install) or from the repo:

bash ~/.cursor/skills/omnish/scripts/doctor.sh
# or: bash contrib/omnish-cursor/scripts/doctor.sh

Interpret output: omnish on PATH, gateway running, allowlist/platform token, Cursor hooks/skill installed. Never echo secrets from config.

Setup paths

Pick one path — see setup-paths.md:

Path	When
Platform attached	User has platform_url + platform_token; messengers on relay
Standalone WhatsApp	Local omnish link + QR
Standalone Telegram	omnish link --tg <token>

Platform attached (common for builders):

npm install -g omnish
omnish platform login --url https://tunnel.omnish.dev --token YOUR_ACCOUNT_TOKEN
omnish platform status && omnish platform probe
omnish run

Verify from allowlisted chat: !pwd or !help.

Configuration essentials

• Data dir: omnish status shows path (~/.omnish or legacy ~/.whatslive; override OMNISH_HOME)
• Inspect: omnish config show, omnish config show platform, omnish security
• Key keys: gatewayMode, allowFrom / telegramAllowFrom, fileSendMaxBytes, fileReceiveMaxBytes, fileReceiveRootMode, recipesNotifyEnabled, platformToken

Edit via CLI or chat /config show (allowlisted). Restart gateway after changes (/reload or restart omnish run).

Chat usage (primary)

Surface	Prefix / command	Purpose
Sync shell	!cmd	Immediate command in chat cwd
Change cwd	!cd path	Per-chat working directory
Background	/bg cmd	Detached job; /jobs, /tail, /kill
PTY apps	/apps start name cmd	Interactive TUIs
Recipes	/run name task	Saved agent wrappers ($OMNISH_TASK)
Scheduled	/cowork	Saved tasks, logs, notify rules

Full manual: omnish repo docs/guides/user-guide.md or omnish search user guide.

File sharing (high value)

See files-and-sharing.md.

Quick reference:

/send ./report.pdf -- Summary        # chat → mobile (current chat cwd)
/receive here                        # inbound saves to chat cwd

From terminal (requires omnish run):

omnish i -c '/sendto * ./report.pdf -- Summary'
omnish i -c '/sendto * -t Status -- deploy finished'

* = all allowlisted peers (WhatsApp + Telegram). No channel-specific ids required.

Notifications

See notifications.md.

• Cursor auto: install contrib/omnish-cursor/install.sh → stop hook sends Done briefs with chat id
• Manual / agents: omnish i -c '/sendto * -t Title -- brief'
• Background jobs: /bg -N long-running-command
• Cowork: /cowork set name when always|failure|state-change

Default destination: * (broadcast). Config: ~/.cursor/omnish-notify.json.

Helping users: checklist

Copy and track:

- [ ] omnish installed (npm i -g omnish)
- [ ] Setup path chosen (platform / WA / TG)
- [ ] Gateway running (omnish run)
- [ ] Allowlist configured (platform dashboard or omnish allow)
- [ ] Smoke test: !pwd from chat
- [ ] File test: /send or omnish i /sendto *
- [ ] Notify test: omnish i -c '/sendto * -t Test -- ok'
- [ ] Cursor bundle (optional): bash contrib/omnish-cursor/install.sh
- [ ] doctor.sh passes with no blockers

Cursor bundle install

For users who want agent Done notifications + this skill globally:

bash contrib/omnish-cursor/install.sh
# partial: --hooks-only | --skill-only

Installs hooks, rule, skill to ~/.cursor/, config with "peer": "*". Restart Cursor after install.

Doc pointers

• Quick start: docs/guides/quick-start.md
• Platform: docs/guides/platform-attached-mode.md, docs/guides/platform-reference.md
• Files: docs/files-send-receive.md
• Interactive CLI: docs/guides/interactive-cli.md
• Offline search: omnish search <topic>

Do not paste platform tokens or webhook secrets into chat or commits.