README
¶
Compair CLI
Compair CLI helps developers catch cross-repo drift from the terminal. Track your backend, frontend, SDK, CLI, desktop app, and docs in one shared review context. Compair compares changes across related repos and surfaces conflicts, hidden overlap, and missing updates before they turn into broken workflows or user-facing issues.
Why it's different: most AI review tools look at one pull request in one repo. Compair reviews a repo in the context of the other repos it depends on.
- Catch backend/frontend/SDK/docs drift earlier
- Review changes in the context of the rest of your product
- Turn high-confidence findings into CI checks when you're ready
Try It In 5 Minutes
The fastest way to see what Compair does:
# 1) Install Compair CLI
# 2) Run the disposable demo
compair demo
What the demo does
- creates a disposable workspace
- tracks two small related repos
- runs a real Compair review
- shows the kind of cross-repo issues Compair is built to catch
Start here if: you want the fastest possible first pass before trying Compair on your own repos.
Install
Choose the path that fits your workflow:
| Path | Use when... |
|---|---|
| Download a release | You want the fastest setup on macOS, Linux, or Windows. |
| Build from source | You want to inspect the code, hack on the CLI, or run the latest checkout. |
Download a release
Start from the GitHub Releases page. Release archives are published for macOS, Linux, and Windows.
Build from source
go build -o compair .
If you want source-based install details or deeper command reference material, see docs/user_guide.md.
Choose Your Start
Demo
Use this if you want to see Compair end-to-end in a disposable workspace.
compair demo
Local / self-hosted
Use this if you want to evaluate Compair locally with managed Core.
compair profile use local
compair core up
compair login
Cloud
Use this if you want the simplest shared setup.
compair profile use cloud
compair login
New here? Start with compair demo.
Evaluating open/local? Start with Local.
Working with teammates right away? Start with Cloud.
Example
You change an API field name in a backend repo. The web app and CLI still reference the old name.
Compair reviews the repos together and flags the mismatch before the change reaches users or turns into a broken workflow.
Potential Conflict
backend-api: review response now uses `items`
web-app / developer-cli: still read `reviews`
Likely impact: clients show fallback values or missing review data
Compair surfaced a high-confidence drift issue across related repos that would not appear in a single-repo review.
Try It On Your Own Repo Suite
Use this after you've run the demo and want to test Compair on the repos that make up your actual product surface.
Before you start:
- Put all related repos in one group
- Upload baselines first
- Then run one warm review across the group
# 1. Choose a profile and create a shared review group
compair profile use local
# or: compair profile use cloud
compair login
compair group create "Product Suite"
compair group use "Product Suite"
compair self-feedback on
compair feedback-length brief
# 2. First-run bootstrap only:
# index each related repo before asking for cross-repo feedback
compair track ~/code/backend-api --initial-sync --no-feedback
compair track ~/code/web-app --initial-sync --no-feedback
compair track ~/code/developer-cli --initial-sync --no-feedback
compair track ~/code/desktop-client --initial-sync --no-feedback
# repeat for any other repos in the shared product surface
# 3. Run the warm review pass across the whole group
compair review --all --snapshot-mode snapshot --reanalyze-existing --feedback-wait 90
# 4. Inspect the results
compair reports
compair notifications
After the first run:
- Start with
brief - Expect the first baseline to take longest
- After the warm pass, use normal
review/synccycles day to day - Treat
--initial-sync --no-feedbackas a one-time bootstrap step, not the normal daily workflow
For the full step-by-step workflow, see docs/cross_repo_workflow.md.
Feedback Length
| Setting | Use it when... |
|---|---|
brief |
You want a fast, readable signal. Recommended for first full-suite reviews and most daily use. |
detailed |
You want more context and rationale for a smaller number of findings. |
verbose |
You are actively debugging a specific result and want the most supporting detail. |
Add Compair To CI When You're Ready
Start in advisory mode:
compair sync --json
Move to a conservative failing check:
compair sync --json --gate api-contract
Tighten rules later as you build trust in the signal.
If the term gate is unfamiliar, treat it as the rule that decides whether CI should fail.
| Command | What it does | Use it when... |
|---|---|---|
compair sync --json |
Advisory only. Produces machine-readable output and a Markdown report, but does not fail CI on its own. | You are introducing Compair and want visibility without disruption. |
compair sync --json --gate api-contract |
Fails CI on high-severity potential_conflict notifications. |
Best first production preset. |
compair sync --json --gate cross-product |
Fails CI on broader high-severity cross-product issues. | You want more than API contract checks, but still want a conservative threshold. |
compair sync --json --gate review |
Fails CI on high-severity conflicts and review-oriented updates. | You want stronger code-review style enforcement. |
compair sync --json --gate strict |
Fails CI on high and medium issues across a broader set of notification types. | Use on integration or release branches after you trust the signal. |
Recommended rollout: start with visibility, then fail only on the highest-confidence issues, then tighten thresholds later.
See docs/ci_review_examples.md for GitHub Actions and GitLab CI examples.
Docs
New users should start with the demo, user guide, or cross-repo workflow. Maintainers and operators can use the advanced docs below.
Start Here
Advanced / Maintainer Docs
Documentation
¶
There is no documentation for this package.
Source Files
Directories