Frontmatter:
title: Create a Task
description: Learn how to create Tasks in Kepler from scratch, from issues, or from pull requests — and how to manage them through to completion.
taxonomy:
category: kepler
Purpose: Cover the full Task lifecycle: what a Task is, the three ways to create one, how to configure worktrees and shared context, and how to manage Tasks as work moves through the pipeline.
Sections to include:
What is a Task?
A Task is the core unit of work in Kepler. It holds work across one or more repos and contains worktrees, agent sessions, and changes.
What lives inside a Task: one or more worktrees (one per repo), one or more agent sessions, a diff/changes view, and shared context.
Tasks move through stages: Exploration → In Development → In Review → Done.
Three ways to create a Task: from scratch, from an issue, from a pull request.
Creating a Task from scratch
When to use: you know the goal and don't need to pull context from an existing issue or PR.
Step-by-step:
Click "+ New task."
Pick your repos.
Choose "New worktree" or select an existing branch.
Set the base branch using the "from" dropdown (searchable; origin/main is labeled DEFAULT).
Optionally click "+ Add repo" to add more repos to the same Task (each gets its own worktree and base branch configuration).
Set Agent, Mode, Model, and Effort in the bottom bar.
Click "Launch task."
Settings reference table: Repo(s) | Worktree (new or existing) | Base branch | Agent | Mode | Model | Effort.
Creating a Task from an issue
Supported trackers: GitHub Issues, GitHub Enterprise, GitLab, GitLab Self-Hosted, Jira, Linear, Trello, Azure DevOps. (Link to issue-tracker-integrations.md.)
How to find an issue: search bar (title or paste URL), or use the filter bar. Filter options: "Assigned to me" / "All visible" toggle, provider, repo, "Hide tasked" (hides issues that already have an active Task).
Select one or more issues; Kepler creates a Task per issue, spins up worktrees, and passes issue context (title, description, metadata) to the agent automatically.
Task preview row: repo selector, worktree type ("New worktree" or existing branch), base branch "from" picker (searchable dropdown, DEFAULT labeled). "+ Add repo" to span multiple repos.
Bottom bar: Agent, Mode, Model, Effort apply to all Tasks being launched. Summary shows "N issues → N tasks." Click "Launch task."
Creating a Task from a pull request
Supported providers: GitHub, GitHub Enterprise, GitLab, GitLab Self-Managed, Bitbucket, Azure DevOps. (Link to pull-request-integrations.md.)
Two use cases: (1) start a review on a PR, (2) have an agent address review comments.
How to find a PR: search bar (title or paste URL); filter by provider, repo, or "Hide tasked."
Selecting multiple PRs: two options appear — "Split into N tasks" (one Task per PR) or "Group as 1 task" (all PRs under one Task). Explain when to use each.
Task preview: shows the repo, the worktree branch name Kepler will create (e.g., "Worktree will be created on new-example-page"), and a per-task repo selector. Kepler infers "Address feedback" as the agent's starting instruction from the PR context (diff, description, open comments).
Bottom bar: Agent, Mode, Model, Effort; summary shows "N PRs → N tasks."
Step-by-step for single-PR and multi-PR flows (two separate numbered sequences).
Task detail: worktrees, sessions, and shared context
Task header shows Task name and total worktree count (e.g., "5 worktrees").
Worktrees section: lists every worktree with branch name and repo name.
Sessions panel: lists all agent sessions with branch, repo, and a "NEW CONTEXT" badge when there is unread context.
Shared context: anything added here is sent to every agent session on the Task. Use it for standing instructions, style rules, or reference material that all agents should follow.
Prompt card: shows the prompt text and version number (e.g., "v2"). Edit or Remove using the buttons on the card.
"+ Add markdown": add additional context as a markdown block.
When to use shared context: when you want every agent in the Task to follow the same rules (e.g., "If a .md file has a date stamp, change it to June 2026").
Managing Tasks
Session status vs. Task stage: Task stage is the Kanban column (Exploration → Done). Session status is the real-time state of the agent. The six session statuses:
🟠 Needs Attention — agent is waiting for input
🟢 Active — agent is running
⚫ Idle — session stopped, not complete
🔴 Errored — session hit an error
⚫ Inactive — not running, no pending work
Disconnected — session lost connection to the agent runtime (confirm cause and reconnect steps with engineering)
Notifications: Kepler sends a toast notification when a Task completes or needs attention. The toast shows the Task name, the agent that ran it, and the repo/branch. A View button jumps directly to the Task.
How to move a Task between columns manually.
How to archive a Task (archive icon on the card).
What happens to worktrees when a Task is closed.
Frontmatter:
title: Create a Task
description: Learn how to create Tasks in Kepler from scratch, from issues, or from pull requests — and how to manage them through to completion.
taxonomy:
category: kepler
Purpose: Cover the full Task lifecycle: what a Task is, the three ways to create one, how to configure worktrees and shared context, and how to manage Tasks as work moves through the pipeline.
Sections to include:
What is a Task?
A Task is the core unit of work in Kepler. It holds work across one or more repos and contains worktrees, agent sessions, and changes.
What lives inside a Task: one or more worktrees (one per repo), one or more agent sessions, a diff/changes view, and shared context.
Tasks move through stages: Exploration → In Development → In Review → Done.
Three ways to create a Task: from scratch, from an issue, from a pull request.
Creating a Task from scratch
When to use: you know the goal and don't need to pull context from an existing issue or PR.
Step-by-step:
Click "+ New task."
Pick your repos.
Choose "New worktree" or select an existing branch.
Set the base branch using the "from" dropdown (searchable; origin/main is labeled DEFAULT).
Optionally click "+ Add repo" to add more repos to the same Task (each gets its own worktree and base branch configuration).
Set Agent, Mode, Model, and Effort in the bottom bar.
Click "Launch task."
Settings reference table: Repo(s) | Worktree (new or existing) | Base branch | Agent | Mode | Model | Effort.
Creating a Task from an issue
Supported trackers: GitHub Issues, GitHub Enterprise, GitLab, GitLab Self-Hosted, Jira, Linear, Trello, Azure DevOps. (Link to issue-tracker-integrations.md.)
How to find an issue: search bar (title or paste URL), or use the filter bar. Filter options: "Assigned to me" / "All visible" toggle, provider, repo, "Hide tasked" (hides issues that already have an active Task).
Select one or more issues; Kepler creates a Task per issue, spins up worktrees, and passes issue context (title, description, metadata) to the agent automatically.
Task preview row: repo selector, worktree type ("New worktree" or existing branch), base branch "from" picker (searchable dropdown, DEFAULT labeled). "+ Add repo" to span multiple repos.
Bottom bar: Agent, Mode, Model, Effort apply to all Tasks being launched. Summary shows "N issues → N tasks." Click "Launch task."
Creating a Task from a pull request
Supported providers: GitHub, GitHub Enterprise, GitLab, GitLab Self-Managed, Bitbucket, Azure DevOps. (Link to pull-request-integrations.md.)
Two use cases: (1) start a review on a PR, (2) have an agent address review comments.
How to find a PR: search bar (title or paste URL); filter by provider, repo, or "Hide tasked."
Selecting multiple PRs: two options appear — "Split into N tasks" (one Task per PR) or "Group as 1 task" (all PRs under one Task). Explain when to use each.
Task preview: shows the repo, the worktree branch name Kepler will create (e.g., "Worktree will be created on new-example-page"), and a per-task repo selector. Kepler infers "Address feedback" as the agent's starting instruction from the PR context (diff, description, open comments).
Bottom bar: Agent, Mode, Model, Effort; summary shows "N PRs → N tasks."
Step-by-step for single-PR and multi-PR flows (two separate numbered sequences).
Task detail: worktrees, sessions, and shared context
Task header shows Task name and total worktree count (e.g., "5 worktrees").
Worktrees section: lists every worktree with branch name and repo name.
Sessions panel: lists all agent sessions with branch, repo, and a "NEW CONTEXT" badge when there is unread context.
Shared context: anything added here is sent to every agent session on the Task. Use it for standing instructions, style rules, or reference material that all agents should follow.
Prompt card: shows the prompt text and version number (e.g., "v2"). Edit or Remove using the buttons on the card.
"+ Add markdown": add additional context as a markdown block.
When to use shared context: when you want every agent in the Task to follow the same rules (e.g., "If a .md file has a date stamp, change it to June 2026").
Managing Tasks
Session status vs. Task stage: Task stage is the Kanban column (Exploration → Done). Session status is the real-time state of the agent. The six session statuses:
🟠 Needs Attention — agent is waiting for input
🟢 Active — agent is running
⚫ Idle — session stopped, not complete
🔴 Errored — session hit an error
⚫ Inactive — not running, no pending work
Disconnected — session lost connection to the agent runtime (confirm cause and reconnect steps with engineering)
Notifications: Kepler sends a toast notification when a Task completes or needs attention. The toast shows the Task name, the agent that ran it, and the repo/branch. A View button jumps directly to the Task.
How to move a Task between columns manually.
How to archive a Task (archive icon on the card).
What happens to worktrees when a Task is closed.