Git workflow
A session on a git workspace works in its own git worktree, so several agents can work on different branches of one repository at the same time. The git panel then takes that work from review to a pull request.

Start a session on a branch
Section titled “Start a session on a branch”A workspace is a git workspace when its folder is inside a git checkout. When you add a workspace and type the path of an existing checkout, mocante fills in the name and source from the folder and its origin remote.
When you type a Source url and the path does not exist or is empty, mocante clones the repository there when you click Add workspace. A path that already has files in it is not cloned into; the dialog shows the error from git.
A plain folder becomes a git workspace when you run git init or clone into it. mocante notices within a few seconds while the workspace page or one of its sessions is open.
- Open the workspace and choose New session….
- In Branch, PR or issue, type or pick what to work on:
- Type a new name, such as
feat/login, to create a branch. - Pick from Local branches to work on a branch you already have.
- Pick from Open PRs to check out a pull request. Type
#142to find one by number. - Pick from Issues to start from a GitHub issue.
- Type a new name, such as
- For a new branch, choose the Base it starts from. The default is the repository’s main branch. Leave Fetch the latest base from the remote first on to start from the remote’s copy of the base.
- Select Start session.
mocante reuses a worktree that already holds the branch. Otherwise it creates one from the base branch, or from the pull request. The worktree folder is named after the branch: feature/login becomes feature-login.
A local base branch can be behind the remote, or hold commits that you did not push. With Fetch the latest base from the remote first on, mocante first fetches the branch that the base tracks, or the branch of the same name on origin, and starts the new branch from that. Your local base branch does not change. A base that is on no remote is used as it is. If the fetch fails, for example when you are offline, the session does not start and the dialog shows why: turn the switch off to start from the local base. The switch stays as you last set it, on each device separately. The new branch does not track the base, so a push goes to a branch of its own name.
A new worktree holds only tracked files. So that tools that read a local environment file still work, mocante copies the .env and .env.* files from the root of the source checkout into a new worktree. It never overwrites a file the worktree already has.
A plain folder that is not a git checkout has no branches. Its sessions share the folder and take an optional Name instead.
Start from an issue
Section titled “Start from an issue”When you pick an issue, the dialog shows its title, labels, people and the start of its body. It proposes a branch name the way GitHub does, such as 142-fix-flaky-auth-timeout. You can edit the name. An existing branch is reused.
The session remembers the issue. Its card and the terminal header carry a #142 badge that opens the issue. The session menu and the command palette offer Open issue and Paste issue to agent. Paste issue to agent types the issue’s title, link and body into the agent’s tab as a prompt. It appears while the terminal shows a tab with an agent in it. If the terminal shows another tab by the time the issue has loaded, nothing is pasted and a notice says so, as a shell would run each line as a command.
Choose where worktrees go
Section titled “Choose where worktrees go”Open Settings → Git → Worktree location:
- Container folder (the default) puts each worktree in
<repo>-worktrees/<branch>next to the repository. Build tools that scan the repository do not see them there. - Beside the repo makes a
<repo>--<branch>folder next to the repository. - A directory in the field below gathers every worktree in one place as
<directory>/<repo>/<branch>. A~means the home folder on the host that owns the workspace.
A repository whose git config sets worktree.baseDir uses that value before these settings. The setting applies only to new worktrees. A worktree that already exists stays where it is.
Browse branches, pull requests and issues
Section titled “Browse branches, pull requests and issues”The workspace view has three tabs under its session cards:
- Local lists worktrees that no session runs in and no agent works in, and local branches without a worktree. Each row has Start session, and Delete worktree… or Delete branch….
- Pull requests lists open pull requests, newest first, thirty to a page.
- Issues lists open issues, most recently updated first. Issues assigned to you come first.
In the pull request and issue tabs, the search field searches GitHub. Type #142 to go straight to one number. Previous and Next move through the pages. Start session on a row opens a session on it, or Open session when one already runs on that branch.
Set up GitHub access
Section titled “Set up GitHub access”Pull requests, issues and badges come from the GitHub CLI, gh. It runs on the device where mocante runs, not on the host. So a workspace on a remote host shows its pull requests as long as gh is installed and logged in on your device.
When the tab cannot read GitHub, it shows the reason instead of an empty list. When gh is not installed, it says so. Install gh, run gh auth login, and refresh the tab.
Only a remote on GitHub counts. A workspace whose origin is on GitLab, Bitbucket or another forge shows “no GitHub remote”, and gets no badges. A GitHub Enterprise remote works when gh has a login for that host: run gh auth login --hostname <your host>.
Pull request badges
Section titled “Pull request badges”A session card, a worktree row or a branch row whose branch is the head of an open pull request carries the pull request number as a badge. The terminal header carries it too, and it replaces an issue badge once a pull request exists. The number links to the pull request on GitHub.
Badges refresh when you open the workspace view, when you select the refresh button in the Pull requests tab, and when you create a pull request from the git panel. A pull request from a fork does not give a badge to a local branch with the same name.
Stacked pull requests
Section titled “Stacked pull requests”A stack is a chain of pull requests where each one is based on the branch of the one below it, as gh stack, Graphite or a hand-made chain creates. mocante finds stacks among the open pull requests of your local branches, so you need no stack tool on the host.
- Workspace view: sessions on the layers of one stack sit together in a dashed box, bottom layer first. The top of the box shows the stack as
main › #141 › #142 › #143. - Terminal header: in place of the pull request badge, a session on a layer shows the whole stack, with its own layer highlighted.
- Git panel: above the changed files, a Stack list shows every layer with its title, top layer first and the trunk at the bottom, as
gh stack viewlists them. The worktree’s own layer is highlighted. - Rows: in the Pull requests and Local tabs, a layer shows its place in the stack, such as
2/3.
In the stack, a layer with a status dot has a session. A layer with a dashed border has none. Select a layer to open its session, or to start a session on it in its own worktree. Select the highlighted layer to open its pull request on GitHub. Right-click a layer for Open on GitHub and Copy branch.
You can work on a stack in one session, where the agent moves between branches with gh stack up and gh stack down, and the header follows the branch it checks out. Or start a session per layer to work on several layers at once. Each layer’s branch view diffs against the layer below, as its pull request does.
Review changes
Section titled “Review changes”The git panel sits beside the session. Show context panel in the palette opens it. It shows:
- Worktree changes: the uncommitted files, with a count of lines added and removed. A renamed file shows once, under its new name; point at it to see the old name. File names with spaces, quotes or accents show as they are. The panel lists up to 100 untracked files; when there are more, the file count in the summary ends with
+, such as104+ files. - Graph: the commits of the branch, then the commits it shares with the base branch. More commits load as you scroll.
Select a file to open its diff in the code view. Select a commit to see its files, each diffed against the parent. Shift-click a second commit to see the whole range as one change. Diff vs main (named after your base branch) shows everything the branch changed since it forked. The palette has the same as Open branch diff, and Open commit… and Open changed file… pick from a list.
To review the whole branch as its pull request would show it, select branch in the code view’s file tree, or run Show every change on the branch from the palette. The panel then lists Branch changes: every file changed since the branch left its base, committed or not, and names the base. The base is the branch that the open pull request merges into. Without a pull request, it is the default branch of the repository. Staging and commit still apply to the uncommitted changes.
The button that shows the code pane carries a green dot while the worktree has uncommitted changes.
The panel checks for changes every few seconds while the window is visible. If git on the host fails or is too slow, the panel says so and keeps the last known changes and history. It then checks less often until git answers again. After you change the repository outside mocante, run Refresh git status from the command palette to read it again at once.
When an agent moves to another worktree
Section titled “When an agent moves to another worktree”An agent can make a new worktree in the middle of a session and work there. Claude Code does this with its worktree tool. The code view and the git panel then follow the agent:
- They show the worktree of the agent tab on screen.
- While a shell tab is on screen, they stay with the agent tab you last looked at.
- When the agent leaves the worktree, they go back to the folder the session started in.
- The branch in the status bar, the pull request badge and Copy branch follow them too.
- When the worktree is deleted, the git panel and the code view close. Open them again to see the folder the session started in.
An agent can also edit a worktree without moving into it, and then mocante cannot tell. So that this work stays in sight, the git panel lists the session’s other worktrees that have changes under Other worktrees, each with the lines it added and removed. Select one to show it. To pick any folder yourself, select the branch name at the top of the git panel, or run Show a worktree in the code and changes panes… from the palette. The list holds the worktrees made since the session started and the folder the session started in. Your pick holds until you choose Follow the agent, or until the worktree is gone.
Stage and commit
Section titled “Stage and commit”Each changed file has a checkbox that mirrors the git index:
- Checked: the whole change is staged.
- A dash: part of it is staged, for example a hunk you staged in the terminal.
- Empty: nothing is staged.
Select the checkbox to stage or unstage the file. The checkbox in the summary line stages or unstages everything. Because this is git’s own index, the terminal and any other tool see the same state.
Type a title in Commit title, and if you like a longer explanation in Description under it. Press Enter in the title, ⌘Enter in the description, or select the commit button:
- Commit staged commits what is staged.
- Commit all appears when nothing is staged. It stages every change first.
The title becomes the commit’s first line and the description its body.
On a Mac with macOS 27, the desktop app can draft both for you. Select the sparkle button beside Commit title, or run Draft commit message from the palette. The on-device model reads the change you are about to commit, the staged files or, with nothing staged, every change in the folder, and fills in a title and a short description. The change stays on your Mac. Read and edit the draft before you commit: it is written by a model from your diff. A draft never replaces text you typed while it was being written, and the button shows only on a Mac that has the model. During a merge there is no draft, since git writes the merge’s message.
When a commit fails, for example because a pre-commit hook rejects it, git’s output shows in the panel.
Push and open a pull request
Section titled “Push and open a pull request”- Select Push beside the branch name. A branch without an upstream is pushed to
originand set to track it. - Select PR, or run Create pull request… from the palette.
- Check the title, the description and the base branch. They are filled in the way
gh pr create --fillwould fill them. A session started from an issue gets aCloses #142line, so merging closes the issue. - Select Create pull request. mocante pushes, creates the pull request and opens it in your browser.
Push and pull request errors, such as missing credentials, a missing remote or a missing gh, show in the panel.
A worktree with a detached HEAD has no branch to push or to open a pull request from. Push and the pull request dialog then say to check out a branch first, and the dialog does not let you create the pull request.
Push, Stage all changes, Unstage all changes and Refresh git status from the command palette open the git panel and show their result there.
Sign commits on a remote host
Section titled “Sign commits on a remote host”Commits and pushes from the git panel on a remote host use your normal ssh connection to that host. If your ~/.ssh/config forwards your ssh agent to the host, for example a 1Password agent, a commit made from the panel can be signed with your local key, as git commit -S would be in a terminal.
A commit waits up to 12 minutes, for the repository’s hooks and for you to approve the key in 1Password. A push waits up to 17 minutes, which also covers sending the commits. A session from a pull request waits up to 3 minutes for each fetch.
Related
Section titled “Related”- Code view for reading and editing the diffs.
- Remote hosts for workspaces on another machine.
- Settings for every option in Settings → Git.
Pull request health
Section titled “Pull request health”A pull request badge shows the state of its pull request with one mark:
| Mark | Means |
|---|---|
| Red × | Checks fail, or the branch has a merge conflict |
| Amber warning | Changes were requested, or the branch is behind its base |
| Amber dot | Checks are running, a review is required, or the pull request is a draft |
| Green ✓ | Ready to merge |
Hover over a badge to read each part. The sidebar row shows the same mark next to the number. mocante reads the state from GitHub every two minutes while a window is open, and only for branches that have a session. The refresh button in the workspace view reads it at once.
Ship in one step
Section titled “Ship in one step”Ship in the git panel, or Commit, push and open a pull request… in the command palette, does all three from one dialog. The agent of the session writes the commit message and the pull request text from the diff. You can edit the text, or type it while the agent writes; what you type stays. If the agent cannot write it, the dialog says why and you type it.
The dialog lists the files in the commit. With nothing staged, that is every change in the worktree. It warns you if an agent in the session is still working.
The agent starts only when there is text to write. Turn off the checkbox in the dialog to start it yourself with Write with…. If the session’s agent cannot write the text, such as pi or opencode, the button names the agent that would, and nothing runs until you press it.
- With nothing to commit, the dialog pushes and opens the pull request.
- If the branch has an open pull request, it commits and pushes, and the title and text stay as they are.
- If a step fails, the dialog shows git’s or GitHub’s message. Try again continues from that step and does not repeat the steps that worked.
The agent runs in the background with no edit rights and no copy of your conversation. It gets up to about 40 KB of the diff, which uses your agent’s plan or API account. Claude Code gets no tools for this. Codex can also read files in a read-only sandbox.
Worktree setup command
Section titled “Worktree setup command”A new worktree has no node_modules or build output. To prepare it, set a Worktree
setup command, such as pnpm install, in the workspace’s settings (Edit workspace…).
It runs in a tab named setup of each session that gets a new worktree, so you can read
its output.
A project can have a setup command too. It runs for each workspace of the project that has no command of its own, such as the same repository on a second host.
To let an agent work out the command, click Ask an agent next to the field, or use
Ask an agent for the setup command in the workspace’s menu or the command palette.
mocante starts a session named setup in the workspace’s own checkout, with the agent
from Agent for new sessions (Claude Code if that is Plain shell). The agent reads the
repository, then asks to save the command with the setup_command_set
agent tool. You read the command in the approval bar before it
is saved. If a session named setup is already open, mocante offers to open it instead.
Setup runs by itself only on a new branch from the base you picked. Setup runs the branch’s code, so for any other branch mocante shows the command and asks first: a pull request, a branch that already exists, a fork of another session, or a branch that Start again makes from a closed session’s last commit. Run setup starts it and Skip leaves the worktree as it is. If the command changes before you click Run setup, it does not run, and the strip shows the new one. Run setup command in the command palette runs it again in any session of the project.
The agent, its task and automatic dev servers wait until setup ends, for at most ten
minutes, and a strip above the terminal says so. Start now stops the wait. They also
start if setup fails, so read the setup tab if the agent reports a broken worktree. If
mocante restarts during the wait, the waiting agent does not start. When mocante asks
first, nothing waits for your answer.