handoffgen

handoffgen

タスクの途中で停止したエージェントの作業の痕跡は、直近で作成したコミット、レビュー待ちのプルリクエスト、作業中に記録した TODO の 3 か所に散らばっています。作業を引き継ぐ次のエージェントは、安全に続行する前にその痕跡を再構成しなければなりません。handoffgen は、渡された情報をまとめて、コールドスタート用のブリーフを作成します。これは、新しいエージェントが最初から最後まで読めば、状態を一から再確認することなく正しく作業を開始できる、短い Markdown ドキュメントです。

事実を入力してください。直近のコミットは入力順に表示され、各ハッシュは件名の隣にバッククォートで囲んで表示されます。オープンなプルリクエストも入力順に表示され、ブロック中として指定されたプルリクエストには [blocked] マーカーが表示されるため、誰も停滞状態を再発見するために時間を費やす必要はありません。TODO は優先度別に分類されます。最初に優先度が高い項目、次に通常、最後に低い項目が表示され、それぞれの分類内では指定した順序が維持されます。優先度が高い項目には [high] が先頭に付き、所在（たとえばファイルパス）を示す項目には、その情報がテキストの後に括弧付きで表示されます。自由記述のコンテキストメモを追加すると、その内容は記述したとおりにそのままブリーフの先頭に表示されます。メモが空、または空白文字だけの場合は、メモなしとして扱われます。同じルールで TODO の出典を表示するかどうかも決まります。

空の入力も省略せず、そのまま反映されます。コミットなしで作成したブリーフでは、見出しの下に "No commits supplied." と表示されます。プルリクエストがない場合と TODO がない場合にも、それぞれ対応する行が表示されます。Markdown に加えて、結果にはその根拠となる件数も含まれます。コミット数、オープンなプルリクエスト数、そのうちブロック中の数、TODO 数、優先度が高い TODO 数です。取得、実行、推測は一切行われません。リポジトリを読み込まず、ホスティングサービスに問い合わせず、状態を推測しません。ブリーフは、入力された事実そのものを、初めて読む人向けに整理したものです。

不正な入力、たとえば commits、open_prs、todos の欠落または配列以外の指定、オブジェクト以外の項目、空または文字列以外のハッシュ、件名、タイトル、TODO テキスト、1 以上の整数ではないプルリクエスト番号、真偽値以外の blocked、文字列以外の source または context、"high"、"normal"、"low" 以外の priority は、該当するパスを示す検証エラーとなり、部分的な結果は返されません。項目内のものも含め、認識されない追加フィールドは無視されます。priority がない場合は "normal" として扱い、blocked がない場合は false として扱います。

CLI

npx @reneturcios/handoffgen build --input args.json
npx @reneturcios/handoffgen --version

args.json には、引数オブジェクト全体が含まれます。

{
  "context": "Parser is stable; cache work is mid-flight.",
  "commits": [
    { "hash": "abc1234", "subject": "Add parser" },
    { "hash": "def5678", "subject": "Fix flaky test" }
  ],
  "open_prs": [
    { "number": 12, "title": "Wire up cache" },
    { "number": 13, "title": "Bump deps", "blocked": true }
  ],
  "todos": [
    {
      "text": "Write migration notes",
      "source": "docs/migration.md",
      "priority": "high"
    },
    { "text": "Tidy README" },
    { "text": "Polish icons", "priority": "low" }
  ]
}

結果は JSON として出力されます。

{
  "brief": "# Handoff brief\n\n## Context\nParser is stable; cache work is mid-flight.\n\n## Recent commits\n- `abc1234` Add parser\n- `def5678` Fix flaky test\n\n## Open pull requests\n- #12 Wire up cache\n- #13 Bump deps [blocked]\n\n## TODOs\n- [high] Write migration notes (docs/migration.md)\n- Tidy README\n- Polish icons",
  "counts": {
    "commits": 2,
    "open_prs": 2,
    "blocked_prs": 1,
    "todos": 3,
    "high_priority_todos": 1
  }
}

終了コード：成功時は 0、実行時エラー（入力ファイルの読み取り不能または不正な状態、入力の不正を含む）時は 1、使用方法のエラー時は 2 です。

MCP server

npx -y @reneturcios/handoffgen mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "handoffgen": {
      "command": "npx",
      "args": ["-y", "@reneturcios/handoffgen", "mcp"]
    }
  }
}

ツール

• build_handoff_brief — 呼び出し元が指定したコミット、オープンなプルリクエスト、TODO 項目から、次のエージェント向けのコールドスタート用ブリーフを作成します。

  • commits（配列、必須、空でも可）— 入力順の直近のコミット。各項目は {hash, subject} で、どちらの文字列も空でないこと
  • open_prs（配列、必須、空でも可）— 入力順のオープンなプルリクエスト。各項目は {number, title, blocked?} で、number は 1 以上の整数、title は空でなく、blocked は指定する場合は真偽値であること
  • todos（配列、必須、空でも可）— 未完了の TODO 項目。各項目は {text, source?, priority?} で、text は空でなく、source は指定する場合は文字列、priority は指定する場合は "high"、"normal"、"low" のいずれかであること（省略時は "normal"）
  • context（文字列、任意）— 現在の状態に関する自由記述のメモ。指定されたものとして扱われる場合、記述したとおりにそのまま含まれます。

  {brief, counts} を返します。counts は {commits, open_prs, blocked_prs, todos, high_priority_todos} です。

Docker

docker run -i ghcr.io/cloudcorprecords/handoffgen
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/handoffgen build --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios