BranchMesh: When Git Merges Cleanly but the Code Breaks

BranchMesh detects hidden behavioral conflicts between independently passing Git branches by testing branch pairs in isolated worktrees - before integration breaks your build.

Comment

Inspiration

Modern development teams often work on several feature branches at the same time. Each branch may pass its own tests, and Git may merge their files without a traditional conflict, but the combined changes can still break the application because the branches made incompatible assumptions.

That gap inspired BranchMesh.

Git is excellent at answering: “Can these file changes be merged?” BranchMesh adds a second question: “After they are merged, does the combined software still work?”

I wanted the answer to come from real project commands, not an AI prediction. I also wanted the tool to work locally, avoid uploading repository content, and never modify the developer’s current worktree.

What BranchMesh does

BranchMesh is a local-first TypeScript CLI and Codex skill that tests committed Git branches individually and in pairwise combinations.

During a scan, BranchMesh:

  1. Inspects the repository and validates the selected base.
  2. Captures every selected branch tip as an exact commit ID.
  3. Creates BranchMesh-owned, isolated temporary Git worktrees.
  4. Validates the base and each branch individually.
  5. Generates every unique branch pair—up to five selected branches by default.
  6. Combines each pair in a deterministic order and runs configured commands such as tests, builds, linting, or type-checking.
  7. Classifies the observed result.
  8. Produces validated JSON, separate raw logs, and a completely offline HTML compatibility report.
  9. Removes its temporary worktrees while leaving the original repository unchanged.

The primary pair outcomes are:

  • Textual Git conflict: Git cannot combine the commits automatically.
  • Behavioral conflict: Git merges cleanly and both branches pass alone, but a configured command fails after they are combined.
  • No detected conflict: Git merges the pair and all configured commands pass.

“No detected conflict” is deliberately narrower than “safe.” BranchMesh reports only what was observed through the configured checks and environment.

The demonstration

The included demo creates three branches:

  • feature/config-seconds changes a retry configuration from milliseconds to seconds.
  • feature/jitter adds one hundred milliseconds of jitter using the original milliseconds field.
  • feature/status-output adds an independent status function.

All three branches pass individually. Git can also combine every pair without a textual conflict.

However, config-seconds and jitter disagree about the retry configuration. After they are combined, the field expected by the jitter branch no longer exists. JavaScript evaluates the missing value plus one hundred as NaN, while the test expects 1100.

BranchMesh reports:

BEHAVIORAL_CONFLICT
PAIR_TEST_FAILURE
NaN !== 1100
Conflicted files: 0

The other two pairs pass. The result proves the core use case: a clean Git merge can still produce broken behavior.

How I built it

BranchMesh is a single Node.js and TypeScript package. The CLI uses Commander, configuration and result contracts use Zod, terminal presentation uses Picocolors, builds use tsup, and automated testing uses Vitest.

Git and validation commands are executed with argument arrays rather than untrusted shell command strings. Branch tips are snapshotted before execution, dirty selected worktrees are rejected by default, and every scan runs inside detached temporary worktrees owned by BranchMesh.

The report uses plain HTML, CSS, and JavaScript. It contains no frontend framework, external assets, analytics, or runtime network requests. The matrix and status indicators include text labels so the result does not depend only on color.

The CLI includes:

branchmesh init
branchmesh doctor
branchmesh scan
branchmesh demo
branchmesh clean
branchmesh version

The repository also includes a reusable Codex skill that can run the deterministic scanner and explain its JSON evidence.

How I used Codex

BranchMesh was developed primarily through one Codex session during OpenAI Build Week. I defined the product scope, architecture boundaries, Git-safety rules, acceptance criteria, and final decisions. Codex handled most of the implementation, tests, debugging, documentation, offline report, demo generator, and release verification.

I developed the project milestone by milestone instead of asking Codex to generate the entire application at once. Repository-level instructions in AGENTS.md prevented scope expansion and enforced the most important rule: never modify the user’s current worktree.

Codex is the development environment used to build BranchMesh. BranchMesh itself makes no model calls or external API calls at runtime. Its conclusions come only from Git operations and the project commands configured by the user.

Challenges I faced

Making Git operations genuinely safe

The most important challenge was ensuring that checkout, merge, cleanup, and cancellation could never affect the developer’s active worktree. Temporary paths must be owned and verified before removal, and cleanup must run after success, failure, timeout, or interruption.

Distinguishing product results from execution failures

A detected incompatibility is a successful BranchMesh scan with an unsuccessful compatibility result. The CLI intentionally returns exit code 1 when it finds a conflict. This needed clear classifications and documentation so users do not mistake a valuable detection for a tool crash.

Reliable command termination

Timeout and cancellation handling must terminate process trees, preserve useful evidence, and still clean up every temporary worktree. These paths required adversarial tests rather than only happy-path unit tests.

Communicating evidence responsibly

BranchMesh cannot guarantee general safety. It can only say that no conflict was detected through the configured commands. That limitation shaped the CLI language, schemas, HTML report, and documentation.

What I learned

I learned that repository safety and cleanup are not supporting details for a Git tool—they are core product functionality. I also learned that immutable inputs, structured evidence, and carefully limited claims make automated results much more trustworthy.

Working with Codex was most effective when I supplied strict repository instructions, small milestones, measurable acceptance commands, and mandatory regression tests. The current release candidate passes the complete verification pipeline, including 142 automated tests across 35 test files, the production build, the real demo, offline report validation, and skill verification.

What’s next

The current release has been manually tested on macOS. Next steps include additional Linux and WSL verification, more adversarial cancellation testing across platforms, performance improvements for larger repositories, and optional CI workflows that preserve the same deterministic local engine.

Native Windows execution is not currently claimed as supported. Pairwise testing also remains intentionally bounded; BranchMesh does not claim to test every possible multi-branch combination or every possible defect.

Run the demo

npm ci
npm run build
node dist/cli.js demo --open

The demo is expected to exit with code 1 because it intentionally detects one behavioral conflict. The HTML report opens locally, and all BranchMesh temporary worktrees are removed after the scan.

Built With

Share this project:

Updates