Use a fork to try another approach while keeping the original conversation. Use a merge when you want to bring useful decisions or work back together. These operations affect AgentGit conversation history; they do not merge the branches in your project’s code Git repository.
Before starting, save the current session and inspect its
history. Examples use alice/my-project@first-task and
illustrative turn numbers; replace them with refs from your own log.
Choose resume, new, or fork
| You want to… | Command |
|---|---|
| Continue the same conversation | agit resume alice/my-project@first-task |
| Start an empty conversation with the repository’s shared files | agit new alice/my-project -b next-task --as codex |
| Try another approach from a saved turn | agit fork alice/my-project@first-task#4 -b alternative --resume |
The new-conversation example uses Codex; replace codex with any
launchable runtime identifier,
including openclaw, hermes, or workbuddy, to choose your installed runtime explicitly.
resume continues an existing, unsealed session branch head. For a tag or
an older turn, use fork. A fork creates a new session identity and inherits
the saved context. Omit --resume if you want to create the branch without
launching it yet. A point on the shared main file line has no conversation
to fork; use new there.
You can ask your agent:
Use AgentGit to fork the session from the turn before we chose the cache design. Keep the original session and try the alternative on a new branch.
Merge with an agent
After working on the alternative and saving its turns, start reconciliation:
agit merge alice/my-project@alternative --into alice/my-project@first-task
AgentGit launches a merge agent to read both sides, select source turns,
reconcile shared files, and write a summary. You can add an instruction with
-m "Keep the retry strategy and explain which approach to use".
The summary matters because both conversations may contain individually reasonable but incompatible decisions. The merge agent resolves those choices so the resumed session receives the selected context and its conclusion.
Inspect or drive a merge manually
Use --dry-run to inspect the fork point and changes without starting a
transaction. Use --manual when you want to select context yourself:
agit merge alice/my-project@alternative --into alice/my-project@first-task --manual
agit merge --into alice/my-project@first-task --status
Read the source with agit log, agit show, or agit view before picking.
For example, if you want turns 5 and 6 plus one event from turn 7:
agit merge --into alice/my-project@first-task pick alternative#5..#6 alternative#7.2
To undo that event selection, remove the exact reference you picked:
agit merge --into alice/my-project@first-task drop alternative#7.2
drop removes entries from the pick list. To change a selected range,
drop that range and pick the smaller ranges or events you want.
Review any shared-file changes, then write the required summary and finish:
agit merge --into alice/my-project@first-task summary -m "Keep the retry strategy from the alternative"
agit merge --into alice/my-project@first-task --continue
--continue requires a summary and checks that the target has not moved.
It records a two-parent merge commit, with the selected events, merge
markers, and summary in the VIEW. To cancel the open transaction:
agit merge --into alice/my-project@first-task --abort
Aborting leaves the target branch at its original commit. After a completed
merge, inspect the result with agit show alice/my-project@first-task, then
resume that branch.
Cherry-pick or remove selected context
For a small, already-understood selection, you can copy turns without a merge agent:
agit cherry-pick alice/my-project@alternative#5..#6 --into alice/my-project@first-task
To remove an event from the context a session receives:
agit revert alice/my-project@first-task#12.3
Both operations update the VIEW and record the change. The evidence log remains intact; revert does not erase recorded content or secrets.
Pull requests
Hub pull requests propose conversation history to another AgentGit
repository. Start from a copy in your namespace,
work on a session branch, and save it. For this example, bob/my-project
is your copy, repro is your source branch, and
alice/my-project@first-task is the destination.
Publish the exact branch you want reviewed, then explicitly select your
copy with AGIT_SESSION. The -b option selects the source branch:
agit push bob/my-project@repro
AGIT_SESSION=bob/my-project@repro agit pr create alice/my-project@first-task -b repro -m "Explain and fix the retry failure"
PR creation verifies that your local branch head matches the published source. It freezes that source commit, the destination commit, and the exact proposal to review. Later source changes do not update an open PR.
When the destination has not advanced beyond the source’s fork point, the Hub can generate a mechanical proposal without running an agent. For a session target, it preserves the target session and adds the source’s recorded continuation. Prepare an agent-assisted merge before opening the PR if both histories have advanced or you want to curate the selected context.
The repository owner can inspect the proposal before landing it. Replace
PR_ID with its numeric ID:
agit pr show PR_ID
Review the proposed turns and summary on the Hub. To also download the proposal’s Git objects, the target repository must exist locally. Clone it first if needed, then select it explicitly:
AGIT_SESSION=alice/my-project@first-task agit pr fetch PR_ID
Use these environment selections from the matching agent session or a regular terminal; an agent session with a different identity rejects them. After review, the repository owner can land the frozen proposal:
agit pr merge PR_ID
A normal merge lands the reviewed proposal without regenerating it. To
install the contributor’s original source as a separate branch, the owner
can use agit pr merge PR_ID --adopt proposed-fix. The branch name must be
unused. Adoption uses the source commit captured when the PR was opened,
leaves the original destination unchanged, and does not install a generated
proposal.
If the destination branch moves, the PR becomes stale and a normal merge
is refused. Read the reported next steps and prepare a current proposal;
AgentGit does not silently reconcile a different target. The frozen source
can still be adopted into a new branch with --adopt when the PR is stale.
Next, publish and sync the result or return to Everyday commands.