merge-ready

merge-ready is a Rust CLI that reports whether the pull request for your current branch is mergeable. It prints concise status tokens designed for shell prompt integration and automation scripts.

Install

cargo install merge-ready

For development builds:

cargo install --path .

Usage

Show top-level help:

merge-ready --help

Show merge status tokens for prompt integration:

merge-ready prompt

Bypass the daemon cache and fetch fresh state directly from gh:

merge-ready prompt --no-cache

Example output:

⚠ review

merge-ready prompt returns:

• 0 when mergeable (✓ merge-ready)
• 1 when blocked (⚠ ... or ✗ ...)
• 2 when state cannot be determined (? ...)

This makes it easy to use from shell scripts and prompt hooks.

Output Tokens

• ✓ merge-ready - ready to merge
• ⚠ review - changes were requested in review
• ⚠ ci-action - CI checks are still in progress
• ✗ ci-fail - CI checks failed
• ✗ conflict - merge conflicts exist
• ✗ update-branch - branch is behind base branch
• ? sync-unknown - branch sync status is unknown
• ? loading - cache miss; daemon is fetching in the background

Background Daemon

merge-ready uses a background daemon to cache GitHub API results and serve prompt queries with near-zero latency.

The daemon starts automatically the first time merge-ready prompt runs. You can also manage it manually:

merge-ready daemon start   # start the background daemon (returns immediately)
merge-ready daemon stop    # stop the running daemon
merge-ready daemon status  # show pid, cache entries, and uptime

On the first query the daemon has no cache yet, so ? loading is printed while it fetches in the background. Subsequent calls return the cached value instantly.

The daemon exits automatically after 30 minutes of inactivity.

Starship Integration

Add merge status to your Starship prompt by using a custom command module in ~/.config/starship.toml:

[custom.merge_ready]
command = "merge-ready prompt"
when = true
require_repo = true
shell = ["/bin/zsh"]
format = "[$output]($style) "
style = "bold yellow"

require_repo = true limits the module to git repositories without any shell command overhead. merge-ready prompt itself returns ? ... tokens when there is no associated PR, so no additional filtering is needed.

If your environment sets STARSHIP_SHELL to a slower shell (for example fish), custom modules can be noticeably slower due to shell startup cost. Pinning shell = ["/bin/zsh"] (or another lightweight shell on your system) keeps prompt latency low.

Requirements

• gh CLI installed and authenticated
• Current git branch linked to an existing GitHub pull request

Features

• Minimal output focused on actionable blockers
• Prompt-friendly status token output
• Background daemon caches GitHub API results, eliminating per-prompt API calls
• Daemon auto-starts on first use; no manual setup required