Last reviewed: 2026-06-08

Direct answer

A coding agent session produces a reviewable diff when every change the agent makes is isolated to a dedicated branch or git worktree, committed in small logical units, and surfaced through a pull request before anything merges into the main branch. The key constraints are:

• The agent works only on its own branch or worktree — never directly on main or a shared branch.
• Each agent session ends with a commit (or a series of commits) that can be inspected line by line in a PR diff view.
• CI runs automatically on the PR so a human reviewer sees test results alongside the diff.
• The reviewer approves or requests changes before merge; the agent does not self-merge.

When these constraints hold, the human reviewer always has a clean, attributable record of what the agent changed, why (from the commit message and PR description), and whether the tests passed.

For broader release checks, see AI Coding Agent Setup, Security, and Model Routing .

Who this is for

This guide is for engineers and team leads who:

• Run coding agents (such as Codex, Claude Code, or similar CLI-based tools) on real codebases and need the output to pass human code review.
• Want to ensure agent-generated changes are auditable and can be rolled back cleanly.
• Are setting up or refining a workflow where agents open PRs rather than pushing directly to protected branches.
• Work in teams where reviewers need to understand what an agent changed without reading a wall of uncommitted edits.

If you are already familiar with git branching and PRs but are new to agents, this guide focuses on the agent-specific wrinkles — session boundaries, branch hygiene, worktree isolation, and PR description quality.

Key takeaways

• One session, one branch. Each agent session should begin on a fresh branch cut from the integration target. Shared branches between sessions accumulate noise that makes diffs unreadable.
• Worktrees prevent accidental cross-contamination. Using git worktree add gives each concurrent agent its own working directory without requiring separate clones.
• Commit frequently, with context. Small commits with clear messages make the PR diff navigable. A single giant commit at the end of a session is hard to review.
• Require CI on the PR branch. Reviewers should see test status before they read the diff, not after. Configure branch protection rules so CI runs on every push to the PR branch.
• The PR description is the handoff note. Agents should write a PR description that summarises what changed, why, and what the reviewer should focus on. Without this, human review time increases significantly.
• Protect main from direct agent pushes. Branch protection rules that require PR review are the simplest enforcement mechanism; the agent physically cannot bypass them.

Branch strategy for agent sessions

Starting a session cleanly

Before starting an agent session, create a branch from the current integration target:

git checkout main
git pull --ff-only
git checkout -b agent/session-<descriptor>-<date>

The branch name should identify the agent, the task scope, and the date so that a reviewer scanning the PR list can immediately understand what each branch represents.

Never start an agent session on main, develop, or any branch that other people or agents are actively using. If two sessions land on the same branch, their diffs will be entangled and neither will be individually reviewable.

Committing during the session

Encourage or instruct the agent to commit after each self-contained change rather than accumulating all edits until the end. A useful commit discipline:

• feat: for new functionality added
• fix: for corrections to existing behaviour
• test: for test-only changes
• refactor: for restructuring without behavioural change
• chore: for tooling, config, or dependency updates

Commit messages should include the task or issue reference if one exists. A reviewer skimming the commit list should be able to understand the sequence of changes without opening each diff individually.

Opening the PR

When the session is complete, push the branch and open a PR. The PR description should include:

1. A one-sentence summary of what was changed.
2. The motivation or task reference that prompted the change.
3. A brief description of the approach taken.
4. Any areas the reviewer should pay particular attention to.
5. Test coverage notes — which tests were added or modified, and what they verify.

If the agent was given a task brief, the brief ID or a link to it belongs in the PR description. This creates a traceable chain from task to change.

For more on writing task briefs that produce well-scoped agent changes, see Write Coding Agent Task Briefs That Produce Reviewable Changes.

Git worktree isolation for concurrent sessions

When multiple agent sessions run concurrently — for example, one agent working on a feature while another fixes a bug — git worktrees provide clean isolation without the overhead of separate full clones.

The git worktree add command creates an additional working directory linked to the same repository object store:

# Add a worktree for an agent session on a new branch
git worktree add ../worktree-agent-fix-auth agent/fix-auth-$(date +%Y%m%d)

Add a worktree for a second concurrent session

git worktree add ../worktree-agent-add-cache agent/add-cache-$(date +%Y%m%d)

Each worktree directory has its own index and HEAD, so agent A editing files in ../worktree-agent-fix-auth cannot accidentally stage or commit files that agent B is editing in ../worktree-agent-add-cache.

The git-scm documentation describes the full worktree command reference, including how to list, lock, move, and remove worktrees. Verify the current command options in the linked source before scripting worktree management into automation.

When a session ends and the PR is merged, remove the worktree to keep the workspace clean:

git worktree remove ../worktree-agent-fix-auth
git branch -d agent/fix-auth-20260608

For a deeper look at isolation rules when multiple agents are running in parallel, see Use Git Worktrees to Keep Parallel Coding Agents Isolated.

CI checks on agent PR branches

A reviewable diff is only useful if the reviewer can quickly determine whether the agent’s changes actually work. Requiring CI to pass before a PR can be reviewed shifts the signal from “the agent says it works” to “the test suite confirms it works.”

On GitHub, the typical enforcement path is:

1. Configure a GitHub Actions workflow that runs on pull_request events targeting the integration branch.
2. Add a branch protection rule requiring that workflow’s status check to pass before merging.
3. Optionally require at least one human review approval in addition to passing CI.

Verify the current GitHub Actions workflow syntax and branch protection configuration options in the GitHub Actions documentation and GitHub pull requests documentation linked in the sources section below. Workflow syntax evolves; do not rely on examples that are more than a few months old.

What CI should check on agent PRs

At minimum, the CI workflow for an agent PR branch should:

• Run the existing test suite.
• Run any linting or static analysis tools configured for the repo.
• Report a clear pass or fail status that GitHub can consume as a required check.

CI should not assert things the agent cannot guarantee, such as specific timing or external service availability. Flaky CI that fails for environmental reasons undermines the review signal.

Limiting what CI can access

Agent-opened PRs should run with the same secret access restrictions as any other contributor PR. On GitHub Actions, the pull_request event from a fork or from a branch opened by an automated actor runs with read-only permissions by default. Verify the current GitHub Actions permission model in the documentation before granting elevated permissions to workflows triggered by agent PRs.

Keeping AGENTS.md current

Many coding agents read a repository instruction file — often named AGENTS.md, .claude/instructions.md, or a similar path — before starting a session. This file is where you encode the branch and PR conventions described in this guide so that agents follow them automatically without requiring per-session instructions.

The OpenAI Codex AGENTS.md documentation describes how instruction files influence agent behaviour and what fields are typically supported. The exact instruction format and supported directives vary between agent tools, so verify the current behaviour for your specific agent against its documentation before relying on any particular instruction syntax.

A minimal AGENTS.md entry for reviewable diff conventions might specify:

• Always create a new branch before making any changes.
• Never push directly to main or any branch named in a protected list.
• Open a PR with a description that includes the task reference, approach, and reviewer focus areas.
• Commit in logical units with conventional commit prefixes.

For a full discussion of what to include in repository instruction files, see How to Write Repository Instructions for Coding Agents.

Smoke-test workflow

Before declaring an agent PR ready for human review, run a quick check to confirm the diff is clean and the branch is in the expected state.

Setup assumptions:

• You have a local clone of the repository.
• The agent has finished its session and pushed the branch.
• CI is running or has completed on the PR.

Happy-path check:

1. Fetch the remote branch: git fetch origin agent/session--
2. Check out the branch: git checkout agent/session--
3. Review the diff against the integration base: git diff main…HEAD
4. Confirm no unintended files appear in the diff (e.g., secrets, build artifacts, IDE config).
5. Confirm the commit log is readable: git log –oneline main..HEAD
6. Confirm CI status is green on the PR.

Error-path check:

• If the diff contains files that should not be tracked (secrets, .env, large binaries), verify .gitignore is correctly configured and ask the agent to amend or drop the offending commits.
• If CI is failing, read the failure output before asking the agent to retry. Blind retries without understanding the failure often produce larger, messier diffs.

Minimum assertions for a reviewable diff:

• The diff is scoped to the stated task — no unrelated file changes.
• Each commit message describes the change it contains.
• CI passes on the branch.
• The PR description exists and is not empty.

What the smoke test must not assert:

• That the diff is perfect or complete — that is the human reviewer’s role.
• That CI timing or external integrations behaved deterministically across runs.
• That the agent’s approach was the only valid one.

Sanitized log record template

After running the smoke test, record the outcome. Use placeholder values only:

date: YYYY-MM-DD branch: agent/session-- base: main (or integration branch name) commit_count: N diff_files_changed: N ci_status: pass | fail | pending unintended_files: none | list pr_description_present: yes | no reviewer_assigned: yes | no notes:

Do not record real credentials, full diff contents, or model-specific claims in this log.

Failure modes

• Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
• Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
• Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
• Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
• Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.

Sources checked

• GitHub pull requests documentation - accessed 2026-06-08; purpose: verify pull request review and collaboration boundaries.
• Git worktree documentation - accessed 2026-06-08; purpose: verify parallel worktree isolation commands and constraints.
• OpenAI Codex AGENTS.md guidance - accessed 2026-06-08; purpose: verify repository instruction-file context for coding agents.
• GitHub Actions documentation - accessed 2026-06-08; purpose: verify workflow runs, jobs, steps, checks, and logs.

Contract details to verify

Reader next step

Compare the workflow against Start with CometAPI .

Use AI Coding Agent Setup, Security, and Model Routing as the next comparison point. Keep Triage CI Failures With a Coding Agent Without Losing the Evidence nearby for setup and permission checks.

FAQ

Why does one branch per session matter if the agent’s changes are small? Even small changes become hard to attribute when multiple sessions share a branch. A single-branch-per-session rule keeps each PR diff scoped to one task and one reviewer focus area, regardless of change size.

Can the agent open the PR itself, or should a human do it? Most coding agent tools can open a PR via the GitHub CLI or API after pushing the branch. Whether you allow this depends on your trust model. The important constraint is that the agent should never self-approve or self-merge the PR; human review must remain in the loop.

What if the agent makes a mistake in the commit history? Before the PR is merged, the agent (or a human) can amend commits or rebase the branch to clean up the history. After merge, fixes should go through a new PR rather than rewriting shared history.

Do I need worktrees if agents run sequentially, not concurrently? Sequential agents on separate branches do not need worktrees — a standard checkout per session is sufficient. Worktrees become valuable when you want two or more agent sessions to run simultaneously without one overwriting the other’s working directory.

How do I know if CI is actually checking agent-generated code, not just cached results? Most CI systems invalidate the cache when the branch changes. To be certain, check the CI run timestamp against the push timestamp on the branch. If the run predates the most recent push, it may be stale.

What should I do if the agent pushes to a protected branch directly? GitHub branch protection rules prevent direct pushes from any actor, including automated tokens, when the rule is correctly configured. If a direct push succeeds, the protection rule is either misconfigured or the token being used has bypass permissions. Audit the branch protection settings and the token’s repository permissions.

Ready to route agent model calls through a unified gateway? Start with CometAPI