Analyzes git repositories to detect merge conflicts before branches are merged. Runs mergelock check on two branches, using git merge-tree and tree-sitter parsers to report textual conflicts, add/add, modify/delete, signature/caller mismatches, and duplicate definitions, without ever touching the working tree.
A git-native merge gate. mergelock check compares two branches before
they meet and reports the conflicts git itself won't tell you about: a
function whose signature changed on one branch while the other branch
added calls to the old signature, a symbol deleted on one side but still
used on the other, the same function written twice.
It never touches your working tree. Everything is computed from commits
with git merge-tree and tree-sitter parsers, so it is safe to run in a
pre-push hook, in CI, or from an AI coding agent over MCP.
Rule | Reports | Severity |
| Ordinary git content conflicts | error |
| Both branches add a file at the same path | error |
| One branch edits a file or symbol the other deletes, or still calls a deleted symbol | error |
| A signature changed on one branch; the other adds calls that no longer fit | error |
| Both branches add the same function, by name or by near-identical body | warning |
Semantic rules understand TypeScript, JavaScript (incl. TSX/JSX) and Python. Files in other languages still get the textual, add/add and modify/delete checks.
Related MCP server: Git Insight MCP
mergelock needs git 2.38 or newer (for git merge-tree --write-tree).
Prebuilt binary (macOS and Linux, amd64 and arm64): download the archive
for your platform from the
latest release,
then put mergelock on your PATH:
tar -xzf mergelock_*_$(uname -s | tr A-Z a-z)_*.tar.gz
sudo mv mergelock /usr/local/bin/On macOS, a binary from an archive downloaded in a browser is blocked by Gatekeeper because it isn't signed yet. Clear the quarantine flag once:
xattr -d com.apple.quarantine /usr/local/bin/mergelockWith Go (needs Go 1.25 or newer and a C compiler, since cgo is used for
tree-sitter; on macOS install the Xcode command-line tools, on
Debian/Ubuntu build-essential):
go install github.com/sadayamuthu/mergelock/cmd/mergelock@latestWith Docker (linux/amd64 and linux/arm64; mount the repository at /repo):
docker run --rm -v "$PWD":/repo ghcr.io/sadayamuthu/mergelock check my-branch main --format text
docker run -i --rm -v "$PWD":/repo ghcr.io/sadayamuthu/mergelock # MCP server on stdioOr build from source:
git clone https://github.com/sadayamuthu/mergelock.git
cd mergelock
go build -ldflags "-X main.version=$(git describe --tags --always)" -o mergelock ./cmd/mergelockCheck it works:
mergelock versionRun inside any git repository:
# Is my branch safe to merge into main?
mergelock check my-feature main
# Compare against the configured target (main by default)
mergelock check my-feature
# Will two in-flight branches collide with each other?
mergelock check feat-a feat-b --format textExit codes make it easy to script:
Code | Result |
0 |
|
1 |
|
2 |
|
3 | operational error (bad branch name, not a git repo, invalid config…) |
See USAGE.md for the full command reference, the
.mergelock.yml config, the JSON output schema, CI and git-hook recipes,
and how to connect it to an AI agent over MCP.
go test ./... # full suite, incl. fixture gate and 5,000-file perf test
go test -short ./... # skips the perf test
go vet ./...
gofmt -l .Rule behaviour is pinned by branch-pair fixtures in testdata/fixtures/*.txtar;
each one is a tiny repo with a base, two branches and the expected findings.
Check a branch against another for textual and semantic merge conflicts. Returns a mergelock verdict (schema v1) with findings an agent can act on.
| Name | Required | Description | Default |
|---|---|---|---|
| branch | No | branch to check; defaults to the current branch | |
| against | No | branch to compare against; defaults to the configured target |
| Name | Required | Description |
|---|---|---|
| base | Yes | |
| notes | No | |
| stats | Yes | |
| result | Yes | |
| version | Yes | |
| branches | Yes | |
| coverage | Yes | |
| findings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that both textual and semantic analysis happen and that the output is a 'mergelock verdict (schema v1)' with actionable findings, which is useful behavioral context. It does not state whether the operation is read-only, what permissions or repo state it requires, or how large a comparison it tolerates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the core purpose front-loaded; the second sentence earns its place by flagging the structured verdict. Slight redundancy with the existing output schema keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only two optional parameters, full schema description coverage, and an output schema that carries return-value detail, the description covers purpose and result shape adequately. The missing piece is invocation guidance (preconditions, when to prefer this over other checks), which is a modest gap for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters document their defaults, so the baseline is 3. The description adds no parameter-level detail (e.g., whether branch names accept refs/commits), so it does not exceed the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource (check one branch against another for textual and semantic merge conflicts), which fully disambiguates the generic tool name 'check'. It does not name or differentiate from the sibling 'claims', but that sibling appears unrelated, so the gap is minor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the agent can infer this is a pre-merge verification step, but there is no explicit when-to-use, when-not-to-use, or alternative named. Nothing misleads, but nothing routes the agent either.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List live claims (declared work scopes) from refs/mergelock/claims, newest first, so you can pick an area no other agent is working in. Read-only in v0.1.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| claims | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does disclose key traits: 'Read-only in v0.1' (safety profile plus a version caveat) and 'newest first' (result ordering). It omits pagination/limits and any auth expectations, so it is not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and resource, then the source ref, ordering, purpose, and safety note in a natural progression. Every clause earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the read-only nature plus ordering are covered. For a zero-param listing tool this is nearly complete; only pagination or scope limits (e.g. how many claims are returned) are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the rubric the baseline is 4 with nothing for the description to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (live claims), expands the jargon with 'declared work scopes', and names the storage ref refs/mergelock/claims. It does not explicitly distinguish itself from the sibling 'check', so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'so you can pick an area no other agent is working in' gives a clear intended context for calling it, which is stronger than implied usage. However it names no alternative and states no when-not condition, so it stops short of explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0checkclaimsScored across 2 tools
The two tools have clearly distinct purposes: check runs a merge-conflict analysis on branches, while claims lists declared work scopes. An agent can easily tell which to use in a given situation with no overlap.
Both names are single lowercase words, but one is a verb (check) and the other a noun (claims), so there is no predictable verb_noun convention. It is readable but not a consistent pattern.
With only 2 tools the surface feels thin for a merge-lock/claim coordination system. It is defensible for a v0.1, but limited.
The claims tool is explicitly read-only in v0.1, so there is no way to declare or release a claim, and only a single conflict-check operation exists. Notable lifecycle gaps remain, though the descriptions acknowledge the v0.1 scope.
Freeze and unfreeze merges across a GitHub organization, with an audit trail.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Audit GitHub repos for malicious and supply-chain code before you depend on them.
Scan packages and lockfiles (npm, PyPI, Go, Maven, Cargo, NuGet) for vulnerabilities and malware.
