asciinema-recorder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

asciinema-recorder

Generate ready-to-copy commands for recording Claude Code sessions with asciinema. Dynamically creates filenames based on workspace and datetime.

Platform: macOS, Linux (requires asciinema CLI)

生成可直接复制的命令，用于使用asciinema录制Claude Code会话。根据工作区和日期时间动态生成文件名。

平台：macOS、Linux（需要asciinema CLI）

When to Use This Skill

何时使用此技能

Use this skill when:

Starting a new terminal recording session
Creating demos or documentation recordings
Capturing Claude Code sessions for review or sharing
Generating workspace-specific recording filenames

在以下场景使用此技能：

启动新的终端录制会话时
创建演示或文档录制内容时
捕获Claude Code会话用于回顾或分享时
生成特定于工作区的录制文件名时

Why This Skill?

为什么选择此技能？

This skill generates ready-to-copy recording commands with:

Dynamic workspace-based filename
Datetime stamp for uniqueness
Saves to project's tmp/ folder (gitignored)

此技能生成可直接复制的录制命令，具备以下特性：

基于工作区的动态文件名
确保唯一性的日期时间戳
保存到项目的tmp/文件夹（已被git忽略）

Requirements

要求

Component	Required	Installation
asciinema CLI	Yes	`brew install asciinema`

组件	是否必需	安装方式
asciinema CLI	是	`brew install asciinema`

Workflow Phases

工作流阶段

Phase 0: Preflight Check

阶段0：预检检查

Purpose: Verify asciinema is installed.

bash

undefined

目的：验证asciinema是否已安装。

bash

undefined

Check asciinema CLI

检查asciinema CLI

which asciinema && asciinema --version


If asciinema is NOT installed, use AskUserQuestion:

- question: "asciinema not found. How would you like to proceed?"
  header: "Setup"
  multiSelect: false
  options:
  - label: "Install asciinema (Recommended)"
    description: "Run: brew install asciinema (macOS) or apt install asciinema (Linux)"
  - label: "Show manual instructions"
    description: "Display installation commands for all platforms"
  - label: "Cancel"
    description: "Exit without recording"

Based on selection:

- **"Install asciinema"** → Run appropriate install command based on OS:

  ```bash
  # macOS
  brew install asciinema

  # Linux (apt)
  sudo apt install asciinema

  # Linux (pip)
  pip install asciinema

Then proceed to Phase 1.0.

"Show manual instructions" → Display the commands above, then exit skill.
"Cancel" → Exit skill without action.

which asciinema && asciinema --version


如果未安装asciinema，使用AskUserQuestion：

- 问题："未找到asciinema。您希望如何继续？"
  标题："设置"
  多选：否
  选项：
  - 标签："安装asciinema（推荐）"
    描述："执行：brew install asciinema（macOS）或apt install asciinema（Linux）"
  - 标签："显示手动安装说明"
    描述："展示全平台的安装命令"
  - 标签："取消"
    描述："退出且不进行录制"

根据选择执行：

- **"安装asciinema"** → 根据操作系统运行相应的安装命令：

  ```bash
  # macOS
  brew install asciinema

  # Linux（apt）
  sudo apt install asciinema

  # Linux（pip）
  pip install asciinema

然后进入阶段1.0。

"显示手动安装说明" → 展示上述命令，然后退出技能。
"取消" → 退出技能且不执行任何操作。

Phase 1.0: Recording Location

阶段1.0：录制位置选择

Purpose: Let user choose where to save the recording.

Use AskUserQuestion:

question: "Where should the recording be saved?" header: "Location" multiSelect: false options:
- label: "$PWD/tmp/ (Recommended)" description: "Project tmp directory (gitignored)"
- label: "~/asciinema/" description: "Global recordings directory"
- label: "Custom path" description: "Specify your own directory"

Based on selection:

"$PWD/tmp/" → Set
```
OUTPUT_DIR="$PWD/tmp"
```

"~/asciinema/" → Set

OUTPUT_DIR="$HOME/asciinema"

and create if missing:

mkdir -p ~/asciinema

"Custom path" → Use user's "Other" input as
```
OUTPUT_DIR
```

目的：让用户选择录制文件的保存位置。

使用AskUserQuestion：

问题："录制文件应保存到哪里？" 标题："位置" 多选：否选项：
- 标签："$PWD/tmp/（推荐）" 描述："项目临时目录（已被git忽略）"
- 标签："~/asciinema/" 描述："全局录制目录"
- 标签："自定义路径" 描述："指定您自己的目录"

根据选择设置：

"$PWD/tmp/" → 设置
```
OUTPUT_DIR="$PWD/tmp"
```
"~/asciinema/" → 设置
```
OUTPUT_DIR="$HOME/asciinema"
```
，若目录不存在则创建：
```
mkdir -p ~/asciinema
```
"自定义路径" → 将用户输入的其他路径设为
```
OUTPUT_DIR
```

Phase 1.1: Recording Options

阶段1.1：录制选项配置

Purpose: Let user configure recording behavior.

Use AskUserQuestion:

question: "Which recording options would you like?" header: "Options" multiSelect: true options:
- label: "Add title/description" description: "Include session title in recording metadata (-t flag)"
- label: "Disable idle time limit" description: "Keep full pauses instead of 2s max (--idle-time-limit 0)"
- label: "Quiet mode" description: "Suppress asciinema status messages (-q flag)"

Based on selections, build command flags:

"Add title" → Continue to title selection question, add
```
-t "title"
```
flag
"Disable idle time limit" → Add
```
--idle-time-limit 0
```
flag
"Quiet mode" → Add
```
-q
```
flag

If "Add title" was selected, follow up with:

question: "Enter a title for this recording:" header: "Title" multiSelect: false options:
- label: "Use workspace name" description: "Title: ${WORKSPACE}"
- label: "Use workspace + datetime" description: "Title: ${WORKSPACE} ${DATETIME}"
- label: "Custom title" description: "Enter your own title"

Based on title selection:

"Use workspace name" → Set
```
TITLE="${WORKSPACE}"
```
"Use workspace + datetime" → Set
```
TITLE="${WORKSPACE} ${DATETIME}"
```
"Custom title" → Use user's "Other" input as
```
TITLE
```

目的：让用户配置录制行为。

使用AskUserQuestion：

问题："您需要哪些录制选项？" 标题："选项" 多选：是选项：
- 标签："添加标题/描述" 描述："在录制元数据中包含会话标题（-t 参数）"
- 标签："禁用空闲时间限制" 描述："保留完整停顿，而非最多2秒（--idle-time-limit 0）"
- 标签："静默模式" 描述："抑制asciinema状态消息（-q 参数）"

根据选择构建命令参数：

"添加标题" → 继续进入标题选择环节，添加
```
-t "title"
```
参数
"禁用空闲时间限制" → 添加
```
--idle-time-limit 0
```
参数
"静默模式" → 添加
```
-q
```
参数

如果选择了"添加标题"，继续提问：

问题："为此录制输入一个标题：" 标题："标题" 多选：否选项：
- 标签："使用工作区名称" 描述："标题：${WORKSPACE}"
- 标签："使用工作区+日期时间" 描述："标题：${WORKSPACE} ${DATETIME}"
- 标签："自定义标题" 描述："输入您自己的标题"

根据标题选择设置：

"使用工作区名称" → 设置
```
TITLE="${WORKSPACE}"
```
"使用工作区+日期时间" → 设置
```
TITLE="${WORKSPACE} ${DATETIME}"
```
"自定义标题" → 将用户输入的其他内容设为
```
TITLE
```

Phase 1.2: Detect Context & Generate Command

阶段1.2：检测上下文并生成命令

Purpose: Generate a copy-paste ready recording command.

目的：生成可直接复制粘贴的录制命令。

Step 1.2.1: Detect Workspace

步骤1.2.1：检测工作区

Extract workspace name from

$PWD

bash

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
WORKSPACE=$(basename "$PWD")
echo "Workspace: $WORKSPACE"
SKILL_SCRIPT_EOF

从

$PWD

中提取工作区名称：

bash

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
WORKSPACE=$(basename "$PWD")
echo "Workspace: $WORKSPACE"
SKILL_SCRIPT_EOF

Step 1.2.2: Generate Datetime

步骤1.2.2：生成日期时间戳

bash

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
DATETIME=$(date +%Y-%m-%d_%H-%M)
echo "Datetime: $DATETIME"
SKILL_SCRIPT_EOF_2

bash

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
DATETIME=$(date +%Y-%m-%d_%H-%M)
echo "Datetime: $DATETIME"
SKILL_SCRIPT_EOF_2

Step 1.2.3: Ensure Output Directory Exists

步骤1.2.3：确保输出目录存在

Create the output directory selected in Phase 1.0:

bash

mkdir -p "${OUTPUT_DIR}"

创建阶段1.0中选择的输出目录：

bash

mkdir -p "${OUTPUT_DIR}"

Step 1.2.4: Construct Command

步骤1.2.4：构建命令

Build the recording command using:

```
OUTPUT_DIR
```
from Phase 1.0 (location selection)
Flags from Phase 1.1 (options selection)
```
TITLE
```
if "Add title" was selected

bash

undefined

使用以下内容构建录制命令：

阶段1.0中选择的
```
OUTPUT_DIR
```
（位置选择）
阶段1.1中选择的参数（选项配置）
若选择了"添加标题"则使用
```
TITLE
```

bash

undefined

Base command

基础命令

CMD="asciinema rec"

Add flags from Phase 1.1 options

添加阶段1.1选项中的参数

(Claude builds this based on user selections)

（Claude会根据用户选择构建）

Final command format:

最终命令格式：

asciinema rec ${FLAGS} "${OUTPUT_DIR}/${WORKSPACE}_${DATETIME}.cast"


**Example outputs:**

```bash

asciinema rec ${FLAGS} "${OUTPUT_DIR}/${WORKSPACE}_${DATETIME}.cast"


**示例输出**：

```bash

Default (no options selected):

默认（未选择任何选项）：

asciinema rec /home/user/projects/my-app/tmp/my-app_2025-12-21_14-30.cast

With title + quiet mode:

带标题+静默模式：

asciinema rec -t "my-app Demo" -q /home/user/projects/my-app/tmp/my-app_2025-12-21_14-30.cast

With all options:

带所有选项：

asciinema rec -t "my-app 2025-12-21 14:30" -q --idle-time-limit 0 ~/asciinema/my-app_2025-12-21_14-30.cast

---

asciinema rec -t "my-app 2025-12-21 14:30" -q --idle-time-limit 0 ~/asciinema/my-app_2025-12-21_14-30.cast

---

Phase 2: User Guidance

阶段2：用户指导

Purpose: Explain the recording workflow step-by-step.

Present these instructions:

markdown

undefined

目的：分步解释录制工作流。

展示以下说明：

markdown

undefined

Recording Instructions

录制说明

Exit Claude Code - Type
```
exit
```
or press
```
Ctrl+D
```
Copy the command shown above
Paste and run in your terminal (starts a recorded shell)
Run
claude
to start Claude Code inside the recording
Work normally - everything is captured
Exit Claude Code - Type
```
exit
```
or press
```
Ctrl+D
```
Exit the recording shell - Type
```
exit
```
or press
```
Ctrl+D
```
again

Your recording will be saved to:

$PWD/tmp/{workspace}_{datetime}.cast

---

退出Claude Code - 输入
```
exit
```
或按
```
Ctrl+D
```
复制命令 - 复制上方展示的命令
粘贴并运行 - 在终端中粘贴并运行（启动录制的shell）
运行
claude
- 在录制环境中启动Claude Code
正常操作 - 所有操作都会被捕获
退出Claude Code - 输入
```
exit
```
或按
```
Ctrl+D
```
退出录制shell - 再次输入
```
exit
```
或按
```
Ctrl+D
```

您的录制文件将保存到：

$PWD/tmp/{workspace}_{datetime}.cast

---

Phase 3: Additional Info

阶段3：附加信息

Purpose: Provide helpful tips for after recording.

markdown

undefined

目的：提供录制后的实用技巧。

markdown

undefined

Tips

技巧

Environment variable:
```
ASCIINEMA_REC=1
```
is set during recording

Playback: Use

asciinema-player

skill or

asciinema play file.cast

Upload (optional):
```
asciinema upload file.cast
```
(requires account)
Markers: Add
```
asciinema marker
```
during recording for navigation points

---

环境变量：录制期间会设置
```
ASCIINEMA_REC=1
```

播放：使用

asciinema-player

技能或

asciinema play file.cast

上传（可选）：
```
asciinema upload file.cast
```
（需要账号）
标记：录制期间添加
```
asciinema marker
```
以设置导航点

---

TodoWrite Task Templates

TodoWrite任务模板

Template: Record Claude Code Session

模板：录制Claude Code会话

1. [Preflight] Check asciinema CLI installed
2. [Preflight] Offer installation if missing
3. [Context] Detect current workspace from $PWD
4. [Context] Generate datetime slug
5. [Context] Ensure tmp/ directory exists
6. [Command] Construct full recording command
7. [Guidance] Display step-by-step instructions
8. [Guidance] Show additional tips (playback, upload)
9. Verify against Skill Quality Checklist

1. [预检] 检查asciinema CLI是否已安装
2. [预检] 若未安装则提供安装选项
3. [上下文] 从$PWD检测当前工作区
4. [上下文] 生成日期时间标识
5. [上下文] 确保tmp/目录存在
6. [命令] 构建完整的录制命令
7. [指导] 展示分步说明
8. [指导] 展示附加技巧（播放、上传）
9. 根据技能质量检查表验证

Post-Change Checklist

变更后检查表

After modifying this skill:

Command generation still uses
```
$PWD
```
(no hardcoded paths)
Guidance steps remain clear and platform-agnostic
TodoWrite template matches actual workflow
README.md entry remains accurate
Validate with quick_validate.py

修改此技能后：

命令生成仍使用
```
$PWD
```
（无硬编码路径）
指导步骤保持清晰且平台无关
TodoWrite模板与实际工作流匹配
README.md条目保持准确
使用quick_validate.py验证

CLI Options Reference

CLI选项参考

Option	Flag	Description
Title	`-t`	Recording title (for asciinema.org)
Quiet	`-q`	Suppress status messages
Append	`-a`	Append to existing recording

选项	参数	描述
标题	`-t`	录制标题（用于asciinema.org）
静默	`-q`	抑制状态消息
追加	`-a`	追加到现有录制文件

Troubleshooting

故障排除

"Cannot record from within Claude Code"

"无法在Claude Code内部录制"

Cause: asciinema must wrap the program, not be started from inside.

Fix: Exit Claude Code first, then run the generated command.

原因：asciinema必须包裹程序，而非从程序内部启动。

解决方法：先退出Claude Code，再运行生成的命令。

"Recording file too large"

"录制文件过大"

Cause: Long sessions produce large files.

Fix:

Use
```
asciinema upload
```
to store online instead of locally
Split long sessions into smaller recordings

原因：长时间会话会生成大文件。

解决方法：

使用
```
asciinema upload
```
将文件存储在线而非本地
将长会话拆分为多个较小的录制

"Playback shows garbled output"

"播放时显示乱码输出"

Cause: Terminal size mismatch.

Fix: Use

-r

flag during playback to resize terminal.

原因：终端大小不匹配。

解决方法：播放时使用

-r

参数调整终端大小。

asciinema-recorder

Original

Translation

asciinema-recorder

asciinema-recorder

When to Use This Skill

何时使用此技能

Why This Skill?

为什么选择此技能？

Requirements

要求

Workflow Phases

工作流阶段

Phase 0: Preflight Check

阶段0：预检检查

Check asciinema CLI

检查asciinema CLI

Phase 1.0: Recording Location

阶段1.0：录制位置选择

Phase 1.1: Recording Options

阶段1.1：录制选项配置

Phase 1.2: Detect Context & Generate Command

阶段1.2：检测上下文并生成命令

Step 1.2.1: Detect Workspace

步骤1.2.1：检测工作区

Step 1.2.2: Generate Datetime

步骤1.2.2：生成日期时间戳

Step 1.2.3: Ensure Output Directory Exists

步骤1.2.3：确保输出目录存在

Step 1.2.4: Construct Command

步骤1.2.4：构建命令

Base command

基础命令

Add flags from Phase 1.1 options

添加阶段1.1选项中的参数

(Claude builds this based on user selections)

（Claude会根据用户选择构建）

Final command format:

最终命令格式：

Default (no options selected):

默认（未选择任何选项）：

With title + quiet mode:

带标题+静默模式：

With all options:

带所有选项：

Phase 2: User Guidance

阶段2：用户指导

Recording Instructions

录制说明

Phase 3: Additional Info

阶段3：附加信息

Tips

技巧

TodoWrite Task Templates

TodoWrite任务模板

Template: Record Claude Code Session

模板：录制Claude Code会话

Post-Change Checklist

变更后检查表

CLI Options Reference

CLI选项参考

Troubleshooting

故障排除

"Cannot record from within Claude Code"

"无法在Claude Code内部录制"

"Recording file too large"

"录制文件过大"

"Playback shows garbled output"

"播放时显示乱码输出"

Reference Documentation

参考文档