docs/ai-agents-structure

app/.well-known/api-catalog/route.ts

@@ -13,10 +13,10 @@ export function GET(): Response {
             title: "Getting Started Guide"
           },
           {
-            href: absoluteUrl("/features/ai-integration/mcp-server"),
+            href: absoluteUrl("/ai-agents/overview"),
             rel: "service-doc",
             type: "text/html",
-            title: "GitButler MCP Server"
+            title: "GitButler AI Agents"
           },
           {
             href: absoluteUrl("/api/search/openapi"),

app/api/search/openapi/route.ts

@@ -49,7 +49,7 @@ export function GET(): Response {
                         content: { type: "string" },
                         url: {
                           type: "string",
-                          examples: [absoluteUrl("/features/ai-integration/mcp-server")]
+                          examples: [absoluteUrl("/ai-agents/overview")]
                         }
                       },
                       required: ["id", "type", "content", "url"]

app/components/WebMcpTools.tsx

@@ -75,7 +75,7 @@ export default function WebMcpTools(): null {
           properties: {
             path: {
               type: "string",
-              description: "Docs path like /guide or /features/ai-integration/mcp-server."
+              description: "Docs path like /guide or /ai-agents/getting-started."
             }
           },
           required: ["path"]

app/utils/agent-ready.ts

@@ -37,26 +37,26 @@ Use this skill when you need to explain the first-run GitButler workflow to a us
 `
   },
   {
-    id: "gitbutler-mcp-setup",
-    name: "GitButler MCP Setup",
-    description: "Configure a coding agent to use GitButler's MCP server from the CLI.",
+    id: "gitbutler-ai-agent-setup",
+    name: "GitButler AI Agent Setup",
+    description: "Configure a coding agent to use GitButler's `but` CLI and agent skill.",
     type: "documentation",
-    content: `# GitButler MCP Setup
+    content: `# GitButler AI Agent Setup
 
-Use this skill when an agent needs to help a developer connect GitButler to Cursor, VS Code, or Claude Code.
+Use this skill when an agent needs to help a developer organize coding-agent changes with GitButler.
 
 ## Recommended flow
 
-1. Read the MCP setup guide at ${absoluteUrl("/features/ai-integration/mcp-server")} as markdown.
-2. Confirm that the \`but\` CLI is installed before configuring the MCP server.
-3. Use the documented \`but mcp\` stdio transport for agent integrations.
-4. Suggest an automation rule that calls the GitButler MCP tool after file edits.
+1. Read /ai-agents/getting-started as markdown.
+2. Confirm that the \`but\` CLI is installed.
+3. Install or update the GitButler agent skill with \`but skill install\`.
+4. Add baseline version-control instructions so the agent uses GitButler for branching, committing, pushing, and history edits.
 
 ## Key references
 
-- MCP server guide: ${absoluteUrl("/features/ai-integration/mcp-server")}
-- AI overview: ${absoluteUrl("/features/ai-integration/ai-overview")}
-- Claude Code hooks: ${absoluteUrl("/features/ai-integration/claude-code-hooks")}
+- AI agents overview: ${absoluteUrl("/ai-agents/overview")}
+- Getting started: ${absoluteUrl("/ai-agents/getting-started")}
+- Tuning agent behavior: ${absoluteUrl("/ai-agents/tuning-agent-behavior")}
 `
   },
   {

app/utils/discovery.ts

@@ -33,9 +33,9 @@ export function getDiscoveryLinks(): DiscoveryLink[] {
       type: "application/openapi+json"
     },
     {
-      href: absoluteUrl("/features/ai-integration/mcp-server"),
+      href: absoluteUrl("/ai-agents/overview"),
       rel: "service-doc",
-      title: "GitButler MCP Server Docs",
+      title: "GitButler AI Agents Docs",
       type: "text/html"
     },
     {

content/docs/ai-agents/getting-started.mdx

@@ -0,0 +1,103 @@
+---
+title: Getting started
+description: Install `but`, install the GitButler agent skill, and add a baseline version-control policy for coding agents.
+---
+
+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:
+
+```sh
+curl -fsSL https://gitbutler.com/install.sh | sh
+```
+
+See [Installation and setup](/cli-guides/installation) for the full CLI install
+options.
+
+## Install the GitButler skill
+
+Run the installer from the same repository:
+
+```sh
+but skill install
+```
+
+The installer prompts for scope first: current repository or global home
+directory. It then prompts for the skill format. Current formats include Agent
+Skills (`.agents/skills`), Claude Code, OpenCode, Codex, GitHub Copilot, Cursor,
+and Windsurf.
+
+For custom paths, global installs, non-interactive updates, and skill checks,
+see [`but skill`](/commands/but-skill).
+
+## Set up the repository
+
+GitButler currently needs the repository in workspace mode for its multi-branch
+model: multiple GitButler branches in one working directory.
+
+From the repository where the agent will work, run:
+
+```sh
+but setup
+```
+
+You can also skip this step and let the agent run `but setup` when it first
+needs GitButler. For the full list of setup changes, see
+[`but setup`](/commands/but-setup).
+
+GitButler is working toward a plain Git mode that switches into a workspace only
+when multiple concurrent branches are needed. Follow
+[gitbutlerapp/gitbutler#11866](https://github.com/gitbutlerapp/gitbutler/issues/11866)
+for that work.
+
+## Add optional agent instructions
+
+The GitButler skill tells the agent how to use `but`. Your own instructions
+tell the agent what behavior you want.
+
+Put project defaults in a repository instruction file such as `AGENTS.md` or
+`CLAUDE.md`. Put personal defaults in a global instruction file such as
+`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, Cursor rules, Copilot custom
+instructions, or the equivalent for your tool.
+
+These files steer agent behavior; they are not access controls. Use your usual
+repository permissions and branch protection for hard limits.
+
+Use this baseline to keep agent work isolated:
+
+```md
+## Version control
+
+- Use GitButler (`but`) for version-control write operations, including
+  branching, committing, pushing, and history edits.
+- Assume multiple agents may be working in this repository. Do not move, amend,
+  squash, discard, commit, push, or otherwise modify another agent's work unless
+  the user asks.
+- Use a dedicated GitButler branch for each agent session, unless the user asks
+  for a different branch structure. Commit only changes that belong to that
+  session.
+- Do not push or open pull requests unless the user asks.
+- Keep commit messages and pull request descriptions succinct: explain what
+  changed, why it changed, and any important decision.
+```
+
+You can also tune the agent to:
+
+- amend local fixes into existing commits;
+- create checkpoint commits and tidy them before review;
+- create stacked pull requests for dependent work;
+- follow your branch and commit naming conventions;
+- publish, update from main, or create recovery points only when your policy
+  allows it.
+
+For copyable snippets, see
+[Tuning agent behavior](/ai-agents/tuning-agent-behavior).
+
+For prompt examples that ask for specific branch and commit outcomes, see
+[Useful requests](/ai-agents/useful-requests).

content/docs/ai-agents/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "AI Agents",
+  "defaultOpen": false,
+  "pages": [
+    "overview",
+    "getting-started",
+    "useful-requests",
+    "parallel-agents",
+    "review-agent-work",
+    "tuning-agent-behavior"
+  ]
+}

content/docs/ai-agents/overview.mdx

@@ -0,0 +1,56 @@
+---
+title: Overview
+description: Use GitButler to keep coding-agent changes organized into branches and commits you can inspect and review.
+---
+
+Use GitButler with coding agents when you want messy local changes to become
+reviewable branches and commits without moving every task into a separate
+worktree.
+
+GitButler keeps one working directory while organizing changes into separate
+branches and commits. Agents can do that through the [`but` CLI](/cli-overview),
+and you can inspect the same state in the [Desktop Client](/overview). For when
+to use GitButler instead of separate worktrees, see
+[Parallel agents](/ai-agents/parallel-agents#how-this-differs-from-worktrees).
+
+You decide how far the agent goes. You can tell it to stop after local commits,
+or you can allow it to push and open pull requests. GitButler gives the agent
+version-control commands; your instructions decide when it stops.
+
+## What agents can do with GitButler
+
+- **Parallel branches in one workspace.** An agent can create separate branches
+  for independent work while staying in the same working directory. That gives
+  you separate review branches without creating a new worktree, directory, and
+  setup for each task.
+- **Selected files and hunks.** The agent can assign selected files or hunks to
+  a branch, then commit that branch. You can inspect the split before the work
+  is pushed.
+- **Stacked branches for dependent work.** If one change depends on another, the
+  agent can put the dependent branch on top of the branch it needs.
+- **History edits without an interactive rebase.** The agent can move a change
+  from one commit to another, reorder commits, reword commits, absorb fixes, or
+  split a commit with `but` commands.
+- **Review and recovery before publishing.** You can inspect the same branches
+  and commits in the CLI or Desktop Client, then use [`but oplog`](/commands/but-oplog)
+  to restore an earlier local GitButler state if the branch layout needs to be
+  rolled back.
+
+## History edits as direct commands
+
+History edits are where agent workflows often get brittle. Moving one file's
+changes from one commit to another with Git can involve patch restore/reset
+steps, fixup commits, autosquash, or an interactive rebase with one or more
+`edit` stops.
+
+With GitButler, that kind of edit becomes a direct operation: move this file's
+changes into that commit. The operation can still rewrite commits and can still
+conflict. The difference is control flow: the agent gets targeted tools for the
+edit instead of driving a multi-step rebase session.
+
+For more detail, see the [`but rub` command reference](/commands/but-rub) and
+the [CLI guide to moving changes between commits](/cli-guides/cli-tutorial/rubbing#moving-files-between-commits).
+
+GitButler does not currently focus on a direct "push to main" workflow. Today,
+it is best used to get from agent changes to clean local branches, commits, and
+PRs or MRs quickly. Direct push-to-main support is planned for the future.

content/docs/ai-agents/parallel-agents.mdx

@@ -0,0 +1,100 @@
+---
+title: Parallel agents
+description: Run multiple coding agents in one GitButler workspace without creating separate worktrees.
+---
+
+Parallel agents do not require separate worktrees or pre-created branches. Once
+agents use GitButler for version-control writes, you can start another coding
+session in the same repository and prompt it like any other task:
+
+```text
+Work on checkout validation.
+```
+
+When either session is ready, ask it to commit:
+
+```text
+Commit your changes.
+```
+
+The agent uses GitButler to commit the changes for its task to its GitButler
+branch. The branch routing is the agent's job; your prompt can stay small.
+
+If two sessions touch the same file or generated output, have the agents call
+out the overlap before committing.
+
+You can also ask an agent to split independent work out of the current session.
+For example, if a feature session also finds a small bug fix, the agent can
+move the relevant changes or commits to a new branch and prepare a separate PR
+instead of stacking the fix on the feature.
+
+For more background on the branch model, see
+[Parallel branches](/features/branch-management/virtual-branches).
+
+If you prefer automatic checkpoint commits, add that as an agent instruction.
+For an example, see
+[Commit checkpoints after each completed turn](/ai-agents/tuning-agent-behavior#commit-checkpoints-after-each-completed-turn).
+
+The baseline `Version control` instructions from
+[Getting started](/ai-agents/getting-started#add-optional-agent-instructions)
+are useful if you want to steer commit behavior, but they are not a separate
+parallel-agent setup step.
+
+## Handle dependencies explicitly
+
+Parallel agents work best when sessions start independent. If one session
+starts depending on another, make that relationship explicit by stacking the
+branches:
+
+```text
+The notification settings work now depends on checkout validation. Stack your
+branch on top of the checkout validation branch.
+```
+
+If an unrelated fix shows up inside a feature session, tell the agent to extract
+it instead:
+
+```text
+The cache invalidation fix is independent. Move it to a separate GitButler
+branch and prepare a separate PR for it.
+```
+
+If the feature depends on the fix, put the fix on the lower branch and stack the
+feature above it instead. For stacked PR policy, see
+[Create stacked pull requests](/ai-agents/tuning-agent-behavior#create-stacked-pull-requests).
+
+## Know what is shared
+
+Parallel GitButler branches are not runtime isolation. The agents share one
+filesystem, dependency install, generated files, and app state. That can surface
+overlap and broken builds earlier, but it can also hide accidental
+dependencies.
+
+Before shipping a branch independently, check whether it depends on another
+active branch. If two agents start editing the same files or generated output,
+decide whether to keep the work parallel, stack one branch on the other, or use
+separate worktrees.
+
+## How this differs from worktrees
+
+Git has one checked-out branch per worktree. If you want two agents to work on
+two branches at the same time, the usual Git answer is multiple worktrees.
+
+GitButler gives you a different option: multiple active branches in one
+worktree, with each agent's commits organized onto the branch for its session.
+
+| | Multiple worktrees | GitButler parallel branches |
+| --- | --- | --- |
+| Workspace | One directory per agent | One shared working directory |
+| Branches | One checked-out branch per worktree | Multiple active branches in one worktree |
+| Isolation | Separate checkout | Shared filesystem and runtime state |
+| Setup cost | Usually more directories, dependency installs, build outputs, and dev servers | Reuse one install and dev server when tasks can share runtime state |
+| Version-control shape | Branches stay separate because work happens in separate directories | GitButler can commit the right subset of changes to each branch |
+| Best fit | Competing attempts, incompatible checkout states, isolated runtimes | Unrelated features or fixes that can share one workspace |
+
+Use multiple worktrees when agents need incompatible checkout states, separate
+runtime state, or competing attempts at the same task. Use GitButler parallel
+branches when the tasks are independent enough to share one workspace and you
+want less local overhead.
+
+For more request examples, see [Useful requests](/ai-agents/useful-requests).