Code Mower

Code Mower adds a supervised operating layer around AI coding agents. It helps teams give one builder ownership of a change, obtain independent reviews on the current pull-request head, recover stalled work, and measure which builder and reviewer combinations are useful on their own codebase.

The current release is supervised-pilot, bring-your-own-agent-loop software. It is not a drop-in unattended merge gate. Humans still own credentials, repository policy, reviewer promotion, and exceptional decisions.

The current source candidate is v1.4.2, with target install spec code-mower==1.4.2. Publication and installed-package qualification are pending #952. The published v1.4.0 and v1.4.1 artifacts remain unchanged. Install commands below target v1.4.2 after publication; candidate rehearsals use the exact verified artifact.

Documentation on main follows the source on main. After v1.4.2 publication, start with the v1.4.2 guide.

What Code Mower Adds

You can run Claude Code, Codex, Devin, or another coding agent directly. Code Mower supplies the shared workflow around them:

• one orchestrator and one writer per branch;
• provider-neutral work orders, handoffs, status, and recovery;
• independent, structured reviews bound to the current PR head;
• repository-specific calibration before a reviewer gains merge authority;
• local reports for quality, latency, cost, interventions, and outcomes;
• setup diagnostics for provider auth, GitHub permissions, and private-repo Actions cost; and
• optional, explicitly authorized organizational context and metadata sharing.

The default setup is deliberately small: Claude Code and Codex. Additional participants are opt-in and keep their own execution, privacy, cost, and promotion requirements.

Start Here

Code Mower requires Python 3.12 or newer. A laptop or workstation should use one stable pipx installation:

python3.12 --version
export CODE_MOWER_PYTHON="$(command -v python3.12)"
pipx install --python "$CODE_MOWER_PYTHON" code-mower==1.4.2
command -v code-mower
code-mower --version

Hosted agents and CI machines can use uv tool install; contributors should use scripts/dev-python and an editable virtual environment. The Install And Bootstrap guide gives the exact cold-install, upgrade, optional Coworker, and contributor commands.

From the repository you want to pilot:

code-mower init --easy
code-mower init --easy --apply --output-dir .code-mower.generated
code-mower doctor --adoption --repo OWNER/REPO
code-mower lanes status --repo OWNER/REPO

init --easy previews the Claude + Codex setup and changes nothing. --apply writes a reviewable generated tree; it does not copy those files into your repository, start a provider, enable auto-merge, or upload data. Review and edit the generated configuration before opening the setup PR.

To inspect representative output first, use the synthetic calibration example and Board demo.

Follow Try Code Mower In 10 Minutes to run Codex and Claude manually against that first PR. Automation tokens, recurring dispatch, branch-protection changes, and auto-merge are not prerequisites for the manual reviewer-gate pilot.

After the first peer-review loop works, follow Build Loop In 30 Minutes to add automated builder dispatch and the stricter promoted-pilot repository settings.

Participants And Sessions

Choose participants interactively or explicitly:

code-mower init --interactive
code-mower init --with claude,codex,devin

Both commands preview by default. Add --apply only when you are ready to write the generated setup.

The agent that starts a session is the implicit orchestrator:

code-mower session start \
  --repo OWNER/REPO \
  --with claude,codex,devin \
  --host codex

session start saves an operating brief and takes the local single-orchestrator lease. It does not launch every selected product. The host uses the execution paths available for each participant and records explicit handoffs where Code Mower has no automatic transport. Later, from anywhere in the checkout, code-mower session show --current finds the brief the live lease names and code-mower session lease show reports the lease itself; neither changes state. The default is 12 hours. A later process can renew or release the same session ID with session lease renew --session-id SESSION_ID or session lease release --session-id SESSION_ID; stop its writers before release. Use session start --dry-run or --no-lease for read-only work.

Codex, Claude Code, and Cursor are qualified for the shared session, telemetry, lease, and Jira-authority contract in v1.4.2. Devin, Grok Bot, Antigravity, Muse, and custom hosts are recognized for briefs and provenance, while their execution remains an explicit handoff or provider-specific transport. See Participants And Sessions and the Provider Matrix.

Optional Organizational Context

The base installation works without an organizational-memory provider. The optional Coworker integration gives approved Claude, Codex, and Devin roles the same bounded, cited evidence through an explicitly selected private account. Account identity and credentials stay outside the repository.

After installing the optional dependencies and connecting an approved account, the guided path carries one work item through retrieval, builder delivery, current-head attachment, independent review, and private feedback:

code-mower session start --repo OWNER/REPO --host codex --work-item EXAMPLE-123
code-mower session context prepare .code-mower/sessions/SESSION.json
code-mower session context deliver .code-mower/sessions/SESSION.json
code-mower session context attach .code-mower/sessions/SESSION.json --pr 42
code-mower session context feedback .code-mower/sessions/SESSION.json \
  --reviewer claude

Every delivery and feedback read reauthorizes online. Private evidence and private review findings must not be copied into tracked files or public logs. Start with Optional Organizational Context Setup.

Roles

• Orchestrator: the hosting agent by default; coordinates the work item, assignments, evidence, reviews, recovery, and owner actions.
• Builder: the only writer for its PR branch.
• Reviewer: an independent current-head audit. A builder's own review does not satisfy the peer-review requirement.
• Merge authority: repository policy. Selecting a participant never grants it.
• Context provider: supplies approved evidence; it cannot build, review, orchestrate, write to the tracker, or merge.

Code Mower records builder provenance for Claude Code, Codex, Cursor-style hosted builders, Devin, and other authoring lanes. Its generated templates now support the supervised issue-to-merge loop end to end, with provider-specific adapters handling product differences.

What Calibration Does And Does Not Prove

The generated starter corpus proves that the command and report paths work. It does not prove that a reviewer should gate merges.

Bootstrap a draft from recent repository history:

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

Review every proposed disposition. Promote a lane only after known-clean and known-blocked evidence satisfies the lane promotion policy.

Local Status And Board

lanes status is the concise terminal view. The optional Board serves the same redacted metadata on loopback:

code-mower lanes status --repo OWNER/REPO
code-mower productivity report --repo OWNER/REPO
code-mower board serve --repo OWNER/REPO

Plain board serve is read-only. Add --record-events to append throttled, metadata-only local history:

code-mower board serve --repo OWNER/REPO --record-events
code-mower board record --repo OWNER/REPO
code-mower board events
code-mower board doctor --repo OWNER/REPO
code-mower board reset --repo OWNER/REPO --yes

The Board includes the owner queue, reviewer verdict history and spend/latency when those local inputs exist. Local paths are redacted by default. The Board does not upload data.

Optional Cloud Sharing

The OSS package works without CodeMower.com. Cloud sharing is an explicit, dry-run-first path for sanitized metadata and selected reports:

code-mower cloud dogfood --json
code-mower cloud board-snapshot --repo-slug OWNER/REPO --json

Neither command uploads without --yes. Default bundles exclude source code, raw diffs, model transcripts, raw stdout/stderr, auth output, issue body text, local secret values, and secrets. See Cloud Sharing and the Cloud Data Contract.

Current Capabilities And Limits

GitLab, Bitbucket, broad unattended rollout, uncalibrated merge gates, Devin peer-orchestrator/reviewer parity, a hosted work-order CLI, a required Graphify dependency, and Slack worker delivery are outside the v1.4.2 candidate. The current priorities and boundaries are recorded in Current State And Roadmap.

Documentation

Install And First Use

• Install And Bootstrap
• Try Code Mower In 10 Minutes
• Upgrade An Existing Repository
• Quickstart Reference
• Troubleshooting
• First Run Transcript (v1.4.0 illustrative shape, not the current v1.4.2 pin)

Sessions, Builders, And Reviewers

• Participants And Sessions
• Build Loop In 30 Minutes
• Build Loop Operations
• Planning And Work Orders
• Builder Experiments
• Orchestrator Prompt Pack
• Provider Matrix
• Provider Calibration Scorecard
• Devin Peer-Support Qualification
• Lane Standing Instructions
• Codex Lane
• Claude Lane
• Cursor Lane
• Devin Lane
• Self-Hosted Mac Runner
• Local Audit Runner

Context And Trackers

• Optional Organizational Context Setup
• Coworker Connections
• Context Delivery And Private Review
• Context Provider Contract
• Context Packet Schema
• Jira Cloud Setup
• Jira Adoption Rehearsal
• Work Tracker Data Contract

Trust, Operations, And Project Records

• Architecture
• Current State And Roadmap
• Lane Promotion Policy
• Privacy And Threat Model
• Board Data Contract
• Cloud Data Contract
• Release Qualification
• Public Release Checklist
• v1.4.2 Release Notes
• Release History And Archived Plans
• Changelog
• Contributing
• Support
• Security Policy
• Code of Conduct

License

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