Git, diffs, and Virtual Edits

© 2026 Quadropic Pvt Ltd. Proprietary and confidential. Use restrictions.

Choose an editing strategy#

Create a thread Virtual Edit#

Before sending a new task:

1. Select a Git-backed workspace.
2. Enable Virtual Edit beside the workspace selector, or press ⌘⇧E / Ctrl+Shift+E.
3. Submit the task.

Syntheo creates a temporary Git worktree and branch for the thread. Terminal, file tools, external Open actions, and Git operations should use that effective directory.

For an existing thread, open Git → Virtual Edit → Create Worktree. The agent can then continue in the layer.

Use one Virtual Edit per coherent deliverable. If the goal changes completely, create a new thread and layer instead of turning one branch into a collection of unrelated experiments.

Work safely inside the layer#

Tell the agent what belongs in the layer:

Keep all implementation and tests in this Virtual Edit. Do not apply the layer,
stage, commit, or push. Finish with validation results and remaining risks.

Check the effective directory before running manual commands. An external editor opened from the thread should point at the worktree, but an editor window you opened earlier may still point at the base workspace.

Do not manually delete the worktree directory. Let Syntheo remove or apply the managed layer so Git’s worktree metadata stays consistent.

Review before applying#

Use three levels of review:

1. Agent summary — understand intent, files, tests, and caveats.
2. File Diff panel — inspect captured line-level edits.
3. Git diff in Terminal — verify the authoritative worktree state.

Useful commands:

git status --short --branch
git diff --stat
git diff
git diff --check

Then run the acceptance check inside the layer. For a risky change, also ask a fresh Ask or Debug thread to review the diff without editing:

Review the current diff for correctness, regressions, unsafe assumptions, and
missing tests. Do not edit. Rank findings by severity and cite files.

Apply the layer#

When the layer is ready:

1. Make sure the base workspace has no conflicting or surprising changes.
2. Open Git → Apply Layer.
3. Read the target layer name.
4. Apply it.
5. Inspect git status and git diff in the base workspace.
6. Rerun the most important validation if environment or dependencies differ.

Applying integrates the layer into the real codebase. It is not approval to stage, commit, or push.

If applying fails, do not resolve by deleting files or resetting the repository. Inspect both branches and the reported conflict, preserve user changes, and decide whether to rebase, manually integrate, or revise the layer.

Room worktrees#

A named Autonomy room can own a dedicated worktree. Agents with Inherit operate in it and see each other’s changes immediately.

Before parallel writers start:

• divide ownership by file or subsystem;
• assign one integration owner;
• identify shared files that only one agent may edit;
• define a validation owner;
• keep unrelated work out of the room.

Use Merge into main from the room menu only after the room’s integrated state is reviewed. Deleting a room with a worktree may merge it as part of deletion; read the confirmation carefully.

Direct Git actions#

The Git menu exposes:

Add Current Changes#

Runs the equivalent of:

git add -A
git status --short --branch

It stages all tracked modifications, deletions, and untracked files in the effective directory. Do not use it in a dirty tree unless every change belongs in the same commit. For selective staging, use the Terminal:

git add path/to/file
git add -p

Commit Changes#

Commits the already staged set with your message and adds:

Co-authored-by: Syntheo <syntheo@getsyntheo.com>

The commit action does not decide what should be staged. Inspect git diff --cached first.

Push to Origin#

Pushes the current HEAD to origin. Confirm:

• the branch name is correct;
• commits are intended for that remote;
• no force push is needed;
• required checks or review policy are satisfied.

Pull from Origin#

Uses fast-forward-only pull. It refuses a merge commit when local and upstream history have diverged. Resolve divergence deliberately in the terminal or with your normal Git workflow.

Sync Changes#

Runs a fast-forward-only pull, then pushes the current branch. Use it only when both directions are intended.

Run directly or hand off to the agent#

Git detail views let you either run a command or hand the operation to an agent. Hand off when:

• branch or staging state needs interpretation;
• only some files should be staged;
• a safe commit message requires understanding the diff;
• a pull/push should stop on suspicious state.

Run directly when you already reviewed the exact command and target.

Agent handoff uses the current thread when one is active; otherwise it starts a new Git task. The agent is still subject to tool permissions.

Recovery rules#

• Never use a destructive reset to clean up changes you have not classified.
• Never assume untracked files were created by the current agent.
• If a task changed the wrong directory, stop it before attempting recovery.
• If the base tree was dirty before a Virtual Edit, record that state before applying.
• If a commit contains unrelated files, prefer a deliberate follow-up correction; do not rewrite shared history without explicit authorization.