Lathe

Claude Code / Codex などの runner を backend にして、PR / issue / direct task を Lathe 管理 branch で処理する CLI。

Lathe は main / develop を占有しません。常設するのは lathe branch / worktree だけです。

Model

user-owned branches
  main, develop, feature/*, ...

lathe branch/worktree
  .lathe/
    config.json
    harness/
      task/      task agent runtime source
      harness/   harness agent runtime source
    plans/
    runs/       task archives copied from Lathe task workspaces
    improvements/

lathe-worktrees/
  task-pr-123/   internal Lathe task workspace (Git worktree)

.latheignore は Git ignore ではありません。user-owned branch と Lathe-managed branch の境界を越えない path を定義する transfer filter です。

user branch / PR branch
  ↓ .latheignore filter
lathe-task/* branch
  ↓ .latheignore filter
user branch / PR branch

たとえば .claude/ や CLAUDE.md を .latheignore に入れると、ユーザー repo が .claude を git 管理していても task agent runtime と衝突しません。Lathe 側の .claude も user branch へ戻りません。

Install

npm install -g lathe-cli

依存：git 2.10+、jq。gh は PR 系コマンドで必要。claude は Claude runners / lathe harness、codex は codex-exec runner で必要です。

Init

新規 project:

mkdir myapp && cd myapp
lathe init

生成物:

myapp/
├── .git/              shared bare repo
├── main/              user app worktree
├── lathe/             Lathe control worktree (branch: lathe)
└── lathe-worktrees/   task run worktrees

lathe init は対話時に helper skill setup を聞きます。

1) Claude Code (.claude/skills/lathe-cli)
2) Codex (.codex/skills/lathe-cli)
3) skip

これは lathe-cli skill だけを追加します。CLAUDE.md や agent role files は作りません。既存 .claude/ がある場合も、既存設定には触らず .claude/skills/lathe-cli/ だけを追加します。非対話実行では helper skill setup は skip されます。

既存 repo:

cd existing-repo
lathe init

生成物:

existing-repo/
├── lathe/             Lathe control worktree (branch: lathe)
└── lathe-worktrees/   task run worktrees

既存 repo では .gitignore や既存 agent role files を変更しません。helper skill setup を選んだ場合だけ .claude/skills/lathe-cli/ または .codex/skills/lathe-cli/ を追加します。lathe/ と lathe-worktrees/ は local exclude に入れます。

Commands

lathe task pr <pr#>              # task agent で PR を処理 (default: claude-tui)
lathe task plan pr <pr#>         # planning only
lathe task process pr <pr#>      # process mode 明示
lathe task process --runner claude-p-stream pr <pr#>
lathe task process --runner codex-exec pr <pr#>
lathe plan pr <pr#>              # legacy wrapper: lathe task plan pr
lathe process <pr#>              # legacy wrapper: lathe task process pr
lathe harness                    # harness agent を起動 (default: claude-tui)
lathe harness --runner claude-p-stream --prompt "最新runを評価して"
lathe harness --runner codex-exec --prompt "eval結果を要約して"
lathe feature <name>             # optional: user feature worktree helper
lathe ls                         # worktree / branch / runs / improvements
lathe eval ...                   # harness fixture eval

lathe task は次を行います。

1. PR metadata を gh で読む
2. internal branch lathe-task/pr-<n> と task workspace lathe-worktrees/task-pr-<n>/ を作る
3. PR head を .latheignore filter 越しに import
4. .lathe/harness/task から CLAUDE.md / AGENTS.md / .claude/ を materialize
5. .lathe/task.json / .lathe/brief.md / .lathe/invocation.json を書く
6. task agent を起動する
7. 成功後、task workspace の descriptor / full filtered source snapshots / plan / transcript logs / patches / exported file snapshot を lathe/.lathe/runs/pr-<n>/ に archive し、remote があれば origin/lathe へ push する

task agent が見る CLAUDE.md / AGENTS.md / .claude は Lathe が生成した task agent 専用 runtime です。PR に混ざった agent runtime ではありません。

成功した process run は default で internal branch lathe-task/pr-<n> と task workspace lathe-worktrees/task-pr-<n>/ を削除します。正本は lathe/.lathe/runs/pr-<n>/ archive です。plan run は後続の process が既存 plan を再利用できるよう default では残します。

Task workflow source は lathe/.lathe/harness/task/workflow/ にある curated harness methodology です。task agent は依頼ごとに workflow を選び、plan HTML を per-task execution contract として .lathe/plans/ に作ります。plan HTML には選択した workflow id / version / source path / selection reason / verification profile が structured metadata として入ります。

Verification profiles は lathe/.lathe/harness/task/verification/ にある reusable methodology です。これは実行ラッパーではなく、どの検証コマンド・証跡・前提を使うべきかを workflow から参照する catalog です。run archive の summary.json には選択された workflow / verification metadata が記録され、後続の harness/meta agent が run 評価や methodology 改善の起点にできます。

cleanup policy は lathe/.lathe/config.json で変えられます。環境変数 LATHE_TASK_CLEANUP がある場合はそちらが優先です。

{
  "task": {
    "cleanup": "process_success"
  }
}

値は process_success、success、never を使います。process_success は process 成功時だけ cleanup、success は plan/process 成功時に cleanup、never は常に残します。

Runner は --runner または LATHE_AGENT_RUNNER で差し替えます。

lathe task process pr 1                         # claude-tui
lathe task process --runner claude-print pr 1   # legacy --print 相当
lathe task process --runner claude-p-stream pr 1
lathe task process --runner codex-exec pr 1

claude-tui は Claude Code TUI に初期 prompt を投入し、hooks で native transcript / subagent transcript を .lathe/runs/<session_id>/ に残します。TUI は人間が必要な permission を選び、完了後に Ctrl-D を2回または /exit で閉じると、Lathe CLI が export/archive に戻ります。

claude-p-stream は claude --print --output-format stream-json を使い、stream JSON を runner artifact として保存します。codex-exec は codex exec --json を使い、Codex の JSONL events / final message を .lathe/runs/<session_id>/runner/codex-exec/ に保存します。

Runner の上限時間は LATHE_AGENT_TIMEOUT_SECONDS で共通指定できます。Claude 系だけなら LATHE_CLAUDE_TIMEOUT_SECONDS、Codex だけなら LATHE_CODEX_TIMEOUT_SECONDS を使います。Codex の model は LATHE_CODEX_MODEL で指定できます。

lathe-task/* branch は Lathe 内部の作業 branch です。外部から参照する正本は lathe branch の .lathe/runs/pr-<n>/ archive です。default cleanup 後は local branch/workspace は残りません。task が見たコード全体は source/imported/ と source/final/、その task での差分は patches/export.diff と patches/task-branch.diff、PR に export されたファイル実体は exported-files/ に残ります。

.latheignore

新規 project の default:

.lathe/
.claude/
CLAUDE.md
AGENTS.md
workflow/
hooks/
plan_template.html

PR 処理では base branch 側の .latheignore を policy として扱います。PR head が .latheignore を変更しても、その変更は base に入るまで filter policy としては効きません。

Harness

Harness source は lathe branch の .lathe/harness/ にあります。

.lathe/harness/task/      task agent 用
.lathe/harness/harness/   harness agent 用

lathe task ... は task runtime を生成します。lathe harness は harness runtime を生成します。常設 branch を task/harness で分ける必要はありません。

lathe harness も --runner / LATHE_HARNESS_RUNNER / LATHE_AGENT_RUNNER を受け付けます。runner artifacts は lathe/.lathe/runs/<session_id>/runner/<runner>/ に残ります。Claude 系 runner では harness runtime の hooks により events.jsonl / transcript.jsonl も保存されます。

Eval

lathe eval は harness fixture runner です。指定した Lathe control ref/commit から隔離 project を作り、fixture の seed / feature patch / task body を使って通常の lathe task ... launcher を走らせます。

lathe eval list
lathe eval run pr-wc-basic --candidate-ref lathe --no-claude
lathe eval run pr-wc-basic --baseline-ref <old-commit> --candidate-ref lathe
lathe eval run pr-wc-basic --candidate-ref lathe --mode process --runner claude-p-stream --timeout 300

candidate だけなら 1 ref、baseline 比較なら 2 ref を評価します。未 commit の harness 変更は評価対象にならないので、評価したい状態を commit または ref にしてから実行します。

default では lathe-eval/<run_id> branch と lathe-worktrees/eval-<run_id>/ Git worktree を作り、その中で eval record と実行用 workspace を扱います。完了後は .lathe/evals/runs/<run_id>/ だけを lathe branch に取り込み、実行用 workspace と eval branch/worktree は削除します。複数 eval を同時に走らせても、最後の lathe branch への取り込みだけが lock 下で直列化されます。

結果は lathe/.lathe/evals/runs/<run_id>/ に eval record として残ります。実行用 workspace は eval branch 側の .lathe/evals/workspaces/<run_id>/ に作られ、通常は終了時に削除されます。

Notes

• lathe eval は fixture 比較です。GitHub API は fixture 用に mock します。実装後の最終確認は実際の gh / GitHub PR / claude で行います。
• 旧 develop/meta layout で壊れた project は lathe migrate-gitignore で runtime tracked 状態を修復できます。