swain-stage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stage

Tmux workspace manager for swain. Creates pane layouts, manages an animated MOTD status panel, and gives the agent direct control over the visual workspace.

Prerequisite: Must be running inside a tmux session (

$TMUX

must be set). If not in tmux, inform the user and exit gracefully.

面向Swain的Tmux工作区管理器。创建面板布局，管理动态MOTD状态面板，并让Agent能够直接控制可视化工作区。

前提条件： 必须在tmux会话中运行（必须设置

$TMUX

环境变量）。如果不在tmux中，需告知用户并优雅退出。

Script location

脚本位置

All scripts live in this skill's

scripts/

directory:

```
swain-stage.sh
```
— main tmux layout and pane manager
```
swain-motd.py
```
— MOTD status panel (Textual TUI, runs via
```
uv run
```
)
```
swain-motd.sh
```
— legacy bash MOTD (kept as fallback if uv/Textual unavailable)

Resolve the script directory from this skill's install path.

所有脚本都位于该Skill的

scripts/

目录下：

```
swain-stage.sh
```
— 主tmux布局和面板管理器
```
swain-motd.py
```
— MOTD状态面板（Textual TUI，通过
```
uv run
```
运行）
```
swain-motd.sh
```
— 旧版bash实现的MOTD（当uv/Textual不可用时作为备用）

从该Skill的安装路径解析脚本目录。

Commands

命令

Layout presets

布局预设

Apply a named layout. Available presets are in

references/layouts/

Layout	Description
focus	Agent pane + MOTD top-right + file browser bottom-right
review	Agent + editor (changed files) + MOTD
browse	Agent + file browser + MOTD

bash

bash scripts/swain-stage.sh layout review
bash scripts/swain-stage.sh layout browse
bash scripts/swain-stage.sh layout focus

The default layout is configured in

swain.settings.json

under

stage.defaultLayout

(default:

focus

Users can override layout definitions in

swain.settings.json

under

stage.layouts.<name>

应用命名布局。可用预设位于

references/layouts/

目录中：

布局	描述
focus	Agent面板 + 右上角MOTD + 右下角文件浏览器
review	Agent + 编辑器（已修改文件） + MOTD
browse	Agent + 文件浏览器 + MOTD

bash

bash scripts/swain-stage.sh layout review
bash scripts/swain-stage.sh layout browse
bash scripts/swain-stage.sh layout focus

默认布局在

swain.settings.json

的

stage.defaultLayout

中配置（默认值：

focus

）。

用户可在

swain.settings.json

的

stage.layouts.<name>

中覆盖布局定义。

Open individual panes

打开单个面板

Open a specific pane type without applying a full layout:

bash

bash scripts/swain-stage.sh pane editor file1.py file2.py   # editor with specific files
bash scripts/swain-stage.sh pane browser                      # file browser at repo root
bash scripts/swain-stage.sh pane browser /some/path           # file browser at specific path
bash scripts/swain-stage.sh pane motd                         # MOTD status panel
bash scripts/swain-stage.sh pane shell                        # plain shell

无需应用完整布局，直接打开特定类型的面板：

bash

bash scripts/swain-stage.sh pane editor file1.py file2.py   # 打开编辑器并加载指定文件
bash scripts/swain-stage.sh pane browser                      # 在仓库根目录打开文件浏览器
bash scripts/swain-stage.sh pane browser /some/path           # 在指定路径打开文件浏览器
bash scripts/swain-stage.sh pane motd                         # 打开MOTD状态面板
bash scripts/swain-stage.sh pane shell                        # 打开普通Shell面板

MOTD management

MOTD管理

The MOTD pane shows a dynamic status panel with:

Project name, branch, and dirty state
Animated spinner when the agent is working (braille, dots, or bar style)
Current agent context (what it's doing)
Active epic with progress ratio (from swain-status cache)
Active bd task
Ready (actionable) artifact count
Last commit info
Assigned GitHub issue count
Count of touched files

The MOTD is a Textual TUI app (

swain-motd.py

) launched via

uv run

. It reads project data from

status-cache.json

(written by swain-status) when available, falling back to direct git/bd queries when the cache is absent or stale (>5 min). Agent state (spinner, context) is always read from

stage-status.json

for real-time responsiveness. Textual handles Unicode width correctly, provides proper box drawing with rounded corners, and supports color theming.

Control the MOTD:

bash

bash scripts/swain-stage.sh motd start                        # start MOTD in a new pane
bash scripts/swain-stage.sh motd stop                         # kill the MOTD pane
bash scripts/swain-stage.sh motd update "reviewing auth module"  # update context
bash scripts/swain-stage.sh motd update "idle"                # mark as idle
bash scripts/swain-stage.sh motd update "done"                # mark as done/idle

MOTD面板显示动态状态信息，包括：

项目名称、分支和脏状态
Agent工作时的动态加载动画（盲文、点状或条状样式）
当前Agent的上下文（正在执行的任务）
进行中的Epic及进度占比（来自swain-status缓存）
活跃的bd任务
可操作的工件数量
最后一次提交信息
已分配的GitHub问题数量
已修改文件的数量

MOTD是一个Textual TUI应用（

swain-motd.py

），通过

uv run

启动。当

status-cache.json

（由swain-status生成）可用时，它会从中读取项目数据；如果缓存不存在或已过期（超过5分钟），则回退到直接查询git/bd。Agent状态（加载动画、上下文）始终从

stage-status.json

读取，以保证实时响应。Textual能够正确处理Unicode宽度，提供带圆角的标准边框绘制，并支持颜色主题定制。

控制MOTD：

bash

bash scripts/swain-stage.sh motd start                        # 在新面板中启动MOTD
bash scripts/swain-stage.sh motd stop                         # 关闭MOTD面板
bash scripts/swain-stage.sh motd update "reviewing auth module"  # 更新上下文信息
bash scripts/swain-stage.sh motd update "idle"                # 标记为空闲状态
bash scripts/swain-stage.sh motd update "done"                # 标记为完成/空闲状态

Close panes

关闭面板

bash

bash scripts/swain-stage.sh close right     # close the right pane
bash scripts/swain-stage.sh close bottom    # close the bottom pane
bash scripts/swain-stage.sh close all       # reset to single pane

bash

bash scripts/swain-stage.sh close right     # 关闭右侧面板
bash scripts/swain-stage.sh close bottom    # 关闭底部面板
bash scripts/swain-stage.sh close all       # 重置为单个面板

Status

状态查询

bash

bash scripts/swain-stage.sh status          # show current layout info

bash

bash scripts/swain-stage.sh status          # 显示当前布局信息

Reset

重置

bash

bash scripts/swain-stage.sh reset           # kill all panes except current

bash

bash scripts/swain-stage.sh reset           # 关闭当前面板以外的所有面板

Agent-triggered pane operations

Agent触发的面板操作

The agent should use swain-stage directly during work. Recommended patterns:

Agent应在工作期间直接使用swain-stage。推荐使用模式：

After making changes — open review

修改完成后——打开审阅面板

When you've finished modifying files, open them for the user to review:

bash

bash scripts/swain-stage.sh motd update "changes ready for review"
bash scripts/swain-stage.sh pane editor file1.py file2.py

当你完成文件修改后，打开文件供用户审阅：

bash

bash scripts/swain-stage.sh motd update "changes ready for review"
bash scripts/swain-stage.sh pane editor file1.py file2.py

During research — open file browser

研究期间——打开文件浏览器

When exploring the codebase:

bash

bash scripts/swain-stage.sh pane browser src/components/

探索代码库时：

bash

bash scripts/swain-stage.sh pane browser src/components/

Update context as you work

工作时更新上下文

Keep the MOTD informed of what you're doing:

bash

bash scripts/swain-stage.sh motd update "analyzing test failures"
bash scripts/swain-stage.sh motd update "writing migration script"
bash scripts/swain-stage.sh motd update "done"

随时更新MOTD以告知用户当前工作内容：

bash

bash scripts/swain-stage.sh motd update "analyzing test failures"
bash scripts/swain-stage.sh motd update "writing migration script"
bash scripts/swain-stage.sh motd update "done"

Clean up when done

完成工作后清理

bash

bash scripts/swain-stage.sh close right
bash scripts/swain-stage.sh motd update "idle"

bash

bash scripts/swain-stage.sh close right
bash scripts/swain-stage.sh motd update "idle"

Settings

设置

Read from

swain.settings.json

(project) and

~/.config/swain/settings.json

(user override). User settings take precedence.

Key	Type	Default	Description
`editor`	string	`auto`	Editor command. `auto` detects: micro > helix > nano > vim
`fileBrowser`	string	`auto`	File browser command. `auto` detects: yazi > nnn > ranger > mc
`stage.defaultLayout`	string	`focus`	Layout applied by default
`stage.motd.refreshInterval`	number	`5`	MOTD refresh interval in seconds (idle)
`stage.motd.spinnerStyle`	string	`braille`	Spinner animation: `braille` , `dots` , or `bar`
`stage.layouts`	object	`{}`	User-defined layout overrides (same schema as preset files)

从项目级

swain.settings.json

和用户级

~/.config/swain/settings.json

读取设置。用户级设置优先级更高。

键	类型	默认值	描述
`editor`	字符串	`auto`	编辑器命令。 `auto` 会自动检测优先级：micro > helix > nano > vim
`fileBrowser`	字符串	`auto`	文件浏览器命令。 `auto` 会自动检测优先级：yazi > nnn > ranger > mc
`stage.defaultLayout`	字符串	`focus`	默认应用的布局
`stage.motd.refreshInterval`	数字	`5`	MOTD空闲时的刷新间隔（秒）
`stage.motd.spinnerStyle`	字符串	`braille`	加载动画样式： `braille` 、 `dots` 或 `bar`
`stage.layouts`	对象	`{}`	用户自定义的布局覆盖（与预设文件 schema 一致）

Error handling

错误处理

If not in tmux: report clearly and exit. Do not attempt tmux commands.
If editor/file browser is not installed: warn the user and suggest alternatives or
```
swain.settings.json
```
override.
If jq is not available: warn that settings cannot be read, use hardcoded defaults.
Pane operations are best-effort — if a pane can't be created or found, warn but don't fail the session.

如果不在tmux中：清晰提示并退出，不执行任何tmux命令。
如果编辑器/文件浏览器未安装：警告用户并建议替代方案或通过
```
swain.settings.json
```
覆盖设置。
如果jq不可用：警告无法读取设置，使用硬编码默认值。
面板操作采用尽力而为原则——如果无法创建或找到面板，仅发出警告但不终止会话。