Getting started

This page is for coding agents that can read local instruction files and run commands in your repository. The GitButler skill does not give the agent new permissions. It tells the agent how to use but instead of driving Git through checkout, stash, add, commit, and rebase commands.

Install the but CLI

If you already have GitButler Desktop installed, you can install the CLI from the Desktop Client settings. For terminal-only setup, run:

curl -fsSL https://gitbutler.com/install.sh | sh

See Installation and setup for the full CLI install options.

Run the agent setup wizard

From the repository where the agent will work, run:

but agent setup

The wizard asks which agents you use, where the setup applies, and which workflow preferences you want. It can:

• install the GitButler skill for Codex, Claude Code, Cursor, GitHub Copilot, Windsurf / Devin, OpenCode, or Agent Skills;
• save workflow instructions globally, in this repository, or both.

Before it writes anything, the wizard shows the skill install paths, instruction files, and the exact generated text.

but agent with no subcommand starts the same wizard. For command details, see but agent.

The wizard installs the skill for you. To check installed skills and update any outdated copies later without rerunning the wizard, use:

but skill check --update

See but skill for other install and update options.

The repository itself needs no setup. With one branch applied, it stays a normal checkout of that branch. When an agent creates a second branch, GitButler switches to its workspace branch so both branches can be in the folder at once.

Add optional agent instructions

The wizard can write common workflow preferences for you: folding small fixes into the right commits, splitting mixed work, stacking dependent branches, updating from the target branch, opening draft PRs, landing approved work directly onto the target instead of opening pull requests (single-repository setups only), using a publish phrase, naming branches, following commit-message conventions, and creating checkpoint commits.

Use Tuning agent behavior when you want to read the policies before choosing them, adjust them after the wizard runs, or copy individual snippets by hand.

These instructions steer agent behavior; they are not access controls. Use your usual repository permissions and branch protection for hard limits.

For prompt examples that ask for specific branch and commit outcomes, see Useful requests.