Back to Details

swain-session

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- swain-model-hint: haiku, effort: low -->
<!-- swain-model-hint: haiku, effort: low -->

Session

会话

Manages session identity, preferences, and context continuity across agent sessions. This skill is agent-agnostic — it relies on AGENTS.md for auto-invocation.
在Agent会话之间管理会话标识、偏好设置和上下文连续性。该Skill与Agent无关——它依赖AGENTS.md实现自动调用。

Auto-run behavior

自动运行行为

This skill is invoked automatically at session start (see AGENTS.md). When auto-invoked:
  1. Restore tab name — run the tab-naming script
  2. Load preferences — read session.json and apply any stored preferences
  3. Show context bookmark — if a previous session left a context note, display it
When invoked manually, the user can change preferences or bookmark context.
该Skill会在会话启动时自动调用（详见AGENTS.md）。自动调用时：
  1. 恢复标签页名称 —— 运行标签页命名脚本
  2. 加载偏好设置 —— 读取session.json并应用所有已存储的偏好设置
  3. 显示上下文书签 —— 如果上一次会话留下了上下文注释，则将其显示出来
手动调用时，用户可以修改偏好设置或添加上下文书签。

Step 1 — Set terminal tab name (tmux only)

步骤1 —— 设置终端标签页名称（仅支持tmux）

Check if 
$TMUX
is set. If yes, run the tab-naming script:
bash
bash "$(dirname "$0")/../skills/swain-session/scripts/swain-tab-name.sh" --auto
Use the project root to locate the script. The script reads 
swain.settings.json
for the tab name format (default: 
{project} @ {branch}
).
If this fails (e.g., not in a git repo), set a fallback title of "swain".
If 
$TMUX
is NOT set, skip tab naming and show this tip:
Tip: Tab naming and workspace layouts require tmux. Run 
tmux
before starting Claude Code to enable 
/swain-session
tab naming and 
/swain-stage
layouts.
检查是否设置了
$TMUX
。如果已设置，运行标签页命名脚本：
bash
bash "$(dirname "$0")/../skills/swain-session/scripts/swain-tab-name.sh" --auto
使用项目根目录定位脚本。该脚本会读取
swain.settings.json
获取标签页名称格式（默认：
{project} @ {branch}
）。
如果此操作失败（例如，不在Git仓库中），则将回退标题设置为“swain”。
如果未设置
$TMUX
，跳过标签页命名并显示以下提示：
提示： 标签页命名和工作区布局需要tmux支持。在启动Claude Code前运行
tmux
，即可启用
/swain-session
标签页命名和
/swain-stage
布局功能。

Step 2 — Load session preferences

步骤2 —— 加载会话偏好设置

Read the session state file. The file location is:
<project-root>/.agents/session.json
This keeps session state per-project, version-controlled, and visible to collaborators.
Migration: If 
.agents/session.json
does not exist but the old global location (
~/.claude/projects/<project-path-slug>/memory/session.json
) does, copy it to 
.agents/session.json
on first access.
The session.json schema:
json
{
  "lastBranch": "main",
  "lastContext": "Working on swain-session skill",
  "preferences": {
    "verbosity": "concise"
  },
  "bookmark": {
    "note": "Left off implementing the MOTD animation",
    "files": ["skills/swain-stage/scripts/swain-motd.sh"],
    "timestamp": "2026-03-10T14:32:00Z"
  }
}
If the file exists:
  • Read and apply preferences (currently informational — future skills can check these)
  • If 
    bookmark
    exists and has a 
    note
    , display it to the user:
    Resuming session — Last time: {note} Files: {files list, if any}
  • Update 
    lastBranch
    to the current branch
If the file does not exist, create it with defaults.
读取会话状态文件。文件位置为：
<project-root>/.agents/session.json
这样可以按项目保存会话状态，支持版本控制，并且对协作者可见。
迁移： 如果
.agents/session.json
不存在，但旧的全局位置（
~/.claude/projects/<project-path-slug>/memory/session.json
）存在，则在首次访问时将其复制到
.agents/session.json
。
session.json的 schema：
json
{
  "lastBranch": "main",
  "lastContext": "Working on swain-session skill",
  "preferences": {
    "verbosity": "concise"
  },
  "bookmark": {
    "note": "Left off implementing the MOTD animation",
    "files": ["skills/swain-stage/scripts/swain-motd.sh"],
    "timestamp": "2026-03-10T14:32:00Z"
  }
}
如果文件存在：
  • 读取并应用偏好设置（目前仅作信息展示——未来的Skill可读取这些设置）
  • 如果
    bookmark
    存在且包含
    note
    ，则向用户显示：
    恢复会话 —— 上次进度：{note} 相关文件：{文件列表（如果有）}
  • 将
    lastBranch
    更新为当前分支
如果文件不存在，则使用默认值创建该文件。

Step 3 — Suggest swain-stage (tmux only)

步骤3 —— 推荐使用swain-stage（仅支持tmux）

If 
$TMUX
is set and swain-stage is available, inform the user:
Run 
/swain-stage
to set up your workspace layout.
Do not auto-invoke swain-stage — let the user decide.
如果已设置
$TMUX
且swain-stage可用，则向用户提示：
运行
/swain-stage
以设置你的工作区布局。
不要自动调用swain-stage——由用户自行决定是否使用。

Manual invocation commands

手动调用命令

When invoked explicitly by the user, support these operations:
当用户显式调用该Skill时，支持以下操作：

Set tab name

设置标签页名称

User says something like "set tab name to X" or "rename tab":
bash
bash skills/swain-session/scripts/swain-tab-name.sh "Custom Name"
用户输入类似“将标签页名称设置为X”或“重命名标签页”的指令时：
bash
bash skills/swain-session/scripts/swain-tab-name.sh "Custom Name"

Bookmark context

添加上下文书签

User says "remember where I am" or "bookmark this":
  • Ask what they're working on (or infer from conversation context)
  • Write to session.json 
    bookmark
    field with note, relevant files, and timestamp
用户输入“记住我的当前进度”或“添加书签”的指令时：
  • 询问他们正在处理的内容（或从对话上下文推断）
  • 将注释、相关文件和时间戳写入session.json的
    bookmark
    字段

Clear bookmark

清除书签

User says "clear bookmark" or "fresh start":
  • Remove the 
    bookmark
    field from session.json
用户输入“清除书签”或“重新开始”的指令时：
  • 从session.json中移除
    bookmark
    字段

Show session info

显示会话信息

User says "session info" or "what's my session":
  • Display current tab name, branch, preferences, bookmark status
用户输入“会话信息”或“我的会话状态”的指令时：
  • 显示当前标签页名称、分支、偏好设置和书签状态

Set preference

设置偏好

User says "set preference X to Y":
  • Update 
    preferences
    in session.json
用户输入“将偏好X设置为Y”的指令时：
  • 更新session.json中的
    preferences
    字段

Post-operation bookmark (auto-update protocol)

操作后书签（自动更新协议）

Other swain skills update the session bookmark after completing operations. This gives the developer a "where I left off" marker without requiring manual bookmarking.
其他Swain Skill会在完成操作后更新会话书签。这样无需手动添加书签，即可为开发者提供“上次中断位置”的标记。

When to update

更新时机

A skill should update the bookmark when it completes a state-changing operation — artifact transitions, task updates, commits, releases, or status checks.
当Skill完成状态变更操作（例如工件流转、任务更新、提交、发布或状态检查）时，应更新书签。

How to update

更新方式

Use 
skills/swain-session/scripts/swain-bookmark.sh
:
bash
undefined
使用
skills/swain-session/scripts/swain-bookmark.sh
：
bash
undefined

Find the script

查找脚本

BOOKMARK_SCRIPT="$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)"
BOOKMARK_SCRIPT="$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)"

Basic note

基础注释

bash "$BOOKMARK_SCRIPT" "Transitioned SPEC-001 to Approved"
bash "$BOOKMARK_SCRIPT" "Transitioned SPEC-001 to Approved"

Note with files

带文件的注释

bash "$BOOKMARK_SCRIPT" "Implemented auth middleware" --files src/auth.ts src/auth.test.ts
bash "$BOOKMARK_SCRIPT" "Implemented auth middleware" --files src/auth.ts src/auth.test.ts

Clear bookmark

清除书签

bash "$BOOKMARK_SCRIPT" --clear

The script handles session.json discovery, atomic writes, and graceful degradation (no jq = silent no-op).
bash "$BOOKMARK_SCRIPT" --clear

该脚本会处理session.json的查找、原子写入和优雅降级（无jq时静默跳过操作）。

Settings

设置

This skill reads from 
swain.settings.json
(project root) and 
~/.config/swain/settings.json
(user override). User settings take precedence.
Relevant settings:
  • terminal.tabNameFormat
    — format string for tab names. Supports 
    {project}
    and 
    {branch}
    placeholders. Default: 
    {project} @ {branch}
该Skill会从项目根目录的
swain.settings.json
和用户目录下的
~/.config/swain/settings.json
（用户覆盖配置）读取设置。用户设置优先级更高。
相关设置：
  • terminal.tabNameFormat
    —— 标签页名称的格式字符串。支持
    {project}
    和
    {branch}
    占位符。默认值：
    {project} @ {branch}

Error handling

错误处理

  • If jq is not available, warn the user and skip JSON operations. Tab naming still works without jq.
  • If git is not available, use the directory name as the project name and skip branch detection.
  • Never fail hard — session management is a convenience, not a gate.
  • 如果jq不可用，向用户发出警告并跳过JSON操作。标签页命名功能无需jq即可正常工作。
  • 如果Git不可用，使用目录名称作为项目名称并跳过分支检测。
  • 绝不强制终止——会话管理是一项便利功能，而非准入门槛。