Code Mower

Code Mower helps teams set up AI peer-programmer and reviewer lanes on real GitHub pull requests, then measure which builders and reviewers are useful on their actual codebase.

Code Mower is beta, bring-your-own-agent-loop software for teams willing to calibrate reviewers. It is not a drop-in autonomous merge gate.

The short version:

• create safe, manual-first reviewer lanes for Codex, Claude, Gitar, and other AI review tools;
• run setup diagnostics before a lane can surprise you with spend, source exposure, or GitHub Actions churn;
• turn issue text, external docs, and project doctrine into local work orders before an agent starts coding;
• generate local reviewer value reports from known-clean and known-blocked PRs; and
• optionally share sanitized metadata with CodeMower.com for private team dashboards today and aggregate benchmarks as that dataset becomes useful.

Code Mower is local-first. The OSS tool works without the hosted service. Default cloud bundles exclude source code, raw diffs, raw model transcripts, raw stdout/stderr, auth output, and secrets.

Design Principles

Code Mower should feel like an engineering tool, not a demo harness:

• Local first: install, diagnose, audit, and report without a hosted account.
• Manual first: new reviewer lanes start explicit and observable before they can affect merge policy.
• Evidence first: promote lanes from real calibration data on your repository, not from generic benchmark claims.
• Privacy first: cloud sharing is opt-in metadata by default, with source, diffs, transcripts, auth output, and secrets excluded.
• Composable by design: providers, lenses, context packs, calibration, and cloud upload stay separate so teams can adopt only the parts they trust.

What It Looks Like

code-mower doctor --preflight is the first useful command. It checks your runtime, GitHub setup, provider CLIs, token posture, optional cloud setup, and private-repo Actions cost traps. --preflight is the friendly first-run preset; doctor --v05 remains an equivalent compatibility alias for older scripts.

Example, shortened:

$ code-mower doctor --preflight
PASS  config.validate             config validates
PASS  profile.select              selected profile: codex, claude_audit, gitar
PASS  runtime.python              Python 3.12 satisfies Code Mower requirements
PASS  runtime.github_auth         GitHub CLI auth probe succeeded
PASS  runtime.local_cli codex     codex found
PASS  runtime.local_cli claude    claude auth smoke probe succeeded
WARN  env.tokens codex            missing CODEX_AUDIT_LABEL_TOKEN or GITHUB_TOKEN
WARN  github.actions_cost         private repo has high-frequency metadata workflows
PASS  cloud.token                 optional Code Mower Cloud token file is configured

Summary: warn, 20 checks, 0 failures, 5 warnings
Next: fix token warnings, keep paid lanes manual, then generate a value report.

The warnings are the point: Code Mower should make setup, cost, and trust boundaries visible before you promote any reviewer lane.

See a fuller static transcript: docs/first-run-transcript.md.

After init and doctor, use code-mower lanes status --repo OWNER/REPO to see active builder/reviewer lanes, gate/check state, recent Code Mower workflows, local AgentTrail boards when present, and the next operator action.

See The Value Shape First

If you want to understand the product before installing anything, start with the checked-in demo calibration package:

• examples/demo-calibration/README.md
• examples/demo-calibration/reviewer-value-report.md
• docs/first-user-demo-transcript.md

The example is intentionally tiny and synthetic: one known-clean control, one known-blocked control, and three reviewer lanes. It shows the decision Code Mower is built to support: which AI reviewers are useful, noisy, expensive, fast, or eligible for stronger merge policy on your actual codebase.

Start Here

Choose one path. Each path has one guide and gets to one visible outcome. Cold adopters should start with the reviewer gate, then add builders, then measure builder experiments; provider experiments come after that base loop is observable.

The v0.6 beta announcement entry point is the tagged Try Code Mower In 10 Minutes guide.

What Calibration Does And Does Not Prove

The generated starter corpus proves that the commands run and the report path works. It does not prove that a reviewer should gate merges. Promote reviewer lanes only after repository-specific known-clean and known-blocked evidence meets the lane promotion policy.

To bootstrap a draft from your repository history:

code-mower calibration auto-discover \
  --repo OWNER/REPO \
  --last-n 20 \
  --output .code-mower/draft-calibration-corpus.json

Auto-discovery uses recent merged PR metadata, structured audit trailers, and review-request signals to propose known-clean and known-blocked cases. Review every disposition before using it for lane promotion or merge policy.

Full walkthrough: docs/try-in-10-minutes.md. First-time command map: docs/launch-command-surface.md. Provider-contract baseline for the next release train: docs/v06-truth-baseline.md.

For release verification, First-User Install Rehearsal records the package-index procedure for v0.6.0-beta.1 / code-mower==0.6.0b1. The GitHub release records the workflow and rehearsal evidence for the exact tag.

Optional: Plan Before Coding

For larger changes, use GitHub Issues and local work orders as the planning surface, then keep pull requests focused on code review and merge readiness:

code-mower project-context init --project-name "My Product"
code-mower context add --external ~/Downloads/product-requirements.md
code-mower plan from-github-issue OWNER/REPO#123 \
  --output .code-mower/work-orders/billing-settings-plan.md
code-mower work-order draft \
  --issue-plan .code-mower/work-orders/billing-settings-plan.md \
  --output .code-mower/work-orders/billing-settings.md

The GitHub issue remains the source of truth. The local plan and work order are derived working artifacts, and work-order draft also writes a metadata-only *.cloud-event.json sidecar that can tie later builder/reviewer evidence back to the issue on CodeMower.com. That sidecar excludes source, raw diffs, raw transcripts, stdout/stderr, auth output, secrets, and issue body text. External docs are recorded as metadata manifests unless you explicitly ask for bounded previews. See docs/planning-work-orders.md.

After a PR exists, attach source-free delivery metadata to the same sidecar:

code-mower work-order attach-delivery \
  .code-mower/work-orders/billing-settings.cloud-event.json \
  --pr OWNER/REPO#124 \
  --from-github

If a hosted builder such as Grok Bot or Cursor Cloud Agents produced the PR, record source-free builder provenance too:

code-mower builder record \
  --provider grok_bot \
  --executor cursor_cloud_agent \
  --work-order .code-mower/work-orders/billing-settings.md \
  --pr OWNER/REPO#124

That lets CodeMower.com show issue -> plan -> work order -> builder run -> PR -> reviewer checks -> merge lineage without receiving source, diffs, transcripts, prompts, or issue body text. See docs/builders-grok-cursor.md.

Roles

Code Mower records builder provenance for Claude Code, Codex, Cursor-style hosted builders, and similar authoring lanes, then runs reviewer lanes against the resulting pull requests. The orchestrator is a workflow convention: issue, optional work order, single-writer branch, reviewer lanes, and fix rounds. Code Mower's templates now support that loop end to end; humans still own credentials, branch protection, calibration, and owner decisions.

The reference adoption shape is Claude Code as orchestrator; Claude Code, Codex, and Cursor as builder lanes; Claude Code and Codex as reviewer lanes; and Gitar or Antigravity as informational reviewer signal until local calibration says otherwise.

Why Not Just Run Codex Or Claude Yourself?

You should, at first. Code Mower is not a replacement for a good local agent or reviewer CLI.

Code Mower adds the operating layer around those tools:

• consistent reviewer lanes on real pull requests;
• setup checks for auth, Python, GitHub permissions, private-repo Actions cost, provider CLIs, and cloud-token posture;
• calibration against known-clean and known-blocked PRs instead of vibes;
• evidence-gated lane promotion: informational, selective, or merge-gating;
• spend/latency/usefulness reporting across providers and lenses; and
• privacy boundaries for optional metadata sharing.

The goal is to learn which AI builders and reviewers are worth trusting on your actual codebase, at what cost, and under which merge policy.

Optional Cloud Sharing

Code Mower Cloud currently provides private team dashboards from opt-in metadata. Cross-team cohort benchmarking is a roadmap feature that becomes valuable only as enough teams contribute sanitized data. The local OSS path stays useful without the hosted service.

The cloud value loop is:

1. run local Code Mower reports;
2. inspect the metadata-only bundle or dogfood preview;
3. upload only with --yes; and
4. use CodeMower.com to see repo rollups, provider/lens signal, cost/latency, noisy lanes, next-lane recommendations, and token-safe evidence/detail pages over time.

Start with a dry run:

code-mower cloud dogfood --json

Nothing uploads unless you pass --yes.

Current dogfood uploads, historical catch-up imports, and calibrated reviewer/lens evidence are intentionally separate. Imported GitHub Actions history can prove activity and upload health; it should not be treated as reviewer-quality evidence until it is calibrated against known-clean and known-blocked cases.

To connect to CodeMower.com, sign in at https://codemower.com/login, create or receive a team token, then run:

code-mower cloud setup \
  --token-stdin \
  --team-id "YOUR_TEAM_SLUG" \
  --install-id "your-laptop" \
  --out ~/.config/code-mower/tokens/your-laptop.env

Cloud sharing details, historical catch-up, and repo-sync commands live in docs/cloud-sharing.md.

Provider Posture

The first recommended lanes are local/manual:

Everything else starts manual or informational until your own calibration data proves it is useful: Antigravity/Gemini, Hermes, CodeRabbit CLI, Cursor BugBot, Qodo, Greptile, Devin, local LLMs, and future ACP bridges.

Gemini CLI and Antigravity are distinct lane ids even though both are Google surfaces and may use Gemini model infrastructure. Keep their auth, model provenance, calibration evidence, and release notes separate.

Provider details: docs/provider-matrix.md. Setup/auth fixes: docs/troubleshooting.md.

Road To v1.0

The v1.0 bar is not "every provider works." The v1.0 bar is that a fresh senior engineer can:

1. install Code Mower in a clean repo;
2. understand the local/cloud trust boundary;
3. run init --easy and doctor --preflight;
4. run lanes status --repo OWNER/REPO to see active lanes and gate state;
5. detect and run the repo's native lint/test/build surface instead of assuming every project uses the same tools;
6. produce a local value report from known PR outcomes;
7. decide which lanes should stay informational, selective, or merge-gating; and
8. optionally upload sanitized metadata to CodeMower.com and see useful team dashboard signal.

Build-loop templates extend the same loop from "who reviews best?" to "which AI builder plus reviewer loop ships best on this product?" Start with docs/build-loop-in-30-minutes.md, then use docs/builder-experiments.md and docs/authoring-intelligence.md for deeper measurement work.

Installation Status

The current public beta baseline is v0.6.0-beta.1, with pinned package-index install spec code-mower==0.6.0b1. Release evidence is recorded on the GitHub release and in the first-user install rehearsal. The public repository is codemower-ai/code-mower, and GitHub releases remain the auditable source for tags, build artifacts, and release notes.

For source checkout development and release rehearsal, use:

scripts/dev-python
scripts/dev-python -m venv .venv
.venv/bin/python -m pip install -e ".[test]"

The wrapper resolves Python 3.12+ and refuses stale or old system Python shims. Do not run the CLI by hand-wiring source import paths; install the editable venv first so local work exercises the same package entrypoint users install.

Known Limitations

• PyPI distribution publishing is active through trusted publishing; see docs/pypi-release.md for the release and verification runbook.
• GitHub is the primary supported forge. GitLab, Bitbucket, and ACP bridges are roadmap items.
• Hosted/SaaS reviewers start informational or manual until calibration data supports promotion.
• calibration auto-discover is a bootstrap tool, not an adjudicator. It proposes a draft corpus from PR history; humans still confirm the ground truth.
• CodeMower.com currently provides private team dashboards; cohort benchmarks are roadmap work and should not be treated as live product value yet.
• Self-service cloud data deletion/export basics are live. Retention remains conservative and team-controlled while automated retention jobs are roadmap work.
• Advanced/provider/operator commands remain available behind code-mower --help-all. The default help path stays focused on init, doctor, calibration, value reports, and optional cloud export/upload.

Docs Map

• Try Code Mower In 10 Minutes
• Build Loop In 30 Minutes
• Quickstart Reference
• Planning And Work Orders
• Builder Providers: Grok And Cursor
• Build Loop Operations
• Self-Hosted Mac Runner
• Local Audit Runner
• Lane Standing Instructions
• Codex Lane Standing Instructions
• Claude Lane Standing Instructions
• Cursor Hosted Lane Standing Instructions
• Provider Matrix
• GitHub Setup
• First Run Transcript
• First-User Demo Transcript
• First-User Install Rehearsal
• Launch Command Surface
• v0.6 Truth Baseline
• v0.6 Release Notes
• Demo Calibration Example
• PyPI Release Runbook
• Sample Doctor Output
• Architecture
• Lane Promotion Policy
• Cloud Sharing
• Cloud Data Contract
• Privacy And Threat Model
• Current State And Roadmap
• Public Release Checklist
• Changelog
• Contributing
• Support
• Security Policy
• Code of Conduct

License

The Code Mower open-source core is licensed under Apache-2.0. Hosted benchmarking and reporting, managed integrations, private telemetry and benchmark data products, enterprise controls, and support are commercial surfaces unless licensed otherwise.