Last updated: November 2026
Use Settings → Tasks to choose how new tasks start and how a task’s page looks, and to manage your task groups. A task is one piece of work: its prompt, the agent sessions working on it, and the worktree or folder they work in.
New tasks
New tasks sets what Kepler preselects for every new task: the agent, where the task makes changes, where its panel opens on the Dashboard, how branches and folders are named, and whether Kepler names the task for you. These values belong to the environment you are working on, so in a remote window they are the remote machine’s.
Default agent
New sessions start with sets the agent that the New task composer, the Dashboard’s composer, and a new draft session start with. It is the same agent-settings pill as in the composer: pick the agent and account, and optionally an agent preset, a model, and other options. Kepler saves each pick as you make it.
Start each session on the agent you used last, below the pill, is on by default. With it, your first session uses the pill’s agent, and each later session starts with the agent, model, and mode you last picked. To start every session on the pill’s agent and settings, clear it.
If you uninstall the agent you saved, the row warns you to pick another. This setting does not apply to Ask Kepler, which has its own default in Settings → Agents.
An Action inherits this configuration unless it names an agent of its own.

Where new tasks make changes
Where new tasks make changes sets what a repository starts on when you attach it to a new task in the New task composer. It has these options:
| Option | What it does |
|---|---|
| Isolated worktree | The default. Creates a new branch in its own worktree, so agents can work in parallel |
| New branch | Creates a new branch in the repository’s own checkout, with no worktree |
| Current branch | Works on whichever branch the repository’s own checkout has |
This setting is only the default. For a single task, the repository chip’s own Base branch and Isolated worktree controls override it. See Create a task.
With New branch and Current branch, commits land on whichever branch is checked out at the time, because both work in the repository’s own checkout. If another task is already working in that checkout, Kepler says so and offers to switch that repository to an isolated worktree instead.
You can edit Branch prefix, Worktrees folder, and Tasks folder whichever option you choose, because a single task can still ask for a new branch or a worktree.
Where a new task opens on the Dashboard
Where a new task opens on the Dashboard sets where the panel of a task you start, or open from a notification, appears among the Dashboard’s open panels:
| Option | What it does |
|---|---|
| Beside the focused panel | The default. Opens the panel next to the one you are reading, or at the end once the panels fill more than one row |
| At the end | Always opens the panel after every open panel |

Branch prefix
The following setting starts the name of every branch Kepler creates:
| Setting | What it controls | Default |
|---|---|---|
| Branch prefix | Starts the name of every branch Kepler creates. A repo can set its own in its settings. | kepler/ |
The prefix applies to automatic names only. Kepler uses a branch name you type exactly as you typed it, so a repository with an enforced feat/ or fix/ push rule still works. If your prefix does not end in a separator, Kepler adds a /, so team becomes team/, while ea- stays as you typed it.
To override the prefix for one repository, use its Edit repo page under Settings → Repositories.
Folder locations
Kepler uses 3 folder settings to decide where to put things:
| Setting | Where it is | What it controls | Default |
|---|---|---|---|
| Worktrees folder | Tasks → New tasks | Where Kepler creates the worktree for each new task. | ~/kepler/worktrees |
| Tasks folder | Tasks → New tasks | Each task gets a folder here for its attachments and files. | ~/kepler/tasks |
| Repositories folder | Repositories | Where Kepler clones repositories, and where it looks for repositories to add | ~/kepler/repositories |
Type a path, or click Choose a folder beside the field to browse. An edit saves when you leave the field.
The fields also warn you about paths that do not work the way you might expect:
- If a Worktrees folder has text before
<REPOSITORY_PATH>, Kepler adds each repository’s full path after that text. The field suggests 2 patterns that work: worktrees next to each repository, or a subfolder per repository. On Windows, Kepler does not save a path like this, so use one of the 2 patterns. - If the Repositories folder does not exist yet, the field tells you that Kepler creates it when you clone.
The Variables menu
A folder field that takes variables has a Variables menu beside it. Pick a variable, such as REPOSITORY PATH, to insert it at the cursor. Kepler fills it in when it creates the folder, so one pattern works for every repository. Each field offers only the variables it can fill in:
| Field | Variables offered |
|---|---|
| Worktrees folder | <REPOSITORY_PATH> (Main repo folder), <REPOSITORY_NAME> (Repo name) |
| Repositories folder | <REPOSITORY_NAME> |
| Tasks folder | None |
For example, <REPOSITORY_PATH>/.worktrees/<REPOSITORY_NAME> nests each worktree inside the repository it belongs to.
Per-repository commands have a Variables menu of their own, with 2 more variables. See Per-repository commands.

Automatically name new tasks
The following setting names new tasks for you:
| Setting | What it controls | Default |
|---|---|---|
| Automatically name new tasks | Names a new task with AI from its prompt and attached resources. A task created from a single issue or PR keeps that item’s name. | On |
A change takes effect on the next task you create.
Task page
Task page sets how a task’s page looks in this window. Kepler saves these settings on this machine:
| Setting | What it controls | Default |
|---|---|---|
| Show tabs on the task page | Keeps sessions, worktrees, and resources open as tabs you can pin, drag between groups, and arrange side by side | Off |
| Preview tabs | A single click opens a preview that the next click replaces. Double-click, or edit, to keep it open. | On |
With Show tabs on the task page off, each column of a task shows one thing at a time, and you switch between them from the list on the left. Preview tabs works only with it turned on. Sessions always open as permanent tabs. See The task view.
Groups
Groups lists all your task groups, including archived ones. To open it from the Dashboard, choose Manage groups… in a group header’s menu.
- To add a group, click New group in the section header.
- To edit a group’s name or color, click its name.
- To reorder groups, drag a row by its grip.
- To archive or delete a group, use its ⋮ menu. You can archive a group once all its tasks are archived.
Archived groups are listed under Archived, where their menu has Restore group. Deleting a group never deletes its tasks; they stay, ungrouped. See Your groups.
