moshi-best-practices

Name: moshi-best-practices
Author: rjyo

28stars4forks

How to install moshi-best-practices?

rjyo/moshi-skill/moshi-best-practices

$npx -y skills add rjyo/moshi-skill --skill moshi-best-practices

Installs into the current project.

Summary

Use when preparing or verifying a host for Moshi remote coding. Trigger this for Easy Pair host setup, SSH or preferably Mosh readiness, non-interactive shell PATH issues, tmux defaults, creating a tmux project session rooted at a chosen directory, adapting shell or tmux behavior

Files · 1

View on GitHub

SKILL.md

1	# Moshi Best Practices
2
3	Use this skill to make any host feel easy to use from Moshi.
4
5	Use it for either:
6
7	- fresh setup
8	- verification of an existing setup
9
10	## Rules
11
12	- Inspect before editing.
13	- Prefer direct config edits over platform-specific setup scripts.
14	- Verify every outcome after changing it.
15	- Do not install the old `moshi` shell helper or alias. Current installs provide `moshi` as a symlink to `moshi-hook`.
16
17	## 1. Host Readiness
18
19	For a fresh Moshi SSH/Mosh setup, prefer Easy Pair when `moshi-hook` is available:
20
21	```bash
22	moshi-hook host setup
23	```
24
25	Tell the user to scan the Easy Pair QR from Moshi. This creates the saved host connection, generates the phone-side private key, and installs Moshi's public key on the host. Call out the security boundary: anyone who scans the QR before it expires can claim SSH access to the host, so they should not share the screen or setup link.
26
27	Do not confuse Easy Pair with `moshi-hook pair --token`; token pairing is only for agent hooks, inbox, Live Activities, and Apple Watch events.
28
29	Target outcome:
30
31	- preferred transport is Mosh plus tmux; fallback is SSH plus tmux
32	- the host has a working SSH entry point
33	- `tmux` is installed
34	- `mosh-server` is installed when the user wants Mosh, otherwise SSH plus tmux is acceptable
35	- both resolve in the current shell and in the login shell's non-interactive mode
36	- at least one tmux session exists so the Moshi selector can appear.
37
38	Inspect with a small set of real checks. Keep OS-specific mechanics minimal, but do not skip verification.
39
40	Useful checks:
41
42	```bash
43	command -v tmux \|\| true
44	command -v mosh-server \|\| true
45	tmux list-sessions 2>/dev/null \|\| true
46	LOGIN_SHELL="${SHELL:-/bin/sh}"
47	"$LOGIN_SHELL" -c 'command -v tmux'
48	"$LOGIN_SHELL" -c 'command -v mosh-server'
49	```
50
51	Useful macOS-specific checks when relevant:
52
53	```bash
54	dscl . -read "/Users/$USER" UserShell
55	systemsetup -getremotelogin \|\| true
56	```
57
58	Verify after changes:
59
60	```bash
61	command -v tmux
62	tmux list-sessions
63	"$LOGIN_SHELL" -c 'command -v tmux'
64	"$LOGIN_SHELL" -c 'command -v mosh-server' \|\| true
65	```
66
67	Then ask the user to reconnect from Moshi. Expected result: the tmux selector appears, and the transport can use Mosh instead of plain SSH when configured.
68
69	## 2. tmux Environment
70
71	Use these defaults unless the user wants something different:
72
73	```tmux
74	set -g history-limit 100000
75	set -g mouse on
76	set -g set-titles on
77	set -g set-titles-string "#I: #W"
78	set -g base-index 1
79	setw -g pane-base-index 1
80	set -g renumber-windows on
81	```
82
83	Workflow:
84
85	- inspect the existing tmux config
86	- update overlapping settings instead of appending duplicates
87	- reload tmux after editing
88
89	## 3. MOSHI_CLIENT Signal
90
91	`MOSHI_CLIENT=1` is an opt-in environment variable the Moshi iOS client exports
92	into the remote shell so rc files, prompts, and tmux configs can detect a
93	Moshi-launched session and adapt. The user enables it in the app under
94	Settings → Integrations → Export ENV (off by default). When on, it is set
95	identically on both the Mosh path (via `mosh-server -l MOSHI_CLIENT=1`) and the
96	SSH fallback (via an injected `export` at shell start).
97
98	The main use case is protecting Moshi's swipe-to-change-window gesture, which
99	relies on reading the tmux status bar. A populated `status-left` /
100	`status-right` from a custom theme can break detection. Conditionally clearing
101	them when `MOSHI_CLIENT` is set keeps local themes intact while keeping Moshi
102	detection reliable. Other uses: narrower prompts, dropping nerd-font glyphs,
103	different key bindings.
104
105	Shell (in the user's rc file):
106
107	```sh
108	if [ -n "$MOSHI_CLIENT" ]; then
109	# running under Moshi — trim prompts, skip heavy glyphs, etc.
110	fi
111	```
112
113	tmux (in `~/.tmux.conf`):
114
115	```tmux
116	# propagate the variable into tmux sessions attached by this shell
117	set-option -ga update-environment " MOSHI_CLIENT"
118
119	# clear status regions for Moshi clients so swipe detection stays clean
120	if-shell '[ -n "$MOSHI_CLIENT" ]' {
121	set -g status-left ''
122	set -g status-right ''
123	}
124	```
125
126	After editing, reload tmux (`tmux source-file ~/.tmux.conf`).
127
128	Verify, after the user toggles the setting on and reconnects from Moshi:
129
130	```bash
131	echo "$MOSHI_CLIENT" # expect: 1
132	tmux show-environment \| grep MOSHI_CLIENT # expect a value in new sessions
133	```
134
135	If `echo` prints nothing, the toggle is off in the app — confirm with the user
136	before editing host configs. The variable only appears in sessions opened
137	after the toggle was flipped.
138
139	## 4. tmux Project Session
140
141	When `moshi-hook` is installed

People who liked this also viewed

6 picks

Type

moshi-best-practices

28stars4forks

View on GitHub

How to install moshi-best-practices?

rjyo/moshi-skill/moshi-best-practices

$npx -y skills add rjyo/moshi-skill --skill moshi-best-practices

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Moshi Best Practices
2
3	Use this skill to make any host feel easy to use from Moshi.
4
5	Use it for either:
6
7	- fresh setup
8	- verification of an existing setup
9
10	## Rules
11
12	- Inspect before editing.
13	- Prefer direct config edits over platform-specific setup scripts.
14	- Verify every outcome after changing it.
15	- Do not install the old `moshi` shell helper or alias. Current installs provide `moshi` as a symlink to `moshi-hook`.
16
17	## 1. Host Readiness
18
19	For a fresh Moshi SSH/Mosh setup, prefer Easy Pair when `moshi-hook` is available:
20
21	```bash
22	moshi-hook host setup
23	```
24
25	Tell the user to scan the Easy Pair QR from Moshi. This creates the saved host connection, generates the phone-side private key, and installs Moshi's public key on the host. Call out the security boundary: anyone who scans the QR before it expires can claim SSH access to the host, so they should not share the screen or setup link.
26
27	Do not confuse Easy Pair with `moshi-hook pair --token`; token pairing is only for agent hooks, inbox, Live Activities, and Apple Watch events.
28
29	Target outcome:
30
31	- preferred transport is Mosh plus tmux; fallback is SSH plus tmux
32	- the host has a working SSH entry point
33	- `tmux` is installed
34	- `mosh-server` is installed when the user wants Mosh, otherwise SSH plus tmux is acceptable
35	- both resolve in the current shell and in the login shell's non-interactive mode
36	- at least one tmux session exists so the Moshi selector can appear.
37
38	Inspect with a small set of real checks. Keep OS-specific mechanics minimal, but do not skip verification.
39
40	Useful checks:
41
42	```bash
43	command -v tmux \|\| true
44	command -v mosh-server \|\| true
45	tmux list-sessions 2>/dev/null \|\| true
46	LOGIN_SHELL="${SHELL:-/bin/sh}"
47	"$LOGIN_SHELL" -c 'command -v tmux'
48	"$LOGIN_SHELL" -c 'command -v mosh-server'
49	```
50
51	Useful macOS-specific checks when relevant:
52
53	```bash
54	dscl . -read "/Users/$USER" UserShell
55	systemsetup -getremotelogin \|\| true
56	```
57
58	Verify after changes:
59
60	```bash
61	command -v tmux
62	tmux list-sessions
63	"$LOGIN_SHELL" -c 'command -v tmux'
64	"$LOGIN_SHELL" -c 'command -v mosh-server' \|\| true
65	```
66
67	Then ask the user to reconnect from Moshi. Expected result: the tmux selector appears, and the transport can use Mosh instead of plain SSH when configured.
68
69	## 2. tmux Environment
70
71	Use these defaults unless the user wants something different:
72
73	```tmux
74	set -g history-limit 100000
75	set -g mouse on
76	set -g set-titles on
77	set -g set-titles-string "#I: #W"
78	set -g base-index 1
79	setw -g pane-base-index 1
80	set -g renumber-windows on
81	```
82
83	Workflow:
84
85	- inspect the existing tmux config
86	- update overlapping settings instead of appending duplicates
87	- reload tmux after editing
88
89	## 3. MOSHI_CLIENT Signal
90
91	`MOSHI_CLIENT=1` is an opt-in environment variable the Moshi iOS client exports
92	into the remote shell so rc files, prompts, and tmux configs can detect a
93	Moshi-launched session and adapt. The user enables it in the app under
94	Settings → Integrations → Export ENV (off by default). When on, it is set
95	identically on both the Mosh path (via `mosh-server -l MOSHI_CLIENT=1`) and the
96	SSH fallback (via an injected `export` at shell start).
97
98	The main use case is protecting Moshi's swipe-to-change-window gesture, which
99	relies on reading the tmux status bar. A populated `status-left` /
100	`status-right` from a custom theme can break detection. Conditionally clearing
101	them when `MOSHI_CLIENT` is set keeps local themes intact while keeping Moshi
102	detection reliable. Other uses: narrower prompts, dropping nerd-font glyphs,
103	different key bindings.
104
105	Shell (in the user's rc file):
106
107	```sh
108	if [ -n "$MOSHI_CLIENT" ]; then
109	# running under Moshi — trim prompts, skip heavy glyphs, etc.
110	fi
111	```
112
113	tmux (in `~/.tmux.conf`):
114
115	```tmux
116	# propagate the variable into tmux sessions attached by this shell
117	set-option -ga update-environment " MOSHI_CLIENT"
118
119	# clear status regions for Moshi clients so swipe detection stays clean
120	if-shell '[ -n "$MOSHI_CLIENT" ]' {
121	set -g status-left ''
122	set -g status-right ''
123	}
124	```
125
126	After editing, reload tmux (`tmux source-file ~/.tmux.conf`).
127
128	Verify, after the user toggles the setting on and reconnects from Moshi:
129
130	```bash
131	echo "$MOSHI_CLIENT" # expect: 1
132	tmux show-environment \| grep MOSHI_CLIENT # expect a value in new sessions
133	```
134
135	If `echo` prints nothing, the toggle is off in the app — confirm with the user
136	before editing host configs. The variable only appears in sessions opened
137	after the toggle was flipped.
138
139	## 4. tmux Project Session
140
141	When `moshi-hook` is installed

People who liked this also viewed

6 picks

Type