longrun

クイックスタート：入れて、あとはふつうに使うだけ

このskillは、人間がいつもどおりセッションで作業することを前提にしています。メモ、ダイジェスト、メッセージの配送はhookと、指示に従うモデルが引き受けます。以下が、手でやることのすべてです。

1. 1度だけインストール。1行で済み、checkoutも要りません。インストーラーがソースを自分で取ってきます：

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

   入るのはskill、~/.claude/settings.jsonの12個のhook、CLIの~/.local/bin/longrun、longrun MCPサーバー、そしてチェックと監視役を5分ごとに走らせるタイマーです。尋ねられるのは1つだけ、次の項目のデスクトップ通知です。cloneから入れる場合も同じinstall.shで、--uninstallが元に戻します。
2. 通知（任意）。install.shは通知を設定するかを尋ね、この項目が必要かどうかは、その答えで決まります。longrunが通知に依存することはありません。全停止も発火したウォッチも、いずれにせよsocketか受信箱を通ってセッションに届くので、断っても他には何も変わりません（--no-notifyで先に答えておくこともでき、あとからbrew install terminal-notifierで有効にもできます）。macOSでは、terminal-notifierがなければインストーラーがbrew install terminal-notifierを実行し（Homebrewが前提です。なければその旨を伝えて先へ進みます）、テスト通知を1つ送ります。macOSはterminal-notifierからの通知を許可するかを1度だけ尋ねることがあるので、許可してください。macOS標準の手段でこの手順を置き換えることはできません。osascript -e 'display notification'はScript Editorの名義で通知を出しますが、Script Editorは通知権限を持たないため、システムは通知を記録するだけで何も表示せず、終了コードは0を返します（macOS 15で25回中25回。Script Editorを先に起動しても権限は付きません）。そのためバナーにはterminal-notifier自身の名前とアイコンが出ます。macOSはこの2つを通知を出したバンドルから取るので、通知ごとに差し替える方法はありません。Linuxではnotify-send(libnotify)で、たいていのデスクトップ環境にはすでに入っています。どちらでもlongrun notify --testで確かめられます。テスト通知を1つ送り、システムが実際に表示したかを読み返し、クリックするとどのセッションが開くかを出力します。絶対に見逃したくないセッションが1つあるならlongrun important on（またはnext、あるいは数字）です。そのセッションのターンの終わりは、notify_turn_endがどう設定されていようと、どのウィンドウが前面だろうと必ず通知されます。別のClaudeセッションで入力している間は、前面ウィンドウを見る通常の判定ではこの通知を出せません。
3. フォルダをプロジェクトにする。longrunにとってのプロジェクトは、Claude Codeで開くフォルダです。リポジトリのルートである必要はありません。複数のリポジトリを含むフォルダ、monorepoのサブディレクトリ、空の司令塔フォルダでもかまいません。そこで1度longrun initを実行します。ターミナルでも、Claude Codeのセッションの中でもよく、頼めばエージェントが代わりに実行します。.longrun/ディレクトリができます。そのフォルダがリポジトリの中にあるなら、ignoreファイルに追加してください（またはlongrun init --externalで、ディレクトリを~/.claude/longrun/の下に置きます）。同じプロジェクトの各worktreeからはlongrun link <path to the project>。確認はlongrun whereです。
4. 設定する。セッションでエージェントに「set up longrun」と言います（または/longrun onboard）。エージェントはlongrun onboardを実行し、skillが何をするかを手短に説明し、主な設定について尋ねます。autocompactのウィンドウ、停滞のしきい値、メモのサイズ、通知です。答えはエージェントがlongrun config setで適用します。例外が1つ。hookはautocompactのウィンドウを設定できないので、エージェントはClaude Codeで/autocompact 300k（または選んだ値）と入力するよう頼みます。そのしきい値の5万token手前で、hookがcompactionの前にメモを書くようセッションに促します。キーの詳細は下の第9章。
5. 作業する。呼ぶものは何もありません。開始時にセッションはダイジェスト（共有メモ、自分のメモ、他に誰が作業中か）を受け取り、compactionの後はすべて自動で戻り、他のセッションの変更は次のターンで届きます。行き止まりと決定のメモは、エージェントが自分で書きます。言葉で頼めます。「記録しておいて」「これまで何を試したか」「セッションの状況」「別のセッションに渡して」「何が残っているか」「PRがマージされたら教えて」。
6. 複数のセッションと共通の目標。そのうちの1つで「オーケストレーターの役を引き受けて、目標は……」と言います。タスクボードを作って仕事を配り、他のセッションはタスクをターンとして受け取ります。覚えることはありません。「全員止めて」「続けて」も言葉で、オーケストレーターのセッションで言います（下の第8章）。

なぜ

プロジェクトの本当の状態、つまり何を試して失敗したか、何を決めたか、何が誰待ちかは、1つの会話の中にだけあり、その会話とともに消えます。次のセッション、明日のセッションや隣のウィンドウのセッションは、何も知らないところから始まり、ほかのセッションの存在も知りません。だからプロジェクトはその状態をディスクに置き、エージェントがそれを保ちます。compactionは同じ問題のいちばん鋭い形であって、問題そのものではありません。履歴は要約に圧縮され、次のcompactionはその要約をさらに圧縮します。

下の図は問題1についてです。上段はモデルがコンテキストに持っているもので、左から右へ時間が進みます。最初は完全な履歴、compactionの後は要約だけ、そしてその要約を読むエージェント。下段は、エージェントがいちばん最初にメモを1行書いたディスク上のファイルです。点線の矢印は、そのメモが開始時と、compactionの後にもう1度コンテキストへ入ることを示します。

skillは何でできているか

実体は3つ、それだけ

ここで言う「プロジェクト」は.longrun/ディレクトリのことだけを指します。monorepoの中のプロジェクトでも、Claude Codeのtranscriptフォルダでもありません。worktreeはlongrun linkでプロジェクトに紐づけます。worktree自体はメモを持ちません。セッションが属するプロジェクトは1つです。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個入れますが、実体はどれも1つのpythonスクリプトです。hookはイベントごとに別プロセスなので、インストールの直後から新しいコードがすべてのセッションで同時に効きます。ループの中のhookをクリックしてください。

メモ：何をどこへ書くか

1行、英語で、400文字まで（同じ事実を他の言語で書くとtokenが約1.5倍かかり、上限は動かせないからです）。判断基準は1つ。コマンド1回、Read1回、grep1回で取り戻せるか？取り戻せるなら書きません。

メモは何も指定しなければプロジェクトの共有メモへ入ります。この会話の中だけに留めたいときは--ownです。1行に収まらないほど長いものは、メモではなくファイルにします。longrun doc add research/plan.md "the rollout plan and what is open"が共有メモに指し示す1行だけを残し、どのセッションも必要になったときだけそのファイルを開きます。進捗（「pushした」「テストが緑」）はどこにも書きません。hookがすでにジャーナルに残しているからです。タスクより長く残るもの（ユーザーが誰か、どう働くか）は、ここではなくClaude Codeの自動メモリへ。

確認：これはどこへ入るか

compactionを生き延びる1つのセッション

プロジェクトshop、セッションA。「次へ」「戻る」のボタンか、矢印キーで進みます。左はこのステップで誰が誰と話しているか、右はコマンドとその出力、下はディスク上で何が変わったかです。

2つのセッション：共有記憶

セッションBが同じフォルダで開きます。

仕事の受け渡しとイベント待ち

他のセッション宛のメッセージは、相手のセッションにユーザーのターンとして届きます。イベントを待つのにtokenはかかりません。チェックを実行するのはタイマーです。

オーケストレーター：1つのセッションが他をまとめる

メモとメッセージの上に載る層です。1つのセッションが目標とボードを持ち、ほかは3つのコマンド、board take、board done、board blockだけを覚えます。オーケストレーターに必要なものはすべて状態ファイルにあり、transcriptは読みません。これは複数のウィンドウをまたぐ協調と、人間への連絡線であって、自律的に目標へ向かって走ることではありません。1つのセッションを、評価役が確かめられる1つの条件へ向けて動かすのは、Claude Code自身の/goalの役目です。

設定

2階層あります。グローバルのファイル~/.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

キーは40個ほどあります（完全な一覧は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以外のいちばん古いエントリから1件ずつ落とすのであって、新しいほうを末尾で切り捨てることはありません。
• アプリのresumeはpriorCliSessionIdsでつながります。CLIの/clearは経験則で、「同じフォルダ、3分以内に理由clearで終了」です。
• socketとtranscriptの形式は文書化されていません。Claude Codeのバージョンが変わると、動いているセッションへのsendが真っ先に壊れます。受信箱のキューは動き続けます。
• macOSのタイマーの下では、pythonが~/Documentsにアクセスできないことがあります(TCC)。チェックはそこに依存しません。アクセスできない場合、メッセージは、~/.claude以下のセッションディレクトリに置かれます。
• サブエージェントはダイジェストを受け取りません。/rewindはメモを巻き戻しません。

詳しくはリポジトリのREADME.md、docs/REFERENCE.md、docs/ORCHESTRATOR.md、そしてlongrun help。