Sync with the Target Branch
When the Target Branch moves ahead of a session's branch, the chat header shows Branch behind. A pull request that cannot merge cleanly shows PR has conflicts. Press Sync beside either label. GitHub handles a clean merge, then refreshes the sandbox, while the agent handles conflicts and proves its merge with the cheapest appropriate check.
When to sync
The label sits in the status row at the top of the chat, next to the branch name. It appears on Active and Under Review sessions.
| Label | Color | Means |
|---|---|---|
| Branch behind | Yellow | The Target Branch has commits this branch does not have yet. |
| PR has conflicts | Red | The pull request no longer merges cleanly into the Target Branch. |
Once a session has a pull request, a branch that is behind also needs its Assignee. With Sensei, it shows in Needs you on the Sensei page. See Overview, Needs you and Activity.
Run Sync
- Press Sync in the status row. In a narrow chat panel the label shrinks to a dot, and Sync stays beside it.
- The control reads Syncing… during the merge and refresh. Sync pending means GitHub accepted the sync and completion is still running. When completion finishes, the label clears. Nothing is posted in the chat.
- If completion fails, read the failure and use its recovery action below.
- If the agent takes over, answer it if it asks about a conflict, and read its reply.
GitHub merges when the branches have no conflict, the sandbox has no uncommitted or unpushed work, and the agent is idle. Otherwise the agent takes over, including when the session is Ready or GitHub refuses the merge. After GitHub accepts a merge, completion stays with the refresh, even when it is delayed or fails.
An Under Review session stays Under Review while the agent syncs it, and its pull request stays ready for review. When /kosuke:ship carries on after the sync, a merge with no change of its own keeps the review and QA results of the commit before it. Any other merge gets review and QA for what it changed.
If the agent is working when you press Sync, the request waits Up next and runs after the current turn, as an agent sync. Your unsent message and its attached or selected context stay in the composer.
Sync brings in the Target Branch, the branch set in Open PRs against in the project settings. When that setting is empty, it is the repository's default branch. Once the session has an open pull request, Sync brings in the branch that pull request merges into, and Branch behind compares against that branch. They differ only for a pull request that targets another branch, such as one stacked on another session's branch or retargeted on GitHub.
Recover a failed sync
Retry refresh retries a temporary refresh failure. It requests no new GitHub merge.
Check GitHub observes a merge GitHub has accepted but has not confirmed yet. The sandbox refresh starts only after confirmation. This action never starts an agent Turn.
Ask agent to repair is offered when a confirmed merge cannot refresh because of local work, a different checkout branch, or failed setup or services. Press it to ask the agent to preserve local work and repair the checkout and environment. The action keeps your draft and attached context. It does not request another GitHub merge.
If the session branch or pull request changed, the header shows Sync context changed. The old operation offers no repair action for that new context.
A refresh waits while a Turn or another update owns the sandbox. If it stays busy for a day, completion reports a failure and offers Retry refresh.
Answer a conflict question
The agent settles most conflicts on its own by combining what each side meant. It asks you only when both sides changed the same thing for the same purpose, such as the same title text changed two ways.
It collects all such conflicts into one question. For each, it names the file and shows both versions. It offers to keep this branch's version, take the Target Branch's version, or use a resolution you describe. Answer in the chat and the agent finishes the sync. Messages, Up next and steering explains how answering works.
What you get
When GitHub merges:
- A merge commit on the session's branch, made on GitHub as you when you connected GitHub, and as Kosuke App otherwise. Without a pull request it reads "chore: sync with main"; with one, GitHub writes its own Update branch message.
- The sandbox wakes if paused and moves forward to the merged branch when local work permits it. A changed checkout runs the configured setup and restarts services. An unchanged checkout needs neither. Local work that prevents the refresh stays intact and produces a refresh failure.
- The label clears after completion. A delayed merge or refresh stays Sync pending until it finishes or reports a failure.
- No check of the merged code. The pull request's checks run on GitHub, and failing checks show on the session as usual.
When the agent syncs:
- A merge commit on the session's branch, such as "chore: sync with main".
- The cheapest check that proves the merge. CI runs the full suite, build and lint after the push.
- The agent pushes the branch and the label clears.
- The app up to date with the merged code. The agent re-runs setup or restarts the services only when what came in needs it, after the push.
- A reply that lists what came in from the Target Branch and how each conflict was resolved. It also names the migrations and dependencies it reconciled, the checks it ran and the state of the app.
A sync voids no approval by itself. Sensei counts an approval as the repository's rules count it, so a pull request loses one after a sync only when the repository dismisses stale reviews.
If the merged code needs an environment variable or a service that the project settings gained after this session started, the agent says so. Start a new session to get it.
The steps the agent follows are on /kosuke:sync-branch. You can also run that skill yourself by typing /kosuke:sync-branch in the chat, or $kosuke:sync-branch in a Codex session.