Skillget

agent-session-titles

agent
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push -1 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • spawnSync — Synchronous process spawning in bin/agent-session-titles.cjs
  • fs.rmSync — Destructive file system operation in bin/agent-session-titles.cjs
  • os.homedir — User home directory access in bin/agent-session-titles.cjs
  • process.env — Environment variable access in bin/agent-session-titles.cjs
  • fs module — File system access in bin/agent-session-titles.cjs
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

一条命令为 Codex 与 Claude Code 安装三段式会话标题插件

README.md

Agent Session Titles（会话标题自动更新）

简体中文 | English

LINUX DO

为 Codex、Claude Code 和 DeepSeek Harness 的本地会话维护可选中文或英文的三段式标题：

状态｜初始需求｜当前进展
开发中｜会话标题自动化｜适配双端安装器
Building | Session titles | Add bilingual support

Codex CLI 中标题随对话进展自动更新

上图为 Codex CLI：每轮对话后，窗口标题和底部状态栏的会话标题随进展即时刷新。

中间段保留用户最初要解决的问题；DeepSeek Harness 的中间段按整个会话做简短摘要，而不是只复述首条需求。状态和末段在阶段变化时更新，无须等整个回合结束。当前支持的自动状态为「聊天、摸底、方案、开发中、测试、修复、待确认、已完成、搁置」。用户手动修改哪一段，插件就保留并锁定哪一段，其余段继续自动更新；手动状态词可以不在自动状态列表中。标题只有这三段，工作树和无项目会话都不额外加前缀或目录名。无法可靠拆分或确认来源的名称会整体保留；Claude Code 桌面端在首个标题确认前自动起的名字不算人工改名，插件会继续沿用自己的标题。

直接交给 Agent 安装

把下面这段话直接发给有本机终端权限的 Codex 或 Claude Code Agent。将“中文”改为“英文”即可选择英文；也可以将“两个客户端”改为“仅 Codex”或“仅 Claude Code”。Agent 会执行安装命令和检查步骤，你不需要自己打开终端。完整的中英文可复制版本见 Agent 安装说明；DeepSeek Harness 使用其中的 DSH 指令，或把目标改成 --dsh。

请从 https://github.com/panda-z519/agent-session-titles 安装本地会话标题插件，目标是两个客户端，标题使用中文。先检查本机 codex、claude、Node.js 20+ 和 Python 3.11+。执行 npx --yes github:panda-z519/agent-session-titles --both --lang zh --migrate，再核对安装结果和配置备份。--migrate 只用于备份并迁移旧版标题钩子，保留其他钩子。若缺少客户端或安装失败，说明具体原因，不声称成功。Codex 若要求信任新钩子，请让我在应用中检查并确认；完成后提醒我重启客户端并验证新本地会话。

自己运行命令安装

需要 macOS 或 Linux、Node.js 20+、Python 3.11+，以及要使用的客户端命令 codex、claude 或 dsh。选择一条命令运行：

自动安装本机已有的客户端（两者都有就安装两端）：

npx --yes github:panda-z519/agent-session-titles

只安装 Codex：

npx --yes github:panda-z519/agent-session-titles --codex

只安装 Claude Code：

npx --yes github:panda-z519/agent-session-titles --claude

明确要求两端都安装（缺少任一客户端命令就停止）：

npx --yes github:panda-z519/agent-session-titles --both

默认标题语言为中文。首次安装选择英文时加 --lang en；之后重跑时不指定语言会保留当前选择，切回中文可用 --lang zh：

--lang 控制插件钩子的标题格式、状态词和给 Agent 的提示。若你自己的全局 AGENTS.md 或 CLAUDE.md 仍强制另一种标题语言或“只在回复结束后更新”，安装器会提示疑似冲突的行，应同步调整；见下方全局规则文件。

npx --yes github:panda-z519/agent-session-titles --codex --lang en
npx --yes github:panda-z519/agent-session-titles --claude --lang zh

已有旧版独立标题钩子时，加 --migrate 才会迁移并安装插件；不加会报错并保持旧配置。迁移只删除旧标题钩子的注册条目，保留脚本、其他钩子和会话数据，并备份原配置。

DeepSeek Harness

需要 Node.js 20+，以及 dsh 命令或已存在的 ~/.dsh。只安装 DSH 插件：

npx --yes github:panda-z519/agent-session-titles --dsh --lang zh

安装器会把 dsh-session-titles 复制到 ~/.dsh/plugins/，在目标 profile 的 cordis.patch.yml
用户层写入受管块：禁用内置 session-title-llm 与 optional-session-title-all-prompts，并用相对
路径插入插件。这种方式不需要 dsh plugin，也不改 profile 的 package.json，重启 DeepSeek
Harness 后生效。桌面端的 desktop profile 由 Electron 独占，CLI 拒绝对它执行 --dump-config；
dsh plugin 的 pnpm 转发仍然可用，见下一节的组合包安装。

如果已经在插件页把 dsh-session-titles 作为 bundle 安装，安装器会检测到，只写禁用行，不会再
重复插入插件行；卸载时先在插件页移除 bundle，再运行 --remove-dsh。

作为组合包安装（出现在插件页）

同一份插件带 dsh.bundle.patch，也可以装成 profile 的组合包。这样它会出现在 插件 → 已安装插件
里，能开关插件行、改 language / maxTitleBytes、直接在页面上卸载；受管块方式不会出现在插件页，
因为它不是 profile 的依赖记录。两种方式只能二选一：

  1. 先删掉安装器写入的受管块（cordis.patch.yml 里 session-title-llm、
    optional-session-title-all-prompts 和 insert: agent-session-titles 那一段），否则
    agent-session-titles 行会被插入两次；
  2. 在插件页用 添加插件 → 安装第三方插件 填本地目录绝对路径
    ~/.dsh/plugins/dsh-session-titles；等价命令是
    dsh plugin --profile <profile> add "link:$HOME/.dsh/plugins/dsh-session-titles"；
  3. 确认 profile 的 package.json 里 dsh.profile.bundles 的末尾是 dsh-session-titles
    ——它的 patch 要最后应用，才能压住实验性 titles bundle 重新插入的内置 provider；插件页安装会
    自动写入，纯命令方式若缺这一项就手动补上；
  4. 重启 DeepSeek Harness。

已在 DSH 0.2.1-rc.5 的 desktop 和 web profile 上验证：组合后的配置里 session-title-llm、
optional-session-title-all-prompts 都是 disabled: true，agent-session-titles 恰好一行。
web profile 不含实验性 titles bundle，重启时 loader 会为 optional-session-title-all-prompts
打一条 "entry not found" 提示，不影响使用。

  • 只装某个 profile：--dsh-profile web（可重复）；三端一起：--all；
  • 卸载：--remove-dsh（删除受管块和插件副本，不删除已有会话标题）；
  • DSH 标题由宿主 sessionTitle 服务写入 session/title 事件；插件提供
    set_session_title 工具，Agent 在理解需求后和阶段变化时更新；
  • 中间段用 4–12 字总结整个会话的主题/目标，不是只写首条需求；未手动锁定前 Agent 可以修正；
    旧版本留下的截断或路径中间段会在下一次消息时自动修正；
  • 手动改名会锁定对应段，下一次用户消息或工具调用时自动恢复其余段；
  • 状态和进展仍依赖 Agent 调用 set_session_title；未调用时标题停在 聊天｜…｜刚开始。
  • 默认标题上限 80 字节，超长会先裁“当前进展”，再裁“会话摘要”。

原理、边界和验证步骤见 DSH 方案文档。

全局规则文件

标题规则由插件钩子在每个会话中自动注入，不需要在全局 AGENTS.md（Codex）或 CLAUDE.md（Claude Code）里手写。安装器默认不修改这两个文件，只扫描其中疑似手写的会话标题规则，并在输出里指出行号，提醒你核对，避免和插件规则重复或冲突。

如果希望在钩子之外也把规则写进全局规则文件，可以加 --rules。安装器会在文件末尾写入一个由 <!-- agent-session-titles:start --> 和 <!-- agent-session-titles:end --> 包住的托管块，内容随标题语言生成，修改前会备份原文件。之后重新安装时，即使不加 --rules，已有的托管块也会整块更新。删除托管块（不安装插件）：

npx --yes github:panda-z519/agent-session-titles --remove-rules

--remove-rules 同样支持 --codex / --claude，只删除标记之间的内容，并保留文件其余部分。

安装器从 GitHub 读取此仓库，将插件文件复制到用户目录中的稳定位置，再调用相应客户端的插件命令。它不会在 npm install 阶段执行 postinstall。新安装的 Codex 钩子需要在 Codex 中检查并信任；随后重启对应客户端，使用新的本地会话验证。Codex 钩子信任说明

安装器会修改什么

客户端 安装和配置
Codex 注册并安装 codex-session-titles 插件；把 ~/.codex/session-titles/ 加入窄范围可写目录；更新前检查状态库结构并创建 SQLite 一致性备份。
Claude Code 注册并安装 claude-session-titles 插件；在 ~/.claude/settings.json 中加入 Edit(~/.cc-session-titles/**)；改动前备份已有设置。
DeepSeek Harness 复制 dsh-session-titles 到 ~/.dsh/plugins/；在目标 profile 的 cordis.patch.yml 用户层写入受管块，禁用内置标题 provider，并用相对路径加载插件；若已作为 bundle 安装则只写禁用行；修改前备份。想让插件出现在插件页时，可改用组合包方式（dsh plugin … add link:… + dsh.profile.bundles），此时需先删受管块。

已安装旧版用户级 session-title.sh 的客户端需要明确传入 --migrate；安装器会备份后移除匹配的旧钩子注册，再安装插件。CODEX_HOME、CLAUDE_CONFIG_DIR 和 DSH_HOME 分别支持自定义配置目录。

验证标题

  1. 重启客户端，新建一个本地会话，提出具体需求。助手理解需求后应尽早形成三段标题，阶段明显变化时更新状态与进展。
  2. 分别手动修改一段标题，再让助手进入下一阶段；手动改过的段应保持原样，其他段继续更新。若把整条标题改为无法拆分的格式，插件应保留整条名称；再改回合法的三段格式后，插件恢复自动更新（中间段锁定）。
  3. Codex 在标题文件写入后的工具事件尽早同步，即使 Codex 此时还没给会话起名；若 Codex 首轮结束后自动生成的名字覆盖了插件标题，下一次发消息时会恢复一次。Stop 和下一次发消息仍负责补偿。可检查 ~/.codex/session-titles/<会话ID>.state.json 的 phase、last_result 和分段锁定信息。Codex CLI 使用后台守护进程（app-server daemon）时，插件经它的控制套接字调用 thread/name/set，已打开的 CLI 窗口会立即刷新状态栏标题；守护进程不可用（例如 --no-daemon）时退回直接写 SQLite，此时已打开的窗口要到重新打开或 /rename 后才显示新标题。侧边栏即时刷新仍取决于桌面端。
  4. Claude Code 首条提示词通过官方 sessionTitle 钩子输出形成初始标题。桌面端在 Agent 写入标题文件后由 PostToolUse 钩子调用桌面端改名工具立即生效；命令行没有该工具，后续进展在下一次提交消息时应用（PostToolUse 钩子会报一条不影响流程的错误）。可检查 ~/.cc-session-titles/<会话ID>.txt。Claude 钩子说明
  5. DeepSeek Harness 重启后新建本地会话，侧边栏应出现三段式标题；Agent 进入下一阶段时标题应即时更新。可检查会话日志中的 session/title 事件，source.provider 应为 agent-session-titles。手动改名后，下一次消息应保留手改段并恢复其余段；把标题改成自由格式后应整体保留，改回三段式后恢复更新。若按组合包方式安装，重启后 插件 → 已安装插件 里应出现「会话标题」卡片，行内开关、配置（language、maxTitleBytes）和卸载都在该页面完成。

历史会话在收到新消息后才重新纳入 Codex 标题管理。若钩子提示“来源未确认”，会保留已有名称。无项目会话使用需求摘要，不把当前目录冒充项目名。

更新与卸载

更新时重新运行相同的 npx 命令，并重启对应客户端。安装器可重复执行；Codex 新版本会另存状态库备份。插件名沿用 codex-session-titles 和 claude-session-titles，两端插件源统一为 agent-session-titles。从旧插件源名称升级时，安装器会在新插件装好后自动卸载旧插件、移除旧插件源登记并删除旧复制目录，避免钩子重复运行，无需手动处理。

卸载插件可分别运行：

codex plugin remove codex-session-titles@agent-session-titles
claude plugin uninstall claude-session-titles@agent-session-titles
npx --yes github:panda-z519/agent-session-titles --remove-dsh

只使用一端时运行该端的卸载命令。准备脚本添加的可写目录或 Edit 规则可从用户配置中单独移除；旧版独立钩子和备份不会被自动删除。--remove-dsh 会删除受管块和插件副本，保留已有会话标题事件；不要只关闭插件行，否则内置标题 provider 仍处于禁用状态。

限制

  • Codex 标题同步优先调用本机后台 app-server 的 thread/name/set，失败时直接写本机 state_5.sqlite。两者都依赖当前 Codex 的内部接口和数据库结构，属于本地集成；结构不符时准备脚本会停止配置，钩子不会创建空数据库。
  • Claude Code 命令行只能在 SessionStart 或 UserPromptSubmit 通过官方钩子设置标题，本轮新写的进展要到下一次提交消息才生效；桌面端的即时改名依赖桌面端内置的 ccd_session_mgmt 工具。
  • 即时改名按标题文件内容原样设置，锁定字段若被覆盖，会在下一次提交消息时恢复。自定义 CC_TITLE_DIR 时即时改名不生效（钩子条件固定匹配 ~/.cc-session-titles/）。
  • 插件只能从与上次应用标题的差异推断“外部修改”，无法证明修改者一定是用户。首次接管且没有基线的历史标题仍需保守处理。
  • DeepSeek Harness 的标题由宿主 sessionTitle 服务管理，服务只允许一个 provider；安装器会在用户 patch 层禁用内置 provider，如果另有第三方标题插件抢占，本插件会降级为不启用并记录警告。
  • DSH 默认标题上限为 80 字节，超长时先裁“当前进展”，再裁“会话摘要”；需要更长标题时同时调整 session-title 服务和插件配置。
  • DSH 桌面端的 desktop profile 由 Electron 独占，CLI 只有 --dump-config 被拒绝（dsh plugin 仍可转发 pnpm）；安装器只写用户 patch 层并跳过桌面端校验，重启应用后由宿主加载。想验证 desktop 的组合结果，可把 profile 复制到临时 DSH_HOME 下改名后 --dump-config。
  • 本仓库的生命周期钩子面向本地桌面端，不能作为带钩子的插件提交到 OpenAI 公共插件目录。插件打包说明

社区

感谢 LINUX DO 社区，本项目在这里发布、交流并收集佬友们的反馈。

手动安装、隔离检查与排查步骤见使用说明。源码按 MIT 许可证开放。

Reviews (0)

No results found