longrun

快速开始：装好，然后照常干活

这个 skill 假定人还是照常在会话里干活，而笔记、摘要和消息投递由 hook 以及照着指示走的模型负责。下面是你需要亲手做的全部事情。

1. 装一次就好。一行命令，不需要 checkout，安装脚本自己去取源码：

   curl -fsSL https://krllx.github.io/longrun/install.sh | bash

   它装上 skill、~/.claude/settings.json 里的 12 个 hook、CLI ~/.local/bin/longrun、longrun MCP 服务器，以及一个定时器，每五分钟跑一次检查和监视器。它只问你一件事：桌面通知，也就是下一步。从 clone 下来的仓库安装，用的也是同一个 install.sh；--uninstall 撤销一切。
2. 通知，想要就装。install.sh 会问要不要配置通知，装不装取决于你当时的回答。longrun 从不依赖通知：全部停止和触发的事件监听，本来就会经由 socket 或收件箱到达会话，所以拒绝了也不会有别的影响（--no-notify 可以提前替你回答；以后想开，再跑一句 brew install terminal-notifier）。在 macOS 上，缺少 terminal-notifier 时安装脚本会执行 brew install terminal-notifier（前提是有 Homebrew；没有就直说一声然后跳过），然后发一条测试通知；macOS 可能会问一次是否允许来自 terminal-notifier 的通知，允许它。macOS 自带的手段替代不了这一步：osascript -e 'display notification' 是以 Script Editor 的身份发出的，而它没有通知权限，于是系统把通知归档、什么都不画，还返回 0（在 macOS 15 上 25 次全是如此；就算先打开过 Script Editor 也拿不到权限）。所以横幅上带的是 terminal-notifier 自己的名字和图标：这两样 macOS 都取自发出通知的那个 bundle，也没有办法逐条覆盖。在 Linux 上用的是 notify-send (libnotify)，大多数桌面环境已经有了。两种系统都可以用 longrun notify --test 检查：它发一条探针，再回头读一次，确认系统真的把它画了出来，并打印点一下会打开哪个会话。如果有一个会话你绝对不能错过：longrun important on（或者 next，或者一个数字）让它每轮结束时一定发通知，不管 notify_turn_end 设成了什么，也不管当前前台是哪个窗口；你在另一个 Claude 会话里打字时，Claude 窗口就在前台，按前台窗口判断的那条规则就不会发通知。
3. 把文件夹变成项目。对 longrun 来说，项目就是你在 Claude Code 里打开的那个文件夹。不一定是仓库根目录：可以是装着好几个仓库的文件夹、monorepo 的一个子目录，或者一个空的指挥部 (hq) 文件夹。在那里跑一次 longrun init：在终端里跑，或者直接在 Claude Code 会话里说一声，agent 会替你跑。一个 .longrun/ 目录会出现；如果这个文件夹在仓库里，把它加进 ignore 文件（或者用 longrun init --external，它把目录放到 ~/.claude/longrun/ 下）。同一个项目的每个 worktree 里：longrun link <project>。检查一下：longrun where。
4. 调一调。在会话里对 agent 说："set up longrun"（或者 /longrun onboard）。它会跑 longrun onboard，简短讲一下这个 skill 做什么，然后问你几个主要设置：autocompact 窗口、判定卡住的阈值、笔记大小、通知。它自己用 longrun config set 把答案写进配置。只有一个例外：hook 设不了 autocompact 窗口，所以 agent 会让你在 Claude Code 里手敲 /autocompact 300k（或者你选的那个值）。在离这个阈值还有 5 万 token 时，会有一个 hook 提醒会话在 compaction 之前先把笔记写好。各个 key 的细节见下面第 9 章。
5. 干活。不用调用任何命令。会话启动时拿到摘要（共享笔记、自有笔记、还有谁在干活），compaction 之后一切自己回来，其他会话的改动在下一轮送到。agent 自己会把死胡同和决定写成笔记。你可以用平常的话说：“记一下”、“我们都试过什么”、“会话状态”、“把这个交给另一个会话”、“还剩什么”、“PR 合了告诉我”。
6. 多个会话，一个共同目标。在其中一个里说：“接过编排器的角色，目标是……”。它会建一块任务板并派活；其他会话把任务当作一轮用户输入收下，什么都不用学。“让所有人停下”和“继续”同样用平常的话说，在编排器会话里说，见下面第 8 章。

为什么

项目真正的状态，试过什么没成、定下了什么、什么事卡在谁那儿，都只活在一次对话里，对话结束就跟着没了。下一个会话，明天那个也好、另一个窗口里那个也好，都从零开始，而且根本不知道还有别的会话在。所以项目把这份状态记在磁盘上，由 agent 自己维护。compaction 是同一个问题最尖锐的那一面，而不是问题本身：历史被压成一段总结，下一次 compaction 再把这段总结压一遍。

下面这张图说的是问题 1。上面一行：模型上下文里装着什么，从左到右是时间顺序：先是完整历史，compaction 之后只剩总结，然后是读着这段总结的 agent。下面一行：磁盘上的文件，agent 一开始就在里面写了一条笔记。虚线箭头：笔记在启动时进入上下文，compaction 之后再进入一次。

这个 skill 由什么构成

三个实体，没有别的

“项目”这个词只指 .longrun/ 目录：不是 monorepo 里的项目，也不是 Claude Code 存 transcript 的文件夹。worktree 用 longrun link 挂到项目上；它自己没有笔记。一个会话属于一个项目。resume 时应用会给会话一个新的 CLI id；longrun 顺着 priorCliSessionIds 这条链找回来，自有笔记就不会断。

磁盘上的文件

每个文件都来自一个具体的问题：

• 会话的 notes.md：问题 1。这个会话里必须熬过 compaction 的死胡同和决定。
• 项目的 NOTES.md：问题 2。任何会话都用得上的事实：PR 号、一个决定、环境的一个怪癖。
• journal.md：不花 token 的时间线，全部由机械层自己写：启动、结束、失败的命令、compaction、发出去的消息。不读 transcript 也能看出一个会话干了什么。
• archive/compact/ 和 archive/precompact/：每一段 compaction 总结的原文，以及它之前的快照 (HANDOFF)。前者由 recall 找到，后者在 compaction 之后回到摘要里。
• inbox/：给当前没在运行的会话的消息，在这儿等它的下一轮。
• meta.json：计数器、最后一次回答、正在跑的工具。摘要里的 SESSIONS 行和给编排器的标记都是用它拼出来的。
• board.json、stale.json、watch/、halt.json：编排器的任务板、“已经不成立”的标记、事件监听的检查、对所有人的停止。见第 7 和第 8 章。

共享的东西都在项目里。自有的东西放在仓库目录树之外，也不放在同步文件夹里，因为每次工具调用都会重写它们。点一下文件看看。

hook：机械层在哪儿

会话的每个事件，Claude Code 都会调用一个外部命令。longrun 装了 12 个这样的命令，它们全都是同一个 python 脚本。每个事件的 hook 都是一个单独的进程，所以装完之后新代码在所有会话里立刻生效。点一下循环里的某个 hook。

笔记：该写什么、写到哪

一行，用英文，最多 400 个字符（同一条事实换一种语言，token 大约是原来的 1.5 倍，而预算是硬上限）。只有一个判据：一条命令、一次 Read 或一次 grep 能不能把它找回来？能的话，就别写。

一条笔记默认写进项目的共享笔记；加 --own 就只留在这次对话里。一行放不下？那它就该是一个文件：longrun doc add research/plan.md "the rollout plan and what is open" 在共享笔记里留下一行指向它，每个会话真需要时才去打开那个文件。进展（“推上去了”、“测试绿了”）哪儿都不用写：hook 早就把这些记进日志了。比任务存在更久的东西（用户是谁、他怎么干活）写进 Claude Code 的自动记忆，不写这里。

自测一下：这条该写到哪？

一个会话熬过 compaction

项目 shop，会话 A。用“下一步”和“上一步”按钮，或者方向键。左边：这一步谁在跟谁说话；右边：命令和它打印出来的东西；下面：磁盘上有什么变了。

两个会话：共享记忆

会话 B 在同一个文件夹里打开。

把活交出去，然后等一个事件

发给另一个会话的消息，在那边是一轮用户输入。等事件不花 token：检查由定时器来跑。

编排器：一个会话协调其余会话

这是建在笔记和消息之上的一层。一个会话拿着目标和任务板，其余会话只学三条命令：board take、board done、board block。编排器需要的一切都在状态文件里；它不读 transcript。这是跨多个窗口的协调，再加上一条随时能问到你的通道，不是自治：把一个会话推向一个评估器能检验的条件，那是 Claude Code 自带的 /goal 干的事。

设置

两级：全局文件 ~/.claude/longrun/config.json 和项目文件 .longrun/config.json；项目里的值覆盖全局的值。不用手改 JSON：

longrun config                                  # effective values and where each comes from: default / global / project
longrun config set stuck_tool_min 60 --global   # for every project
longrun config set notes_max_bytes 8000         # for this project
longrun config unset notes_max_bytes            # back to the default

key 大概有四十个（完整列表在 docs/REFERENCE.md 第 6 节）。刚装完之后，这几个值得看一眼：

速查表和边界

# install
curl -fsSL https://krllx.github.io/longrun/install.sh | bash
                        # skill, 12 hooks, CLI, MCP server, the 5-minute timer, notifications
longrun watch install   # the timer alone (the installer already did it)
longrun notify --test   # optional: does a notification reach the screen
longrun init [--external]  # in the project folder
longrun link <project>  # from every worktree
longrun where           # which project, which session

# notes
longrun add [--own] -t TAG "..."
longrun doc add path "what is in it" | doc ls
longrun rm s3 n12 | replace n12 "..."
longrun stale n12 "why" | mute n12
longrun notes | prune [--auto] [--shared]
longrun recall term

# sessions
longrun status
longrun send [--list] [--resume] WHO "text"
longrun important on|next|N|off [--to WHO]
longrun watch add --to WHO --then "..." -- pr-merged ID
longrun watch ls | test -- CHECK | sessions

# orchestrator
longrun orchestrate start --goal "..."
longrun board | board add|assign|take|done|block T7
longrun board add --fact "..." --task T7 | board ls --facts | board ack F1
longrun halt "why" | resume
longrun ask "question" --options "Yes,No"

# settings
longrun onboard [done]
longrun config
longrun config set KEY VALUE [--global]
longrun config unset KEY [--global]

机械层保证什么，什么取决于模型

边界

• 摘要最多 9000 字节。超出时按这个顺序挤掉：事件监听、日志尾巴、编排器的职责、会话列表、任务板、HANDOFF。笔记最后才让位，而且是一条一条丢掉最旧的非 pin 条目，绝不会把最新的从末尾切掉。
• 应用里的 resume 通过 priorCliSessionIds 串起来；CLI 里的 /clear 靠一条启发式规则：“同一个文件夹，三分钟内以 clear 为原因结束”。
• socket 和 transcript 的格式没有文档：Claude Code 换版本时，最先坏掉的就是往正在运行的会话 send 这条路，走收件箱的队列照常工作。
• 在 macOS 的定时器下，python 可能没有 ~/Documents 的访问权限 (TCC)。检查本身不依赖它；这时消息会落到 ~/.claude 下的会话目录里。
• 子 agent 拿不到摘要。/rewind 不会把笔记回退。

细节见仓库里的 README.md、docs/REFERENCE.md、docs/ORCHESTRATOR.md，以及 longrun help。