Last updated: November 2026
You can start a task in 5 ways. The shortest starts from work that is already assigned to you:
| Start from | How |
|---|---|
| Work assigned to you | Run an Action on an issue or pull request in the Todo view of the Kepler interface. One click starts the task with its context attached |
| Something you’re describing yourself | New task opens the New task composer, where you write the prompt and attach what it needs |
| A conversation you already started | Open an external session, under the New task composer, wraps a task around an agent session you began in your own terminal |
| Workspaces in another agent app | Import from another app brings workspaces from Conductor, Orca, herdr, or Vibe Kanban in as tasks, with their branches and chats |
| Another GitKraken app | A link from GitLens or GitKraken Desktop opens Kepler on the work you were looking at |
From an issue or pull request

Starting from an issue or pull request is the shortest path. Find the item in Todo and click its Action button. Kepler then does the following:
- Creates the task.
- Attaches the repository and the item.
- Sets up a worktree.
- Starts an agent with the context in place.
The default Action depends on the item:
- Plan for an issue.
- Address Feedback for a pull request you authored.
- Review for someone else’s pull request.
You can edit all of these Actions. To read an Action’s prompt, open the list under the button’s chevron and hover the Action. See Actions.
Kepler names tasks automatically from what you started them with. To rename a task, use Rename task in the ⋮ menu, whose field also has an Auto-name button that suggests a name from the task’s prompt and resources. See Tasks and Resources.
Note: Nothing in Todo? Set up your issue tracker and pull request integrations in Settings first. Todo shows work only from connected accounts.
From the New task composer
Click New task or press Cmd/Ctrl+N. To start one without switching to Kepler first, press Shift+Alt+N to open the quick launcher from anywhere, including when Kepler is not the focused window.

The New task composer is a prompt box above a row of 4 buttons:

| Control | What it attaches |
|---|---|
| Add repo or folder | A repository to work in, or a plain folder |
| Add issue → Issues | Issues from your connected trackers. For Linear, pick a team or Project to list everyone’s open issues, not just yours |
| Add PR → PRs | Pull requests from your connected hosts |
| Add context | Files and links the agent can read. A folder to work in goes through Add repo or folder |
Each picker lists what you have already attached of its kind, where you can also remove it.
Paste a link to attach it. Paste a pull request or issue URL into the prompt, from a connected host or from Jira or Linear, and it becomes a chip naming the item. The chip attaches the item the same way Add issue or Add PR would, along with its repository, so a pull request from another repository launches in that repository, on its branch. If the repository is not in Kepler yet, Kepler clones it when the task starts.
A repository you pick yourself takes precedence over the link’s. If Kepler cannot read a link, the composer says so, and the agent gets the link to continue from.
In a window connected to another machine, picking a file through Add context also offers Upload from this machine. Uploads are saved into the task’s own folder when it starts.
Repositories and folders share 1 list, with the places you use most at the top.
You can attach as much or as little context as you want. To create a task from the composer, follow these steps:
- Write the prompt: Describe a task or ask a question…
- Attach what the prompt needs. You can also attach nothing.
- If you attached a repository, configure it. See Configuring a repository.
- Click the primary button, such as Start.
The composer remembers the repositories you last started a task with and stages them again the next time you open it. The branch and worktree settings reset to their defaults.
The composer also remembers an unsent draft. If you close the dialog with a prompt half written, the prompt is still there when you reopen it. Kepler asks before it discards a draft.
Kepler also remembers which repository you pick for a tracker project. When you pick a Jira, Linear, or Azure issue, its Repository chip holds the repository you used for that project before. To use another repository, or No repository, choose it from the chip’s menu.
The primary button runs the Action that matches what you’ve attached, exactly as it would from a Todo row. A linked pull request resolves to Address Feedback or Review, depending on who wrote it; a linked issue resolves to Plan. With nothing attached, the button reads Start and starts the task with your prompt as written.
To keep Start when you link an issue or pull request, turn the switching off: click Turn off in the note the composer shows the first time it switches, or turn off Suggest automatically in Settings → Actions.
The chevron beside the primary button lists the other choices: Prepare, which creates the session without starting work yet, and every Action that applies to what you’ve attached. Picking one there does not run it. Instead, it relabels the primary button, and an Action that names its own agent puts that agent in the agent pill. You can then check or change what will run before you press the button. To pick an Action and run it at once, hold Cmd/Ctrl as you click it. The Action sends its prompt, with anything you typed added as a refinement.
Shift+Tab in the prompt cycles the primary button through the same list.
A task that has its prompt but no session yet, such as one an agent created for you, opens a draft session tab. To send the task’s prompt as written, press Start on the empty box.
The task appears in the list as soon as you press Start, with a Preparing pill until setup finishes. The task’s panel and the task page show each launch step. Cancel stops a launch while Kepler is reading a link or cloning a repository.


If setup fails, the row’s pill reads Failed and the panel shows the error. To change the task and try again, click Edit and retry, or Dismiss to clear it. If it failed because a repository or folder is not trusted, the panel says so: click Trust and retry. A task that starts without some of its repositories warns you which ones it left out. When they were left out because they are not trusted, the warning offers Trust. See Trust a repository.
If the task starts but its agent session does not, the task page and the Dashboard panel say that the agent was unable to start, with Retry. See Agent Sessions.
Configuring a repository
Each attached repository gets a chip with 3 segments:

- Base branch: by default, the task gets a new branch from the repository’s remote default branch. Open the segment to branch off a different branch, to work directly on an existing one, or to take the repository’s current branch in place.
- Branch name: the new branch’s name, suggested from your prompt as you type. Click it to edit it. See Naming the branch.
- Isolated worktree: an on/off toggle, on by default, that gives the task its own working copy. Turn it off to have the task share your repository folder, so a branch switch there moves your checkout. See Tasks and Resources.
What a newly attached repository starts on is a setting. The 3 segments start from Settings → Tasks → New tasks → Where new tasks make changes: Isolated worktree (the default), New branch, or Current branch. The setting changes only the starting point. You can still change every segment for each repository in each task. See Settings.
Picking New branch or Current branch means the task runs in the repository’s own checkout rather than an isolated one, so only 1 task can use that checkout at a time. If another task already has it, the chip says Another task is working here and names it. Click Create a worktree for this task to put this repository in an isolated worktree instead.
Naming the branch
Kepler names a task’s branch from what the task is about, rather than from the task’s name alone:
- The name is suggested from your prompt and appears on the chip as you type. Click it to edit it: Enter keeps your name, and Esc restores the suggestion.
- An issue identifier leads the name when the task came from one, such as
KEP-421-fix-the-import-path. - Automatic names are namespaced under
kepler/. - A name you type is yours verbatim. The prefix applies to automatic names only.
- Kepler applies your repository’s own branch-naming policy where the host publishes one.
You can set the prefix in 2 places: Settings → Tasks → New tasks → Branch prefix for the app, and per repository in Settings → Repositories, on the repository’s own page. The repository’s page offers Default (prefix), None, or Custom, and shows an example branch name. Leave the app setting empty for no prefix at all.
A repository linked to a pull request always opens in its own isolated working copy, and the toggle is locked. Kepler never overwrites a local branch that has commits the pull request does not: it starts the task on a new branch that tracks the pull request.
When the task starts, Kepler clones a repository you have not cloned yet into your Repositories folder. Until then, you cannot pick its branch.
Attaching the same repository twice gives the task 2 independent worktrees on it, for example to compare 2 approaches. Two chips that would end up in the same worktree are marked Duplicate worktree, and Kepler creates only 1 of them.
From a session you already started
If you started work with an agent in your own terminal, you can track that conversation in a task. Under the New task composer, and on an empty tasks list, Open an external session switches the composer to a list of every agent conversation Kepler can see. Start a new task switches back. Open an external session appears only while external session detection is on.

| Part | What it does |
|---|---|
| Live now | Sessions live in a terminal right now |
| Past sessions | Conversations found on disk, from any time |
| Find an external session… | Searches across both groups |
Pick a conversation to continue it in a new task:
- A past conversation resumes.
- A live conversation opens read-only in its task, so you can follow it while it keeps running in your terminal. Once the conversation is idle, close it in your terminal, then click Continue here in the session to continue it in Kepler.
When a task already covers that folder
When the conversation’s folder already belongs to a task, Kepler asks under the list. Add it to that task adds the conversation to that task, and Make a new task creates a new one anyway.
Starting a task from an external session anywhere else, such as from a Kepler link, asks the same question in the Add to existing task? dialog. Add to task adds the conversation to the task you pick, and Create a new task creates a new one anyway. When several tasks include the folder, the dialog marks the closest.
For what happens to the conversation once it’s on a task, including forking, continuing, and what Kepler will and will not answer on its behalf, see Agent Sessions.
From another agent app
If you work in Conductor, Orca, herdr, or Vibe Kanban, you can bring its workspaces into Kepler as tasks. Each workspace becomes a task in the same folder, on the same branch, and its chats continue as the task’s sessions. From Conductor, Kepler imports the workspaces the Conductor app keeps on your Mac, not Conductor Cloud workspaces.
To import workspaces from Conductor, take the following steps:
- On an empty Tasks list, click the import card. It names the apps Kepler found, such as Import from Conductor, Orca and 2 more. You can also choose File → Import from Another App….
- If Kepler finds more than 1 app, click Conductor.
- Tick the workspaces you want, and click Import N workspaces. A workspace you already imported is marked Already a task.
- When Import finished shows what came over, click Done.
- Find the new tasks in Tasks. Open one to pick its chat up where it left off.





Continue each chat in one app only: both apps write to the same chat history.
From a folder, or from nothing at all
A task does not need a repository. Attach a plain folder from Add repo or folder, and the agent works on it in place, with no branch, no worktree, and no Git at all. A folder of notes or a scratch directory works as a normal task.
When you browse for a folder in a window connected to another machine, Kepler opens its own folder picker. To use this picker everywhere, turn on Always use the custom folder picker in Settings → General. When you type a path into it, Kepler checks the path and, for a path close to an existing folder, offers Did you mean with the closest folder.
You can also attach nothing at all: no repository, no folder, and no issue. Use a task like this to ask a question or explore an idea, and attach the real work later, once it’s worth tracking. See The Task View.

From another GitKraken app
You can open Kepler from other GitKraken products, such as GitLens and GitKraken Desktop. A link from one of them can do the following:
- Open the New task composer already filled in with the issue, pull request, or repository you were looking at.
- Open a task or session you already have.
- Put a prompt and an Action in the composer.
- Start a new session on a task you already have.
- Start right away rather than waiting for you to press Start.
For an item that a task already holds, Kepler offers Open task instead. If the repository is not on this machine, Kepler clones it when the task starts. A link that Kepler cannot fully resolve still opens, with a warning about what Kepler could not use.
Which window a link opens in
Kepler sends each link to the window that can use it:
- A link for a task opens in the window already showing that task.
- A link that names a saved remote machine opens in a window on that machine. If none is open, Kepler opens one.
- Any other link goes to the window you used last.
If a link cannot open on the machine it names, it opens on this computer instead, a notice says so, and nothing it asked to start runs on its own. In a window on a remote machine, a link for something that is not there offers Open on this computer.

After the task starts
The task appears in the Tasks view right away, with the Preparing pill until its setup finishes. Click it to open its side panel, or double-click it to open the task page.

From there you can add more sessions, attach more resources, and review what the agent changed. See Agent Sessions and Review What a Coding Agent Changed.
Context: what gets handed to the agent
Starting from Todo and starting from the New task composer send the same Action prompt, but they attach different amounts of detail:
| Started from | What the agent receives |
|---|---|
| A row in Todo | The full issue or pull request body, attached as shared context |
| The New task composer | A reference (identifier, title, and URL) which the agent fetches the detail from itself |
Either way, Kepler saves each linked issue’s description as a note titled with the issue’s identifier and title; long descriptions are shortened with a link to the issue. Kepler does not save pull request descriptions this way.