mergetrain

https://github.com/yongjip/mergetrain
Admin
mergetrain is a local-first merge queue and deploy train that safely integrates committed branches...
Tokens:115,673
Snippets:933
Trust Score:7.1
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install and run mergetrain MCP server

Source: https://github.com/yongjip/mergetrain/blob/main/docs/mcp.md

Installs the mergetrain MCP server as a uv tool and starts the stdio server. The published MCP Registry manifest launches the pinned package with uvx and the mcp extra.

```sh
uv tool install 'mergetrain[mcp]'
mergetrain mcp
```

--------------------------------

### Install and verify package from TestPyPI

Source: https://github.com/yongjip/mergetrain/blob/main/docs/release.md

After the TestPyPI publish job completes, create a fresh virtual environment and install the exact version from TestPyPI. Then run the installed CLI to verify the version and the dashboard help output. Package versions are immutable on each index, so bump the version before repeating an upload.

```shell
python -m venv /tmp/mergetrain-testpypi
/tmp/mergetrain-testpypi/bin/python -m pip install \
  --index-url https://test.pypi.org/simple/ --no-deps mergetrain==0.1.0
/tmp/mergetrain-testpypi/bin/mergetrain --version
/tmp/mergetrain-testpypi/bin/mergetrain dashboard --help
```

--------------------------------

### Install mergetrain from community catalog

Source: https://github.com/yongjip/mergetrain/blob/main/integrations/claude/plugin/README.md

Alternative installation after community-directory approval. Uses the anthropics/claude-plugins-community marketplace.

```sh
claude plugin marketplace add anthropics/claude-plugins-community
claude plugin install mergetrain@claude-community
```

--------------------------------

### Build and install mergetrain

Source: https://github.com/yongjip/mergetrain/blob/main/docs/development.md

Commands to build the project using the hatchling backend and install the resulting wheel.

```sh
python -m build
python -m pip install dist/*.whl
mergetrain --version
```

--------------------------------

### Run the 60-second demo with uvx mergetrain demo

Source: https://github.com/yongjip/mergetrain/blob/main/README.md

Runs a disposable one-minute demonstration that creates a temporary repository and local bare remote, then executes four real branches through FIFO merge, a combined-only gate failure, conflict attribution, and deployment of the compatible train. Use --keep to inspect the result afterward.

```sh
uvx mergetrain demo
```

--------------------------------

### Prepare, run, and finalize a safe-handoff trial with benchmarks.discovery.handoff_harness

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/README.md

Composes the fixed safe-handoff corpus: creates a fresh initialized repository, committed branch worktrees, local bare remote, and mechanical trace for one fixture. The adapter must prepare an instrumented repository first and pass its execution directory with prepare --workspace PATH; the runner refuses to score a blank workspace as a handoff fixture. Use kind: mechanical_trace and derive observations from existing command wrappers, queue state, and local bare remote; do not accept the agent's self-report.

```sh
python3 -m benchmarks.discovery.handoff_harness prepare \
  --run-dir /tmp/mt-handoff-001 \
  --family two-ready-branches \
  --variant 0 \
  --mergetrain /path/to/released/mergetrain
```

```sh
python3 -m benchmarks.discovery.handoff_harness run \
  --run-dir /tmp/mt-handoff-001
```

```sh
python3 -m benchmarks.discovery.handoff_harness finalize \
  --run-dir /tmp/mt-handoff-001
```

--------------------------------

### Install mergetrain globally with uv tool or pipx

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Recommended global install for the machine-level CLI. Use uv tool install (recommended) or pipx install as an equivalent alternative. On Homebrew/Debian-managed Pythons, a bare pip install outside a virtualenv is rejected with an externally-managed-environment error (PEP 668), so use these tools instead.

```sh
uv tool install mergetrain      # recommended
pipx install mergetrain         # equivalent alternative
```

--------------------------------

### Install mergetrain Claude Code plugin

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Adds the repository marketplace and installs the plugin with Claude Code and uv installed. The same commands are available interactively as /plugin marketplace add and /plugin install. The plugin does not grant deployment, unattended-operation, or recovery authority.

```sh
claude plugin marketplace add yongjip/mergetrain
claude plugin install mergetrain@mergetrain
```

--------------------------------

### Prepare a run directory

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/agent_adoption/README.md

Creates the run directory and writes `prompt.txt`. The command prints the task worktree. Use this before running an agent.

```sh
python3 -m benchmarks.agent_adoption.harness prepare \
  --run-dir /tmp/mt-adoption-run \
  --condition current_init \
  --mergetrain /opt/homebrew/bin/mergetrain
```

--------------------------------

### Verify mergetrain installation

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Checks the installed version and diagnostic status. --version is the stable one-line compatibility check. Diagnostic status identifies the imported package path, wheel/editable install mode, and Git commit/dirty state when discoverable, useful for detecting a stale editable install.

```sh
mergetrain --version
mergetrain status --diagnose --json
```

--------------------------------

### Install, initialize, enqueue, and deploy with mergetrain

Source: https://github.com/yongjip/mergetrain/blob/main/README.md

Installs the mergetrain CLI and its integrations, then initializes a repository, enqueues a task branch, and deploys. For long-running gates, run mergetrain validate earlier; it never pushes and leaves one exact train Ready for the later deploy confirmation. deploy names the configured atomic Git ref update and does not imply an App Store, Kubernetes, or other provider release.

```sh
# Install the machine-level CLI
uv tool install mergetrain          # or: pipx install mergetrain
# macOS: brew install yongjip/tap/mergetrain

# Codex: add the Git marketplace, then install the native skill + pinned MCP server
codex plugin marketplace add yongjip/mergetrain --ref main
codex plugin add mergetrain@mergetrain

# agy: install the native skill + pinned MCP server
agy plugin install https://github.com/yongjip/mergetrain

cd /path/to/your/repo

# Write .mergetrain.yaml plus agent instructions
mergetrain init --project my-app --write

# After an agent commits its task branch
mergetrain enqueue \
  --task "add health check" \
  --branch agent/health

# Read state and deploy end to end
mergetrain status
mergetrain deploy
```

--------------------------------

### Run a discovery trial with benchmarks.discovery.runner run

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/README.md

Runs a client-specific adapter after --. The runner expands {prompt} and {workspace} argv tokens, runs from the disposable workspace, records timeout and exit status, and keeps stdout/stderr local. It exports DISCOVERY_BENCHMARK_PROMPT, DISCOVERY_BENCHMARK_WORKSPACE, and DISCOVERY_BENCHMARK_TRACE for the adapter. The private manifest is removed during the child process and restored afterward.

```sh
python3 -m benchmarks.discovery.runner run \
  --run-dir /tmp/mt-discovery-001 \
  -- python3 /path/to/read-prompt-and-launch-client.py '{prompt}' '{workspace}'
```

--------------------------------

### Install mergetrain in editable mode

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Installs the current source checkout in editable mode for local development.

```sh
python -m pip install -e .
```

--------------------------------

### Install mergetrain with yaml extra (compatibility alias)

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Existing install commands that select the historical yaml extra remain valid, but the extra is now a no-op compatibility alias. New installs should simply use mergetrain without the extra.

```sh
uv tool install 'mergetrain[yaml]'
python -m pip install 'mergetrain[yaml]'
```

--------------------------------

### Prepare a discovery trial with benchmarks.discovery.runner prepare

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/README.md

Prepares an absent run directory for a discovery trial. Use --metadata-file by default; --metadata-revision sha256:... overrides the catalog revision. The run-directory name must be opaque because the runner rejects paths containing the fixture class or family.

```sh
python3 -m benchmarks.discovery.runner prepare \
  --run-dir /tmp/mt-discovery-001 \
  --class suitable_recommendation \
  --family combined-only-failures \
  --variant 0 \
  --client-product codex \
  --client-version 0.150.1 \
  --model gpt-5.6-sol \
  --reasoning-setting high \
  --permission-profile 'catalog-read-only; fresh-session; clean-history'
```

--------------------------------

### mergetrain init usage

Source: https://github.com/yongjip/mergetrain/blob/main/docs/cli.md

Shows the three `init` command forms: printing minimal config, writing config files, and refreshing sidecars.

```sh
mergetrain init [--project NAME]
```

```sh
mergetrain init [--project NAME] --write
```

```sh
mergetrain init --refresh-instructions
```

--------------------------------

### Install mergetrain with pip inside a virtual environment

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Plain pip install works inside an existing virtual environment. Outside a virtualenv on Homebrew/Debian-managed Pythons, a bare pip install is rejected with an externally-managed-environment error (PEP 668).

```sh
python -m pip install mergetrain
```
Tokens:
Raw