新建、恢复、重命名、删除

会话是什么

会话是某个工作目录下持久保存的对话：你的提示、助手的回复、工具调用、TODO 列表、回退点，以及 token 计数。Matcha CLI 给每个会话一个 session ID（默认 UUIDv7；新建时传入 -s 可指定），并存在 ~/.matcha/sessions/。用 MATCHA_HOME 可改这个主目录。

启动 matcha 就已经开始一个会话。需要第二个会话，或要把昨天的工作接回来时，用下面的命令。

开始新会话：`/new`

在已打开的对话里：

/new

别名：/clear。

这会清空屏幕上的上下文，并开始新对话。上一个会话仍留在磁盘上，除非你删除它。/new 不接受参数。

要离开当前对话但仍留在 Matcha CLI，用 /home（别名 /welcome），不要用 /new。要彻底退出，用 /quit（别名 /exit）。

继续最近一次会话：`matcha -c`

在你上次工作的项目目录里：

matcha -c

也就是 --continue。它会重新打开当前工作目录最近一次会话——不带提示时进 TUI，同时传 -p 则走无界面。

matcha -c
matcha -p "What were we doing?" -c

恢复指定会话

在 TUI 里：`/resume`

/resume

该命令不接受参数。它会打开本工作区最近会话的选择器。

1. 输入文字可按标题过滤。选择器也会搜对话内容；这些命中出现在 **Extended search results** 下。
2. 按 Ctrl+/ 立即搜索，不必等那一小段停顿。
3. 选中一行即可恢复。

欢迎屏也列出同一批最近会话。可以直接在那里选，不必再跑 /resume。

在终端里：`matcha --resume`

matcha --resume
matcha --resume <session-id-or-title>

短选项：-r。

• 不带值（或只写 matcha --resume）会恢复本目录最近一次会话，思路与 matcha -c 相同。
• 看起来像 UUID 的值一律当作 session ID，不会当成标题。
• 其他值按本目录的标题匹配，忽略大小写。/rename 之后会方便很多。若多个会话同名，唯一一个**手动重命名过的**会话优先；否则命令报错并列出匹配的 ID。

脚本应传入 session ID。隐藏别名 --load <SESSION_ID> 只走 ID 这条路径。

重命名：`/rename`

/rename <title>

别名：/title。标题必填。必须有活动会话。

新标题会出现在 --resume 和选择器里。若打算用语词而不是 ID 找回会话，离开前先重命名。

删除

当前会话：`/delete`

/delete

Matcha CLI 会先询问。确认后会停下当前轮、后台任务和子助手，再删掉历史。你会回到欢迎屏；若会话是从看板打开的，则回到看板。

/delete 没有参数，且需要活动会话。

从列表删除其他会话

• 在 /resume 或欢迎屏的会话列表：按 d，再按 y。
• 在助手看板：连按两次 Ctrl+X，或点 [✗]。

在终端里：`matcha sessions delete`

matcha sessions delete <session-id>

ID 来自 matcha sessions list。该命令会跨工作区查找 ID（不必回到原来的目录）。

在终端里列出与搜索

matcha sessions 必须带子命令：

matcha sessions list
matcha sessions list --limit 50
matcha sessions search "rate limit"

list（默认 --limit 20）列出当前工作目录的会话，按 worktree 标签分组。每行有 session ID、创建与更新日期、来源列，以及一句摘要。

search 在本地索引里匹配标题和提示。用它找到 ID，再 --resume 该 ID，或 delete 它。

你应该看到