treeman

treeman

複数のエージェントが同じリポジトリで同時に作業する場合、 通常はそれぞれに専用の git worktree が割り当てられます。 しばらくすると、どのツリーが誰のものなのか、 どれに未コミットの作業が残っているのか、どれを安全に 削除できるのかが分からなくなります。treeman は、 すでに把握している事実をもとに、そうした疑問に答えます。 各 worktree について、そのパス、チェックアウトされている ブランチ、所有者がいればその所有者、未コミットの変更の 有無、最後に変更されてから経過した日数、ロックされているか どうかを指定します。さらに、ツリーが古いとみなされる 非アクティブ期間のしきい値と、任意でメインツリーのパスも 指定します。treeman は、所有者マップ、各ツリーの状態と クリーンアップのアクション、集計値を含むプランを返します。 git を実行することも、ファイルシステムに触れることもなく、 指定された事実だけをもとにプランを作成します。

各ツリーは固定された一連のチェックで判定され、最初に 一致したものが適用されます。パスが指定された main_path と 一致するツリーは main となり、常に保持されます。 ロックされたツリーは locked となり、保持されます。 変更のあるツリーは blocked となり、保持されます。 未コミットの変更を削除するプランが作成されることは ありません。しきい値を超えて古く、所有者のいないツリーは orphaned となり、削除対象となる唯一の種類です。 所有者がいてしきい値を超えて古いツリーは stale となり、 レビュー対象としてマークされます。記録された所有者がいない 最近のツリーは unowned となり、こちらもレビュー対象に なります。所有者がいて最近アクティブだったツリーは active となり、保持されます。古さの判定には厳密な大なり比較を 使用します。最後のアクティビティがちょうど stale_days 日前の ツリーは、古いとはみなされません。

所有者について、判定が固定されている点が一つあります。 所有者が存在しない、空である、または空白文字だけの場合、 そのツリーは所有者なしとみなされ、所有者は null として 報告されます。結果の owners マップには、ほかのすべての 所有者と、その所有者が持つパスが指定順に記載されます。 所有者のキーは昇順に並びます。所有者のいないツリーは このマップに含まれません。counts には合計数、状態ごとの 件数、およびプランで remove とマークされたツリーの数を 示す removable が含まれます。

不正な入力（worktree リストがない、または空、path や branch がない、空、または文字列ではない、owner が 文字列ではない、dirty がない、またはブール値ではない、 locked がブール値ではない、日数が負数または小数、 stale_days が不正、または main_path が空）は、問題のある パスを示すバリデーションエラーとなり、部分的な結果は 返されません。パスが同じ worktree が二つある場合は、 重複したパスを示すエラーになります。未知の追加フィールドは 無視されます。

CLI

npx @reneturcios/treeman plan --input args.json
npx @reneturcios/treeman --version

args.json には引数オブジェクト全体を記述します。

{
  "worktrees": [
    {
      "path": "/trees/main",
      "branch": "main",
      "owner": "alice",
      "dirty": false,
      "last_activity_days": 0
    },
    {
      "path": "/trees/old-experiment",
      "branch": "exp/spike",
      "dirty": false,
      "last_activity_days": 74
    },
    {
      "path": "/trees/agent-2",
      "branch": "feat/search",
      "owner": "agent-2",
      "dirty": true,
      "last_activity_days": 1
    }
  ],
  "stale_days": 30,
  "main_path": "/trees/main"
}

プランは JSON として出力されます。

{
  "worktrees": [
    {
      "path": "/trees/main",
      "branch": "main",
      "owner": "alice",
      "status": "main",
      "cleanup": "keep",
      "reason": "primary worktree"
    },
    {
      "path": "/trees/old-experiment",
      "branch": "exp/spike",
      "owner": null,
      "status": "orphaned",
      "cleanup": "remove",
      "reason": "no owner and inactive beyond the stale threshold"
    },
    {
      "path": "/trees/agent-2",
      "branch": "feat/search",
      "owner": "agent-2",
      "status": "blocked",
      "cleanup": "keep",
      "reason": "uncommitted changes present"
    }
  ],
  "owners": {
    "agent-2": ["/trees/agent-2"],
    "alice": ["/trees/main"]
  },
  "counts": {
    "total": 3,
    "main": 1,
    "locked": 0,
    "blocked": 1,
    "orphaned": 1,
    "stale": 0,
    "unowned": 0,
    "active": 0,
    "removable": 1
  }
}

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

MCP サーバー

npx -y @reneturcios/treeman mcp

MCP クライアントの設定：

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

ツール

• plan_worktrees — 呼び出し元から渡されたワークツリーの情報（所有者マップ、各ワークツリーの状態、削除しても安全なワークツリー）に基づいて、並列エージェント用の Git ワークツリーを計画します。

  • worktrees（配列、必須、1 項目以上）— 呼び出し元の順序で計画するワークツリー。各項目は次のとおりです。
    • path（文字列、必須、空でない）— ワークツリーのパス
    • branch（文字列、必須、空でない）— ワークツリーでチェックアウトされているブランチ
    • owner（文字列、任意）— ワークツリーを所有するエージェントまたは人。省略、空、または空白のみの場合は、所有者なしとして扱います
    • dirty（ブール値、必須）— ワークツリーにコミットされていない変更があるかどうか
    • last_activity_days（整数、必須、0 以上）— ワークツリーが最後に変更されてからの日数
    • locked（ブール値、任意）— ワークツリーがロックされているかどうか。省略した場合は false です
  • stale_days（整数、必須、0 以上）— 非アクティブ状態とみなす日数のしきい値。この日数を超えるとワークツリーは古いとみなされます（ちょうどこの日数の場合は該当しません）
  • main_path（文字列、任意）— プライマリーワークツリーのパス。クリーンアップの対象にはなりません

  {worktrees, owners, counts} を返します。worktrees には入力された各ワークツリーについて、入力順に {path, branch, owner, status, cleanup, reason} が格納されます（所有者がいない場合、owner は null）。owners は各所有者とそのパスを対応付けます。counts は {total, main, locked, blocked, orphaned, stale, unowned, active, removable} です。

Docker

docker run -i ghcr.io/cloudcorprecords/treeman
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/treeman plan --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