Skip to main content

/kosuke:sync-branch

/kosuke:sync-branch brings your branch up to date with the project's Target Branch. The agent merges, resolves conflicts by what each side meant, proves the merge with the cheapest check that covers it, and pushes. Then it brings the app back up, when the merge needs it. It asks you only when the code cannot settle a conflict, for example when both sides changed the same thing for the same reason, or when their dependency changes are incompatible. The Sync button runs this skill when GitHub cannot merge the branch cleanly on its own, for example on a conflict, uncommitted or unpushed work, or a running turn. Sync with the Target Branch covers when the button appears.

When to use it​

Run it when the branch is behind its Target Branch or its pull request has conflicts. You can also run it before a review, so reviewers see the change against the latest code.

Run it​

Type /kosuke:sync-branch, or $kosuke:sync-branch in a Codex session.

ArgumentWhat it doesDefault
--target-branch <branch>Overrides the branch to sync with. The button passes a non-default project Target Branch only before a pull request opens.The open pull request's base, then the project's Target Branch, then GitHub's default branch.
/kosuke:sync-branch
/kosuke:sync-branch --target-branch release/2.4
/kosuke:sync-branch rebase instead of merging

What it does​

  1. It checks whether the branch is behind. When it already has everything, the agent says so and stops, and your work stays as it was.
  2. It preserves your uncommitted work before merging. It commits work that belongs to the change, or stashes it and restores it at the end.
  3. It merges the Target Branch in. A merge with no conflict is committed at once, and a fix the merge needs goes into that same commit. It rebases only when you ask, or when the branch was never pushed and has no pull request.
  4. It resolves each conflict by reading what each side changed and why. When both sides changed the same thing for the same reason, it collects every such conflict into one Clarification. For each one you keep this branch's version, take the Target Branch's, or describe another resolution.
  5. It keeps both sides' migrations and dependency changes. It never edits, renames, renumbers or deletes a migration, on either side. With a tool that keeps one folder or file per migration, named by timestamp, such as Drizzle 1.0's <timestamp>_<name>/ folders, both sides' migrations never conflict in git; a real conflict is only in the schema source. Your branch's migration stays exactly as it was. When the tool needs it regenerated against the merged schema, the agent deletes only your branch's own migration and runs the project's generate script, and never touches a migration the Target Branch has. After the merge it runs the tool's check, such as drizzle-kit check. When both sides change the same table, column or index, or both sides conflict in a migration journal the tool shares, it stops and asks you how to go on instead of resolving it. It never gets past the check with drizzle-kit generate --ignore-conflicts, which can diff from the wrong base (drizzle-orm #6216), or --custom, whose merge snapshot can drop tables (drizzle-orm #6310). It regenerates the lockfile with the project's own package manager, and asks you when the dependency changes are incompatible.
  6. It runs the cheapest check that proves the merge, such as a type check or tests of resolved code. It uses the project's own environment and fixes what the merge broke. Every fix goes into the same merge commit. The agent reads a passing result for that commit's final contents before starting the push, even after a clean merge. A commit hook running that check counts, so the agent does not repeat it. CI runs the full test suite, the build and lint on the push.
  7. It pushes once. Then it re-runs setup or restarts services only when changed inputs need it, even if the commands stay the same. A service restarts when it loads changed dependencies, environment, configuration or migrations only at startup. Hot-reloading services keep running for changes they reload. After a restart, the agent waits until the services are ready. If no service applies the merged migrations, the agent applies them with the project's command.

Some merged code needs an environment variable or a service added to the project settings after the session started. The agent tells you when that happens, because it takes a new chat session.

What you get​

  • After a merge, a merge commit named chore: sync with <target>, or chore: sync with <target> (resolved N conflicts). A rebase makes no merge commit.
  • The merge is pushed and the branch is no longer behind.
  • A reply that lists what came in and how each conflict was resolved. It also covers the migrations and dependencies, the checks it ran and the state of the app.

Limits​

  • It never takes one side of a conflict wholesale or deletes work to make a conflict go away.
  • It never discards your uncommitted changes.
  • It never force-pushes a branch with an open pull request unless you ask for exactly that.
  • It never edits, renames or renumbers a migration, on either side, and regenerates only your branch's own migration, only when the tool needs it.
  • It adds nothing to the Testing Checklist: the merged work brings its own items, and QA scopes a sync from git.

Next steps​