fable-session

fable-session 是一个套在 Claude Code CLI 外面的本地 Python 工具：每个 session 启动之前， 先替它备好一份小而固定的任务上下文。 上下文短了、边界清楚了，日常写代码就不那么容易误触暂停。 它不是模型，也不是 Anthropic 的产品。

非官方项目，与 Anthropic 无关。 这是一个独立的社区工具， 用来运行 Claude Code CLI。它不是 Anthropic 出品， 也没有得到 Anthropic 的认可或支持。

这个工具不绕过任何安全机制。 它不会重试、改写或重新提交被标记的内容， 也不靠换模型躲开拒绝；不该跑的东西，它也不会替你想办法跑起来。 session 被暂停或拒绝时，fable-session 如实报告，然后停下。

你见过这个画面吗？

截图里的英文原文，逐字如下：

Session paused

Fable 5's safeguards flagged this message. The safeguards are intentionally broad right now and may flag safe and routine coding, cybersecurity, or biology work. These measures let us bring you Mythos-level capabilities sooner, and we're working to refine them. Send feedback with /feedback or learn more

1. Switch to Opus 4.8
2. Edit prompt and retry with Fable 5

先把丑话说在前面：真的被暂停之后，fable-session 不会继续已暂停的运行，不会修改或重试被标记的 prompt， 不会切换模型（截图里的选项 1 和 2 是留给你本人的，它绝不代劳）， 更不会绕过安全机制。真实的暂停会被记录，运行就停在那里， 接下来怎么办由你决定。

如果你用 Fable 5 在 Claude Code 里做日常开发也总撞上这个暂停， 最常见、也最容易避免的原因，是上下文太大又没有边界： 一个巨长的 prompt、整段贴进来的日志， 或者老代码堆里埋着的某个敏感词。 fable-session 做的事，是在启动前把送进 session 的内容收拢好； session 一旦被标记，它绝不再碰。

它做什么

• 有边界的上下文：简报由一个任务文件加一份仓库里的 profile 拼成， 有硬性的字节上限，而不是把手边的东西一股脑塞进去；
• 锁定模型，不自动 fallback：要么用你指定的模型跑完这个 session， 要么直接停下；不会悄悄降级、切换或重试；
• 事后能查：audit 读的是 session 自己的结构化 JSONL 流， 核对这次实际用了哪些模型；watch 只报告一个 session 的状态， 从头到尾不碰 session 本身。

它不做什么

session 真的被暂停或拒绝时，fable-session：

• 不会继续已暂停的运行；
• 不会修改或重试被标记的 prompt；
• 不会切换模型（截图里的 1 和 2 留给你自己选，它从不代劳）；
• 不会以任何方式削弱或绕过安全机制。

真实的暂停会被记录，运行随即停止：暂停写成结构化事件，下一步由你决定。 这个工具只管两件事：减少上下文过大造成的误伤暂停， 让每次运行的结果事后可查。

为什么值得一试

如果你已经在手动跑 Claude Code，fable-session 每次启动会多给你四样东西：

• 小而固定的任务上下文：同一个任务文件加同一份 profile， 每次拼出同样的简报，不多不少；
• 锁定 Fable 5，不自动 fallback：模型要么按你指定的来，要么停；
• 一个 watcher 盯一次运行：对着这次运行自己的 manifest 跑一条 watch --follow，报告运行事件，到终态自动退出；
• 跑完一份模型和用量 audit：用 session 自己的 JSONL， 看清这次实际用了哪些模型、花了多少钱。

这些能降低误触暂停的概率，但不保证 session 永远不被暂停——真的暂停仍然会让运行停止。

凭什么信它

这里的每一条都实际验证过，不是口头承诺：

• 500+ 自动化测试，跑在受保护的 main 分支 CI 上；
• 运行时只用 Python 标准库，零第三方依赖；
• 发布检查会扫描 git 跟踪的文件树，连同历史里每一个可达的 blob， 查内部标识和长得像凭据的内容；
• CI 离线安装 wheel，再对装好的 CLI 做一次 dry run；
• 每个 GitHub Action 都钉在确切的 commit SHA 上；
• 在 Linux + Claude Code 2.1.208 上做过一次真实冒烟，从头跑到尾： 任务经 stdin 送达 Claude，启动接受了 --max-budget-usd 0.5 （这只是冒烟测试的固定参数：registry 里不写预算键， 就不会带任何预算 flag），--follow watcher 输出了一段有上限的用量汇总并自己退出， session 返回了精确标记 FABLE_BETA1_SMOKE_OK， audit 对 actor 消息给出 PURE， 同时如实报告了辅助的 Haiku 调用。 实测花费：$0.15400099999999997。

那次冒烟的简明记录——包括它证明不了什么——都在 docs/VALIDATION.md。

适合谁，不适合谁

适合：

• 你在 Fable 5 上跑重要或很长的 Claude Code session， 希望每次启动都带一份小而固定的上下文；
• 你要拿运行记录写脚本：manifest、运行事件、退出码，一样不缺；
• 你用 Hermes 这类 orchestrator 驱动 session， 想给每次运行配一个 watcher、跑一次 audit。

不适合：

• 它不能替代 Claude：Claude Code CLI 要你自己安装、自己登录；
• 它不帮任何人绕过安全机制，也不做自动重试， 更不会一口气拉起一群 session；
• 随手聊两句的事，犯不着先注册项目再写任务文件。

目前的限制

这个公开 beta 的实际边界：

• 只在 Linux + Claude Code 2.1.208 这一个组合上验证过， 其它平台和 CLI 版本都没验证；
• 需要 Python 3.12+ 和 tmux，而且配置全靠手动： registry、profile、任务文件都要你自己写；
• 任务和简报的 payload 文件，同一 UID 的进程都读得到， 简报还会一直留在 Claude 进程的命令行上—— 千万不要把密钥写进任务文件；
• 这是公开 beta，不是集群调度器（fleet scheduler）： 一次一个 session、一个 watcher、一次 audit。

环境要求

• Linux：实测组合是 Linux + Claude Code 2.1.208， 别的平台和 CLI 版本没验证过，这里也不做更多承诺；
• Python 3.12+：包本身零运行时依赖，只用标准库；
• tmux：启动的 session 会跑在新开的 tmux session 里；
• Claude Code CLI：要单独安装、单独登录， 这个工具不附带它，也不替你配置。

安装

还没上 PyPI，装之前先看这段。 fable-session 0.3.0b1 没有发布到 PyPI，这个名字目前在 PyPI 上也不属于本项目， 所以不要直接从包索引安装：今天什么都装不到， 以后如果冒出同名的包，那也是别人的东西。 要不要发 PyPI，是以后另一个单独的决定。 现在请只用下面钉住 tag 的 GitHub 源安装， 或者用 GitHub release 的附件。 v0.3.0-beta.1 的 tag 和 prerelease 已经发布： https://github.com/getaskclaw/fable-session/releases/tag/v0.3.0-beta.1， 指向 commit 181d32155d81a3ff872a0e00cc4e19c6a3007c7d， 附带 wheel、sdist、SHA256SUMS 和源码包。

装进一个隔离环境，源钉在 tag 上：

# pipx (tag-pinned GitHub source)
pipx install "git+https://github.com/getaskclaw/fable-session@v0.3.0-beta.1"

# uv (tag-pinned GitHub source)
uv tool install "fable-session @ git+https://github.com/getaskclaw/fable-session@v0.3.0-beta.1"

# plain pip, isolated venv (tag-pinned GitHub source)
python3.12 -m venv ~/.venvs/fable-session
~/.venvs/fable-session/bin/pip install "fable-session @ git+https://github.com/getaskclaw/fable-session@v0.3.0-beta.1"

也可以从上面的 release 页面下载 wheel 和 SHA256SUMS， 核对校验和之后，直接安装那个 wheel 文件。

第一次 dry run（什么都不启动）

dry run 是默认行为，不会启动任何东西—— 它只展示将要运行的内容，并写出一份运行 manifest：

fable-session run --project example-api --task /absolute/path/task.md --dry-run

在这之前，你要先注册一次项目，再往仓库里放一份小 profile。 Quickstart 会带你把第一个 session 走完： 安装、registry、profile、任务文件、dry run、启动、一次 watch、一次 audit。

三个子命令

一个命令，三个子命令，一次运行从启动到审计都在里面：

fable-session run   --project example-api --task /abs/task.md --launch --tmux api-example
fable-session watch --manifest /abs/runs/<run-id>/manifest.json --follow
fable-session audit --manifest /abs/runs/<run-id>/manifest.json

• fable-session run：解析注册过的项目，拼出有边界的简报， 构造出确切的 Claude CLI 命令；只有加上 --launch， 才会在一个新的 tmux session 里启动它；
• fable-session watch：跟着一个已启动 session 的结构化 JSONL 流， 报告运行事件（暂停和拒绝都在内），从不干预 session， 到终态自动退出；
• fable-session audit：等 watcher 退出后， 用 session 自己的记录，核对这次实际用了哪些模型。

选项、约定和各种边角情况，都写在 Reference 里。

隐私

运行 manifest 和命令输出里只有哈希、字节数和路径， 没有 prompt 文本、凭据，也没有终端历史。 再说一遍：不要把密钥写进任务文件。 session 运行期间，prompt 内容对同一主机上你自己用户的进程可读； 长得像密钥的内容会在启动前被直接拒绝。 payload 的具体机制和它的边界， 见 Reference。

文档

• Quickstart：第一个 session 从头到尾， checkout、registry、profile、任务文件、dry run、启动、watch、audit；
• Reference：全部细节，包括配置、运行状态、 audit 结论、watch 事件、隐私约定、从 claude-context-tools 迁移、 开发与发布说明；
• 验证记录：那次真实冒烟和各项确定性发布检查的记录， 不含隐私内容；
• 安全政策：怎么报告漏洞（只走 GitHub private vulnerability reporting）；
• examples/projects.toml：带注释的 registry 示例。

状态与许可证

fable-session 以 MIT License 发布，见 LICENSE， 包元数据写的也是 MIT。项目主页是 https://github.com/getaskclaw/fable-session：仓库已公开， 里面是独立审阅过的干净历史，main 分支受保护， GitHub private vulnerability reporting 已开启并验证。 PUBLIC_RELEASE_CHECKLIST.md 里的公开 beta 检查已全部完成； v0.3.0-beta.1 GitHub prerelease 已经发布，地址是 https://github.com/getaskclaw/fable-session/releases/tag/v0.3.0-beta.1， 指向 commit 181d32155d81a3ff872a0e00cc4e19c6a3007c7d， 附带 wheel、sdist、SHA256SUMS 和源码包。 发布到 PyPI 不在这次 prerelease 的范围内。 原始的导出前工作历史，任何时候都不能推到公开仓库。 安全问题见 SECURITY.md。