Last updated: April 2026
Use this page to create and monitor coding agent sessions in GitKraken Desktop. The Agents panel lets you spin up a new agent session on any branch, track its progress while you keep working, and act on the results — all from the left panel without switching context.
Requirements and limits
- A coding agent CLI must be installed and configured in Preferences > External Tools > Coding Agent. GitKraken auto-detects installed CLIs
- Agent sessions each run in their own Git worktree and working directory
- Setup commands (install scripts, build steps) are configured per repository in Preferences > Repo-Specific Preferences > Agents
| Workflow | Supported | Notes |
|---|---|---|
| Open Agents panel | Yes | Toggle with List | Agents at the top of the left panel |
| Create a new agent session | Yes | Creates a worktree, runs setup commands, and launches the agent |
| Choose base branch per agent session | Yes | Defaults to HEAD |
| Choose coding agent per agent session | Yes | Falls back to the agent set in Preferences |
| Monitor agent status | Yes | Each card shows WIP changes, ahead/behind, and agent status |
| Configure setup commands | Yes | Per repository in Preferences > Repo-Specific Preferences > Agents |
Quick Start
To open the Agents panel: Click Agents in the List | Agents segmented control at the top of the left panel.
To start a new agent session:
- Click the + New Agent Session button at the top of the Agents panel.
- Type a branch name.
- Optionally set a base branch, choose a coding agent, or click Configure setup commands.
- Click Start.
To monitor agents: Each card shows the branch name, WIP change count, ahead/behind status, and agent status. The status bar at the bottom of each card reflects whether the agent is running, waiting for input, or done.
To act on an agent session: Right-click any card to open, push, create a pull request, lock, or remove the worktree.
To configure the coding agent: Go to Preferences > External Tools > Coding Agent.
To configure setup commands for the current repository: Go to Preferences > Repo-Specific Preferences > Agents.
How the Agents panel works
The Agents panel is toggled by the List | Agents segmented control at the top of the left panel. When active, it shows all agents and worktrees for the current repository as cards. The List view and Agents view share the same underlying worktrees — you can switch between them at any time.
Why Agents instead of worktrees? The Agents panel surfaces the same underlying Git worktrees as the List view, but organizes them around agent activity — status, progress, and quick actions — rather than branch references. You can switch between views at any time without losing your work.
How to start a new agent session
-
In the Agents panel, click the + New Agent Session button at the top of the panel.
The button expands into an inline creation form with the branch name input focused.
-
Type a branch name.
-
Optionally configure the inline settings:
Setting What it does Default Base branch Which branch to create the new worktree from HEAD Coding agent Which agent CLI to launch in the session Set in Preferences To configure setup commands, click Configure setup commands to open Preferences > Repo-Specific Preferences > Agents.
-
Click Start.
GitKraken creates a new worktree from the selected base branch, runs any configured setup commands, and launches the selected coding agent in the embedded terminal.
How to monitor active agent sessions
Each card in the Agents panel represents a worktree and shows:
| Card element | What it shows |
|---|---|
| Branch name | The branch checked out in that worktree |
| WIP change summary | Count of uncommitted file changes |
| Ahead / behind | Commits ahead of and behind the remote |
| Agent status | Running, waiting for input, or done |
The status bar at the bottom of each card describes the agent’s current status. Status indicators are available for Claude Code as of version 12.0.0.
When an agent needs your attention — for example, when it is waiting for input — a bell icon appears on the card alongside a Waiting for input label, so you don’t need to switch to the agent’s terminal to notice.
You can continue working in any other worktree while monitoring agent cards. When a card turns green, switch to it to review the agent’s output.
How to act on an agent session
Right-click any card in the Agents panel to access actions for that worktree:
| Action | What it does |
|---|---|
| Open this worktree | Switches to the worktree |
| Open worktree in a new tab | Opens the worktree in a new GitKraken tab |
| Lock this worktree / Unlock this worktree | Toggles the worktree’s locked state. A locked worktree cannot be pruned, moved, or deleted. The menu shows Unlock this worktree when the worktree is already locked. |
| Remove this worktree | Deletes the worktree and its working directory |
How to configure the coding agent
Go to Preferences > External Tools > Coding Agent to choose which agent CLI GitKraken launches when starting a new session.
Supported coding agents:
- Claude Code
- Codex CLI
- Copilot CLI
- Gemini CLI
- OpenCode
GitKraken auto-detects installed CLIs. You can also provide custom CLI arguments to pass when starting an agent session.
How to configure setup commands
Setup commands run in sequence in the new worktree before the coding agent launches. Use them to install dependencies and prepare your environment (for example, npm install or pnpm build). Put each command on a new line.
Go to Preferences > Repo-Specific Preferences > Agents to define setup commands for the current repository. Because they live under Repo-Specific Preferences, setup commands are scoped to the repository you configure them in.
Typical workflow
- You are working on a feature in your current worktree (highlighted card in the Agents panel).
- A bug report comes in. You click + New Agent Session, type
fix/login-crash, and press Enter. - A new card appears. GitKraken sets up the worktree and the agent starts.
- You continue working on your feature. A few minutes later, you glance at the left panel and see the agent has finished its work.
- You switch to the
fix/login-crashworktree, review the changes in the diff view, and open a pull request. - After the pull request is merged, you right-click the card and remove the worktree.
