Forklift

Agent-assisted upstream integration for custom forks.

Forklift keeps your custom fork moving with upstream without turning every update into a manual merge ritual. It does the boring Git/worktree/test/report plumbing deterministically and leaves agents for the hard semantic parts.

Status: early alpha, dogfooded on SnowfallHD/hermes-agent.

Why

If you maintain a customized fork of a fast-moving OSS project, a normal git pull upstream main is risky:

• your local behavior can be silently overwritten,
• conflicts land in your live checkout,
• tests and semantic-risk checks are easy to forget,
• agents waste tokens on Git plumbing instead of judgment.

Forklift creates an isolated integration branch/worktree, attempts the upstream merge there, captures status/report JSON, and optionally commits the clean merge. Your main checkout stays untouched until you explicitly promote.

Install

For now:

git clone https://github.com/SnowfallHD/forklift.git
cd forklift
python -m pip install -e .
forklift --help

Or run from source:

PYTHONPATH=src python -m forklift.cli --help

Quick start

From any customized fork with origin as your fork and upstream as the source project:

forklift check --repo .
forklift prepare --repo . --base origin/main --upstream upstream/main --commit
forklift status --repo .
forklift conflicts --repo . --json
forklift report --repo .

If the merge is clean, Forklift creates a branch/worktree under ~/.cache/forklift/worktrees/ and can commit the merge in that isolated worktree.

If conflicts occur, Forklift exits with code 2, records the conflict list, and leaves your live checkout alone. forklift conflicts --json emits structured conflict packets with paths, hunk counts, previews, and refs for an agent or human reviewer.

Commands

forklift check # inspect remotes, branch, dirty state, divergence
forklift prepare # create isolated worktree + integration branch, merge upstream
forklift status # show latest run for this repo
forklift conflicts # emit structured conflict packets for latest run
forklift report # render a Markdown integration report
forklift test# run configured or supplied test commands in integration worktree
forklift promote # guarded push helper for a prepared branch

Safety model

Forklift is conservative by default:

• does not mutate your main checkout during prepare,
• uses Git worktrees for integration,
• records run manifests outside the repo by default,
• treats conflicts as data, not failure to hide,
• requires explicit promotion/push.

Hermes integration plan

Forklift is intentionally CLI-first. Hermes integration should be a thin adapter:

• Hermes plugin slash commands: /forklift check, /forklift prepare, /forklift report
• MCP tools: forklift_check, forklift_prepare, forklift_status, forklift_promote
• dashboard plugin: an update/integration panel that shells out to the CLI

The engine stays generic so Claude Code, Codex, OpenClaw, Cursor, and plain shell users can adopt it too.

License

MIT