moshi-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Moshi Best Practices

Moshi最佳实践

Use this skill to make any host feel easy to use from Moshi.

Use it for either:

fresh setup
verification of an existing setup

使用此技能让你通过Moshi操作任何主机都能轻松上手。

可用于以下两种场景：

全新搭建
已有配置的验证

Rules

规则

Inspect before editing.
Prefer direct config edits over platform-specific setup scripts.
Verify every outcome after changing it.
For
```
moshi DIR
```
, use a shell function named
```
moshi
```
, not a literal alias. Aliases cannot take arguments safely.

修改前先检查现有配置
优先直接修改配置文件，而非使用平台特定的搭建脚本
每次修改后都要验证结果
实现
```
moshi DIR
```
功能时请使用名为
```
moshi
```
的shell函数，不要使用字面别名，别名无法安全接收参数。

1. Host Readiness

1. 主机就绪检查

Target outcome:

preferred transport is Mosh plus tmux; fallback is SSH plus tmux
the host has a working SSH entry point
```
tmux
```
is installed
```
mosh-server
```
is installed when the user wants Mosh, otherwise SSH plus tmux is acceptable
both resolve in the current shell and in the login shell's non-interactive mode
at least one tmux session exists so the Moshi selector can appear.

Inspect with a small set of real checks. Keep OS-specific mechanics minimal, but do not skip verification.

Useful checks:

bash

command -v tmux || true
command -v mosh-server || true
tmux list-sessions 2>/dev/null || true
LOGIN_SHELL="${SHELL:-/bin/sh}"
"$LOGIN_SHELL" -c 'command -v tmux'
"$LOGIN_SHELL" -c 'command -v mosh-server'

Useful macOS-specific checks when relevant:

bash

dscl . -read "/Users/$USER" UserShell
systemsetup -getremotelogin || true

Verify after changes:

bash

command -v tmux
tmux list-sessions
"$LOGIN_SHELL" -c 'command -v tmux'
"$LOGIN_SHELL" -c 'command -v mosh-server' || true

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.

目标结果：

优先使用的传输协议是Mosh + tmux；备选方案是SSH + tmux
主机有可用的SSH入口
已安装
```
tmux
```
用户需要使用Mosh时已安装
```
mosh-server
```
，否则SSH + tmux的配置即可接受
上述工具在当前shell和登录shell的非交互模式下都能正常识别
至少存在一个tmux会话，以便Moshi选择器可以正常显示。

使用少量实际检查命令进行检测，尽量减少操作系统特定的操作，但不要跳过验证步骤。

常用检查命令：

bash

command -v tmux || true
command -v mosh-server || true
tmux list-sessions 2>/dev/null || true
LOGIN_SHELL="${SHELL:-/bin/sh}"
"$LOGIN_SHELL" -c 'command -v tmux'
"$LOGIN_SHELL" -c 'command -v mosh-server'

适用时可使用macOS专属检查命令：

bash

dscl . -read "/Users/$USER" UserShell
systemsetup -getremotelogin || true

修改后验证命令：

bash

command -v tmux
tmux list-sessions
"$LOGIN_SHELL" -c 'command -v tmux'
"$LOGIN_SHELL" -c 'command -v mosh-server' || true

之后请用户从Moshi重新连接。预期结果：tmux选择器正常显示，配置完成后传输协议可使用Mosh代替普通SSH。

2. tmux Environment

2. tmux环境配置

Use these defaults unless the user wants something different:

tmux

set -g history-limit 100000
set -g mouse on
set -g set-titles on
set -g set-titles-string "#I: #W"
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on

Workflow:

inspect the existing tmux config
update overlapping settings instead of appending duplicates
reload tmux after editing

除非用户有其他需求，否则使用以下默认配置：

tmux

set -g history-limit 100000
set -g mouse on
set -g set-titles on
set -g set-titles-string "#I: #W"
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on

工作流：

检查现有tmux配置
更新重叠的配置项，不要追加重复配置
编辑完成后重载tmux配置

3. tmux Project Session

3. tmux项目会话

When creating a new session:

read the current working directory
ask one concise question: should the session start from here?
if the answer is no, ask for the directory
default the session name to the directory basename
create the session detached
use the chosen directory for every initial window with
```
tmux ... -c <dir>
```

Recommended windows:

```
agent
```
```
review
```
```
tests
```
```
servers
```
```
misc
```

Create the session detached and root every initial window at the chosen directory.

Then ask the user to reconnect in Moshi. Expected result: the session is visible in the tmux selector.

创建新会话时：

读取当前工作目录
询问一个简洁的问题：是否要从当前目录启动会话？
如果答案是否，询问目标目录
会话名称默认使用目录的basename
后台创建会话（detached模式）
所有初始窗口都使用
```
tmux ... -c <dir>
```
指定为选定目录

推荐窗口：

```
agent
```
```
review
```
```
tests
```
```
servers
```
```
misc
```

后台创建会话，并将所有初始窗口的根路径设置为选定目录。

之后请用户在Moshi中重新连接。预期结果：会话在tmux选择器中可见。

4. Optional

moshi DIR

Helper

4. 可选

moshi DIR

辅助工具

Do not install this silently. Ask the user first if they want it.

If yes:

install a shell function named
```
moshi
```
in the correct startup file for the active shell
make it accept a directory argument, defaulting to
```
$PWD
```
name the tmux session from the directory basename
create the standard detached session layout only if the session does not already exist
attach to the session afterward

Use the exact function from

references/moshi-shell-function.md

不要静默安装此工具，需先询问用户是否需要。

如果用户同意：

在当前活跃shell对应的正确启动文件中安装名为
```
moshi
```
的shell函数
让它支持接收目录参数，默认值为
```
$PWD
```
tmux会话名称使用目录的basename
仅当会话不存在时才创建标准的后台会话布局
创建完成后附着到该会话

使用

references/moshi-shell-function.md

中的官方函数实现。

5. Agent Hooks

5. Agent钩子

Use

moshi-hooks

, not hand-written config, unless the user explicitly wants manual edits.

Core commands:

bash

bunx moshi-hooks setup
bunx moshi-hooks token <YOUR_TOKEN>

Optional integrations:

bash

bunx moshi-hooks setup --local
bunx moshi-hooks setup .
bunx moshi-hooks setup --codex
bunx moshi-hooks setup --opencode

Final verification:

run a short real agent task
confirm Moshi receives a push notification or Live Activity update

除非用户明确要求手动编辑，否则使用

moshi-hooks

而非手写配置。

核心命令：

bash

bunx moshi-hooks setup
bunx moshi-hooks token <YOUR_TOKEN>

可选集成命令：

bash

bunx moshi-hooks setup --local
bunx moshi-hooks setup .
bunx moshi-hooks setup --codex
bunx moshi-hooks setup --opencode

最终验证：

运行一个简短的实际Agent任务
确认Moshi收到推送通知或实时活动更新

moshi-best-practices

Original

Translation

Moshi Best Practices

Moshi最佳实践

Rules

规则

1. Host Readiness

1. 主机就绪检查

2. tmux Environment

2. tmux环境配置

3. tmux Project Session

3. tmux项目会话

4. Optional
`moshi DIR`
Helper

4. 可选
`moshi DIR`
辅助工具

5. Agent Hooks

5. Agent钩子

moshi-best-practices

Original

Translation

Moshi Best Practices

Moshi最佳实践

Rules

规则

1. Host Readiness

1. 主机就绪检查

2. tmux Environment

2. tmux环境配置

3. tmux Project Session

3. tmux项目会话

4. Optional moshi DIR Helper

4. 可选moshi DIR辅助工具

5. Agent Hooks

5. Agent钩子

4. Optional
`moshi DIR`
Helper

4. 可选
`moshi DIR`
辅助工具