Work in Motriz
Git, worktrees, and GitHub
Commit and push from any workspace, isolate parallel tasks in managed worktrees, and open and track GitHub pull requests.
Motriz drives Git with the real git binary in your login-shell environment, so PATH, credential helpers, and your SSH agent behave exactly as they do in a terminal. For the task queue itself, see Build, tasks, and review.
How repositories attach
You attach a repository through the product entry flow: choose "Continue from a repository" in the "Add a product." dialog. Motriz scans your home directory for repositories ("Rescan" refreshes; "Choose a folder…" picks one directly). The footer states the contract plainly: "The repository stays where it is. Existing history and work are preserved."
One product owns one repository. Paths are matched by filesystem identity, so symlinks cannot create duplicate ownership, and attaching a repository that already belongs to another product fails and names the owner. A folder does not need a GitHub remote — or even to be a Git repository — but the git header control appears only when the workspace is actually a Git worktree; the Changes tab appears for any product with a repository folder, Git or not.
The git header control
Every conversation header in a product with a repository carries a git pill. It shows a branch icon, the current branch name (or "detached"), and one action word:
| You are on | The pill shows |
|---|---|
| The default branch | "Create branch" |
| A feature branch with a GitHub remote | "Open PR" — then "PR #12" once one exists, and "Merged #12" after it merges |
| A branch with a non-GitHub remote | "Git" |
An orange dot on the icon marks a dirty worktree. Status is polled every 30 seconds, and each poll refreshes the remote with git fetch --prune origin, so ahead/behind counts stay honest. A failed fetch is reported inline ("Remote fetch failed: …") instead of being treated as a clean sync.
While any agent run is active in the repository, the pill is disabled ("Git actions are paused while a run is in progress") and the dialog blocks every mutation: "Git and GitHub mutations are paused until active agent runs in this repository stop." The backend enforces the same rule, so shared Git state never changes under a running agent.
The "Git and GitHub" dialog
Clicking the pill opens the "Git and GitHub" dialog. Its description is precise: the product "uses live state from this thread's workspace." A normal thread operates on the project checkout; a task thread that ran in a managed worktree gets Git state and actions for that worktree, not the checkout. The status section shows the branch, the default branch, "dirty" and "published"/"unpublished" badges, ahead/behind counts, the upstream, the remote URL, head SHAs, and the last sync time.
Commit local changes
The "Commit local changes" section appears when the worktree is dirty. Pick a "Target" — "Current branch" or "New branch" (pre-filled from the thread title, like feat/dark-mode) — write a "Commit message" or press "Suggest", and choose "Commit changes". The commit always includes all dirty files; there is no partial staging from this control. Review the Changes tab first.
Push, pull, and branches
"Push to origin" publishes the branch and sets its upstream when needed — the dialog says it outright: "This does not open a PR." "Pull latest" is fast-forward-only and is blocked by a dirty worktree ("Commit or discard local changes before pulling."). On the default branch, "Create branch" creates and switches to a feature branch, starting from origin/{default} when it exists. Creating a branch — like committing to a new branch or opening a PR — records the branch on the thread, and the sidebar decorates the thread row with its branch and PR state.
On-device commit and PR suggestions
The "Suggest" buttons in the commit and Open PR sections draft text with on-device Apple Intelligence (Apple Foundation Models). Your diff is never sent to a cloud service for this — there is no cloud fallback. Commit suggestions follow your repository's convention: if your recent history uses Conventional Commits, the suggestion is composed as type: description. PR suggestions draft a title and a summary-plus-bullets body from the branch's commits and diff.
Anywhere the requirements are not met, the buttons degrade gracefully with the exact message: "Apple Intelligence suggestions require macOS 26, supported Apple silicon, and Apple Intelligence enabled. The fields remain manually editable."
Managed worktrees for parallel tasks
Sequential tasks run directly in the project checkout. When you run a parallel task stage, every task gets an app-managed Git worktree under ~/Library/Application Support/Motriz/task-worktrees/, on its own branch named feat/mtz-{number}-{title-slug}, created from the checkout's current HEAD.
Uncommitted state carries over: before creating worktrees, Motriz snapshots the checkout — a patch of tracked changes plus copies of untracked, non-ignored files — and applies it to each new worktree. Parallel tasks therefore start from exactly what you see, including dirty files. Only one live run is admitted per worktree, but sibling worktrees of the same repository run concurrently.
Existing task worktrees are never reset — retries reuse the same worktree and branch, preserving task-local work. After a merge, the dialog notes: "This task's managed worktree is retained after merge so the thread remains inspectable." Nothing deletes a worktree automatically in 1.0.0.
Integration is explicit and user-driven. When a parallel stage finishes with dependent work still queued, the queue pauses itself and Build shows "Parallel work is ready to integrate". From each task thread, the git control operates on that worktree: review the changes, commit if needed, open a PR, merge, then pull the default branch in the checkout and resume the queue.
GitHub
Authentication
There is no in-app GitHub login. Motriz resolves a token from your environment: first gh auth token (GitHub CLI), then git credential fill, otherwise it stays unauthenticated. Only GitHub.com remotes are supported — GitHub Enterprise is not — and a non-GitHub remote gets an inert section: "This Git remote is not a supported GitHub.com remote, so PR controls are disabled." See Troubleshooting if PR controls are unavailable.
Opening a pull request
- Get on a feature branch.
Motriz will not open a PR from the default branch or a detached HEAD.
- Review the title and body.
The title is pre-filled from the branch name. An empty body falls back to your local PR template (for example
.github/PULL_REQUEST_TEMPLATE.md) when present, or press "Suggest". - Choose "Open PR".
This pushes the current branch to origin and creates a ready-for-review PR against the default branch — never a draft.
Tracking and merging
On a branch with a PR, the dialog shows "PR #{n}" with its state badge and three detail sections: "CI statuses" (check runs and commit statuses, newest first), "Reviews", and "Comments". The "Merge" section reports either "Ready to merge with the expected head SHA guard." or the exact blockers — for example "PR is a draft" or "PR has merge conflicts". The method select lists only the merge methods your repository allows, defaulting to squash. You must tick the "Confirm merge" checkbox, and the merge sends the expected head SHA — if the PR head moved, it fails with "PR head changed; refresh before merging" instead of merging something you did not review.
After a merged PR, normal threads get an "After merge cleanup" section — "One click: checkout {default}, pull latest, then delete {branch}." Deletion uses the safe git branch -d and never touches the default branch. Task-worktree threads skip cleanup and keep their worktree.
What Motriz never does
- It never merges a PR on its own. Every merge requires your explicit confirmation and is guarded by the expected head SHA.
- It never silently merges parallel branches — integration is yours, and resuming the queue is the confirmation.
- It never stages a subset: commit means all dirty files. Push never opens a PR. Pull never rewrites history — it is fast-forward-only.
- It never marks a work item "Shipped" without an observed merged PR on the thread's branch. Motriz never claims a ship it cannot see.
- It never mutates Git during an active run, and never deletes a managed worktree.