repoq

Comprehensive Git repository query CLI with structured JSON output.

repoq replaces brittle git/gh command pipelines when you need reliable, machine-readable repository state in scripts and agent workflows.

What it does

repoq can query:

1. status: one-shot repository snapshot
   • Combines repository identity, full branch info (tracking, worktree, PR, default-branch relation), working-tree breakdown, worktree summary, and last commit.
2. branch: branch state with repo/GitHub context
   • Reports checkedOut, localRef, and remoteRef separately.
   • Detects isDetached and isUnborn (checked-out branch with no commits).
   • Includes upstream tracking (ahead/behind), worktree location, PR summary, default-branch relation.
3. diff-range: merge-base comparison summary
   • Compares merge-base(base, head)..head and includes commit count/messages.
   • Parses conventional commit metadata (isConventional, type).
   • Splits changed files into added/modified/deleted/renamed plus insertion/deletion totals.
   • Reports fastForwardable and handles unborn head via headState: "unborn".
4. worktrees: full worktree inventory
   • Parses git worktree list --porcelain.
   • Adds per-worktree cleanliness and uncommitted-change counts.
   • Detects unborn worktrees (isUnborn) and extracts issue IDs from branch names.
   • Supports filtering by --issue-id and --uncommitted-only.
5. pr: pull request detail + derived summaries
   • Wraps gh pr view --json ... for core PR metadata.
   • Derives check summary (passing/failing/pending) and review summary.
   • Adds unresolved thread/comment counts via GitHub GraphQL.
6. default-branch: resilient default-branch resolver
   • Resolution chain: gh repo view -> refs/remotes/origin/HEAD -> git remote set-head origin --auto retry -> main/master probes.

Requirements

• Node.js >= 22.14.0
• Git
• GitHub CLI (gh) for GitHub-backed queries

Install / run

# one-off
npx -y repoq status --json

# global
pnpm add -g repoq
repoq status --json

Run it from inside a Git repository.

Usage

repoq <command> [options]

Common examples:

# Get current branch name
repoq status --json | jq -r '.branch.current'

# Check if working tree is clean
repoq status --json | jq '.workingTree.isClean'

# Check upstream tracking
repoq status --json | jq '.branch.tracking | {ahead, behind}'

# Check if PR exists for current branch
repoq status --json | jq '.branch.pr.exists'

# Count commits since main
repoq diff-range --json | jq '.commits.count'

# List worktrees with uncommitted changes
repoq worktrees --uncommitted-only --json | jq '.[].path'

# Check if PR is approved
repoq pr --json | jq '.reviews.approved > 0'

# Check CI status
repoq pr --json | jq '.checks.failing == 0'

# Verify all commits are conventional
repoq diff-range --json | jq '[.commits.messages[].isConventional] | all'

# List changed files
repoq diff-range --json | jq '.files.added + .files.modified | .[]'

# Inspect a specific branch
repoq branch feature/login --json | jq '.tracking'

Command reference

| Command | Purpose | | ----------------------------------------------------------- | ------------------------------------------------------------------------- | | status [--json] | One-shot repo snapshot with full branch info, working tree, last commit | | branch <branch> [--json] [--issue-id <id>] | Branch lifecycle/tracking/worktree/PR status with unborn detection | | diff-range [base] [--json] [--head <branch>] | Merge-base diff summary, commit metadata, file/stats, fast-forwardability | | worktrees [--json] [--issue-id <id>] [--uncommitted-only] | Enumerate worktrees with cleanliness/unborn state and filters | | pr [branch] [--json] | PR metadata plus checks/reviews/unresolved summaries | | default-branch [--json] | Resolve default branch with GitHub + git fallbacks |

For detailed command help:

repoq --help
repoq <command> --help

Environment variables

| Variable | Description | | ---------------- | ----------------------------------------------- | | REPOQ_GIT_PATH | Path to git binary (default: git from PATH) | | REPOQ_GH_PATH | Path to gh binary (default: gh from PATH) |

Agent rule

Add to your CLAUDE.md or AGENTS.md:

# Rule: Use `repoq` for Repository Queries

Run `npx -y repoq --help` to learn available options.

Use `repoq` when you need structured, machine-readable Git and GitHub
repository state. It replaces brittle `git`/`gh` command pipelines with
reliable JSON output for scripts and agent workflows.

License

MIT