Resolve Merge Conflicts With an AI Agent

A conflict in apps/api/src/auth/session.ts at 6:40 PM is rarely a syntax problem. It is usually two valid changes competing for the same ownership boundary: a security fix on one branch, a product requirement on another, and a release branch that cannot wait. To resolve merge conflicts with an AI agent, give it more than the conflict markers. Give it the task intent, branch history, repository rules, and a clear point where human judgment takes over.

AI can remove the mechanical drag from conflict resolution. It can inspect both sides, trace callers, identify generated files, apply a consistent edit, and run the relevant checks. But it should not quietly decide which product behavior wins. The goal is not automatic merging. The goal is a reviewed, testable resolution that preserves the right intent.

What an AI agent should actually resolve

A merge conflict appears when Git cannot reconcile overlapping changes. The visible markers are simple enough:

<<<<<<< HEAD
current branch change
=======
incoming branch change
>>>>>>> feature/checkout-tax

The engineering decision behind them may not be simple at all. One side may rename a parameter while the other adds validation. One may replace an API client while the other adds telemetry around the old client. An agent that selects one block and deletes the other can produce a clean merge and a broken system.

A useful AI agent works at two levels. First, it resolves the textual conflict in the affected files. Then it checks the semantic consequences: types, call sites, tests, configuration, migrations, feature flags, and API contracts. That second level is where the work earns trust.

For example, suppose feature/SC-184-add-sso changes createSession() to accept an identity-provider claim, while hotfix/SC-191-session-expiry adds a stricter expiration policy. The correct resolution is likely neither branch verbatim. The agent needs to retain the claim handling and apply the expiry policy, then run the authentication test suite. If the branches express incompatible behavior, it should stop and ask, not invent a compromise.

Prepare the context before the conflict starts

The best conflict workflow begins before an agent touches a file. Start with a work item that identifies the repository, target branch, acceptance criteria, and linked pull request. A prompt such as “fix the conflict and commit it” is too thin. It gives the agent no basis for deciding whether a change is intentional.

Instead, establish the operational frame. Tell the agent which branch is authoritative, which branch is being merged, and whether the target is a release branch, a long-lived integration branch, or a feature branch. Include the ticket context and any non-negotiable constraints.

For a release conflict, the instructions might be: preserve the payment retry fix from release/2026.08, retain the observability fields introduced in PR #842, do not modify database migrations, and run pnpm test payments plus the TypeScript check. That is an engineering job with verifiable boundaries.

Repository guidance matters too. The agent should read local instructions such as AGENTS.md, CONTRIBUTING.md, package-level READMEs, and CI configuration before making edits. A monorepo may require tests from a specific workspace. A generated API client may need regeneration instead of manual editing. A protected module may require a staff engineer's approval regardless of test status.

This preparation also prevents a common failure mode: resolving a conflict against stale branch state. Fetch the remote, confirm the merge base, and verify that the intended commits are present. An agent can report the commit SHAs it inspected so reviewers know exactly what it reconciled.

Resolve merge conflicts with an AI agent in a controlled workflow

Begin by having the agent inspect rather than edit. It should run git status, identify unmerged paths, and compare each side of the conflict with git diff and git log. Ask for a short resolution plan before it writes files: which behavior each branch introduces, which files are affected, and where the decision is ambiguous.

That plan creates a useful approval point. A developer can quickly confirm, redirect, or narrow the work from a desktop or phone without reconstructing the entire task. If the agent says, “Both branches alter token expiration behavior, and the ticket does not establish precedence,” the right response is a decision from the owner, not another autonomous attempt.

Once approved, let the agent resolve one logical unit at a time. It should preserve formatting, avoid unrelated cleanup, and explain any code that could not be retained exactly. In a three-file conflict involving a service, its test, and a configuration fixture, the agent should update all three as one change. Resolving only the production file may leave an old fixture that masks the regression.

The agent should then show the diff, not merely claim success. Reviewers need to see whether it combined both branches, selected one implementation, or introduced a new adaptation. A concise report is enough:

Resolved: apps/api/src/auth/session.ts
Preserved: SSO claim mapping from PR #842
Preserved: 15-minute idle timeout from hotfix/SC-191
Updated: session.spec.ts and auth fixture
Pending: pnpm test auth, pnpm typecheck

Run the smallest meaningful checks first. A focused unit test, type check, lint command, or targeted integration test gives fast feedback. Follow with the checks required by the repository and pull request. If a full CI run is expensive or queued, the agent should state what ran locally and what remains pending. Proof, not promises.

Only after the diff and checks are visible should the merge resolution be staged and committed. Use a commit message that makes the event legible later, such as Merge release/2026.08: reconcile SSO session expiry. This is not bureaucracy. When a regression appears weeks later, clear history reduces the time needed to understand why two changes were combined.

Know when the agent should stop

Autonomy has a boundary. An AI agent should pause for review when the conflict crosses a product or risk decision that cannot be inferred from code and ticket context. The clearest stop conditions include:

• Both branches change the same business rule, but acceptance criteria do not state which behavior has priority.
• The resolution touches authorization, billing, data deletion, secrets, or a production migration.
• Tests pass only after removing coverage, weakening an assertion, or changing an expected contract.
• The conflict reveals a broader architectural mismatch, such as two competing state-management or API-versioning approaches.

These are not agent failures. They are the moments where accountable engineering judgment matters. A good system preserves the agent's findings, exact diffs, command output, and unresolved question so the next reviewer can decide without replaying the investigation.

Review the resolution as a change, not a merge chore

Treat a conflict resolution pull request like any other production change. Review intent first, then implementation. Confirm that the resulting code satisfies the ticket and that neither side's important behavior disappeared. Read adjacent code where the conflict occurred, especially if the agent changed function signatures, error paths, retries, or serialization.

Check for quiet compatibility breaks. A conflict may compile while changing a default value, dropping a metric attribute, removing a permission check, or altering the order of side effects. Agents are effective at tracing these risks when asked directly: “Find every caller affected by this merged signature,” or “Compare the error behavior before and after the resolution.”

Also review the test delta. New tests are useful when the combined behavior did not exist on either source branch. If branch A added a retry and branch B added a timeout, the merged result needs a test for retry behavior under the new timeout policy. Passing each branch's original tests is evidence, but not complete evidence.

Keep the work moving when the developer leaves the desk

Merge conflicts often block work at the worst time: during a handoff, while CI is running, or after the engineer who owns the context has stepped away. The operational problem is continuity. The conflict, its source branches, agent reasoning, command output, reviewer decision, and final checks need to stay connected.

CodeAgent Mobile is built for that control loop. A ticket can become a context-rich agent session, while the team can inspect the resolution plan, approve a diff, redirect the agent, monitor checks, and resume the same work from another device. Nothing needs to be re-explained when ownership shifts from a laptop to a phone or from one engineer to another.

The fastest merge is not the one that removes conflict markers first. It is the one that preserves intent, leaves an auditable diff, passes the right checks, and gives a human a clear decision when the code alone cannot answer the question.