Tools Reference

check-merge-ready

Query-only tool that checks if a PR is ready to merge by running all guards.

Parameters

Parameter	Type	Required	Default	Description
owner	string	yes	-	Repository owner
repo	string	yes	-	Repository name
prNumber	number	yes	-	Pull request number
requireUpToDate	boolean	no	false	Require branch to be up to date

Response

{
  "owner": "paolino",
  "repo": "my-project",
  "prNumber": 42,
  "ready": true,
  "report": {
    "allPassed": true,
    "guards": [
      {
        "name": "ci-status",
        "passed": true,
        "message": "All 3 check(s) passed"
      },
      {
        "name": "approval",
        "passed": true,
        "message": "PR is approved"
      },
      {
        "name": "conflicts",
        "passed": true,
        "message": "No merge conflicts"
      }
    ],
    "timestamp": "2026-01-31T10:30:00.000Z"
  }
}

guard-merge

Atomic tool that validates all guards and merges the PR only if all pass.

No bypass

This tool has no force flag by design. If guards fail, the merge is refused.

Parameters

Parameter	Type	Required	Default	Description
owner	string	yes	-	Repository owner
repo	string	yes	-	Repository name
prNumber	number	yes	-	Pull request number
requireUpToDate	boolean	no	false	Require branch to be up to date
mergeMethod	string	no	"rebase"	Merge method: "merge", "squash", or "rebase"
localRepoPath	string	no	-	Local repo path whose base branch should be updated after a successful merge

Successful Response

{
  "owner": "paolino",
  "repo": "my-project",
  "prNumber": 42,
  "merged": true,
  "sha": "abc123def456",
  "localSync": "Local main updated at /code/my-project",
  "report": {
    "allPassed": true,
    "guards": [...],
    "timestamp": "2026-01-31T10:30:00.000Z"
  }
}

When localRepoPath is provided, guard-merge fetches the merged base branch from GitHub over HTTPS using the authenticated gh session, then fast-forwards the local base branch itself. This avoids depending on an SSH origin remote and avoids rebasing whichever branch happened to be checked out.

Failed Response (Guards)

{
  "owner": "paolino",
  "repo": "my-project",
  "prNumber": 42,
  "merged": false,
  "error": "Guards failed: ci-status",
  "report": {
    "allPassed": false,
    "guards": [
      {
        "name": "ci-status",
        "passed": false,
        "message": "1 check(s) failed: Test (FAILURE)"
      },
      ...
    ],
    "timestamp": "2026-01-31T10:30:00.000Z"
  }
}