Git and worktrees

What this accomplishes

The git integration in Miton: status awareness, the per-turn restore points, the sub-agent worktrees, the branch management, the smart-commit button, the integration with GitHub, GitLab, and Bitbucket.

Miton uses git as version control for your project. Status, commits, branches, and restore points stay in sync as you and the agent work.

Worktree isolation for sub-agents is in sub-agents; rewind is in per-turn rewind; PR review is in PR review.

Current availability

This page documents behaviour verified in Miton development builds. Miton is still pre-release and is not publicly downloadable; invited beta users will receive a signed desktop build with automatic updates.

Before you start

• A Miton development build and an active project containing source code.
• A connected model. Trust the project before allowing file, terminal or Git actions.

The git status awareness

The git status awareness is a real-time view of the project’s git state. The view is in the status bar and the file tree.

The status bar shows:

• Branch — the current branch name.
• Dirty files — the number of files with uncommitted changes.
• Ahead / behind — the number of commits ahead and behind the upstream tracking branch.
• Conflicts — the number of files with merge conflicts (if any).

The file tree shows the git status of each file:

• Green plus — the file is untracked.
• Yellow tilde — the file has unstaged changes.
• Green check — the file is staged for commit.
• Red minus — the file has been deleted (in the working tree; the deletion is staged or unstaged).
• Blue arrow — the file has been renamed (in the working tree; the rename is staged or unstaged).

The git status awareness updates in real time as the user types, as the agent makes changes, and as files change on disk. The status awareness is powered by the file watcher (see editor and language tooling).

The per-turn restore points

The per-turn restore points are git-native backups the agent creates before every turn. The restore points are stored as git refs under refs/miton/rewind/<sessionId>/<turnId>. The restore points are not commits; the restore points are refs to the tree state at the time of the turn.

The per-turn restore points are visible in the rewind drawer. The user can rewind to any restore point with one click. The rewind is a git checkout of the ref, then a git checkout of the user’s current branch; the user’s branch is not modified.

The per-turn restore points are not pushed to a remote. The refs are local. The user can clean up the refs manually (git update-ref -d refs/miton/rewind/<sessionId>/<turnId>) or by clicking the delete button in the rewind drawer.

The per-turn restore points are documented in detail in the cross-cutting per-turn rewind page.

The sub-agent worktrees

When a write-capable sub-agent must run while another writer already holds the active worktree lease, Miton creates a linked git worktree under .miton/worktrees/<runId> on branch miton/<runId>. The sub-agent’s tool cwd points at that tree. When the run finishes, the user reviews with Apply (merge into the active worktree), Discard, or Keep branch.

Read-only sub-agents share the active project worktree. Linked user worktrees of the same commonGitDir are one Miton project with switchable checkouts — see the StatusBar worktree chip and Status (Orientation) Source Control section.

Status: Write lease + isolation + review Dialog are implemented; marketing that claimed always-on isolation for every sub-agent was overstated and is corrected to in-flight.

The branch management

The branch management is a set of git operations the user can perform from the Miton interface:

• Create a branch — the user clicks the branch picker; the user types a branch name; Miton creates the branch from the current HEAD.
• Switch to a branch — the user clicks the branch picker; the user picks a branch from the list; Miton switches to the branch.
• Create a branch from a remote — the user picks a remote branch from the branch picker; Miton creates a local branch tracking the remote branch.
• Delete a branch — the user picks a branch from the branch picker; the user clicks delete; Miton deletes the branch.
• Merge a branch — the user picks a branch from the branch picker; the user clicks merge; Miton merges the branch into the current branch.
• Rebase a branch — the user picks a branch from the branch picker; the user clicks rebase; Miton rebases the current branch onto the selected branch.

The branch management is per project. The branch picker shows local branches, remote branches, and Miton-managed branches (rewind refs, sub-agent branches).

Canvas and the selected worktree

Canvas and Code read the same selected worktree. Switching a linked worktree changes both surfaces; it does not create another Canvas copy or another conversation. Use Compare with main to inspect the merge-base delta before accepting or publishing changes.

Supported Canvas changes write through the revisioned project artefact path. Source constructs outside that representation remain explicitly code-owned and editable in Code.

The GitHub, GitLab, and Bitbucket integration

Miton integrates with GitHub, GitLab, and Bitbucket for pull request creation, PR review, and issue tracking. The integration uses the user’s existing git remote; the user does not have to configure a separate remote.

The integration requires a per-host credential. The credential is the user’s personal access token (for GitHub and Bitbucket) or the user’s personal access token or OAuth (for GitLab). The credential is stored in the OS keychain; the credential is never written to a config file.

The PR creation is documented in PR review. The PR review (the desktop-local reviewer) is documented on the same page. The issue tracking is documented in the cross-cutting primitives section.

The gitignore and argus-ignore

The git integration respects the user’s .gitignore file. Files matched by .gitignore are not shown in the file tree’s git-status indicators; files matched by .gitignore are not indexed by the code search; files matched by .gitignore are not read by the file watcher.

The user can configure a .miton/argus-ignore file in the project root. The file is a list of patterns to ignore from the code search index. The patterns are standard gitignore syntax. The file is independent of .gitignore; the user can use .miton/argus-ignore to exclude files from the code search that are not excluded from git (e.g. generated files, vendored dependencies, large data files).

What the git integration does not cover

The git integration does not cover:

• Git LFS — Miton does not have built-in support for Git LFS. The user can use Git LFS through the shell tool; the user can also use a third-party LFS plugin.
• Submodules — Miton does not have built-in support for git submodules. The user can manage submodules through the shell tool.
• Interactive rebase — Miton does not have built-in support for interactive rebase. The user can use the shell tool to run git rebase -i.

The git integration focuses on the git operations the user can implement with the existing primitives (the file watcher, the shell tool, the code search). The operations that require additional runtime are documented above; the user can extend the git integration with plugins.

What success looks like

The git integration is real-time. The status bar shows the current branch, the dirty files, the ahead / behind, and the conflicts. The file tree shows the git status of each file.

The per-turn restore points are the rewind primitive. The user can rewind to any turn with one click; the rewind is git-native; the user’s branch is not modified.

The sub-agent worktrees are the isolation primitive. The sub-agent runs in its own worktree; the main session is not affected.

The branch management is per project. The branch picker shows local branches, remote branches, and Miton-managed branches.

Common failures and recovery

• Confirm the correct project and branch are active.
• Check the model connection and the permission request shown in Chat.
• Keep the exact error before retrying; use Code troubleshooting when the failure persists.

Related next action

Open Code troubleshooting for recovery steps and diagnostic paths.