Skip to main content
A task connects a Linear issue to an agent conversation and a separate Git worktree. Use it to give the agent a defined outcome, follow its progress, and review the resulting files before moving the issue through your team’s workflow. This guide follows the desktop Tasks layout. For a conversation without a Linear issue, start in Zen.

​
Before you start

  • Connect the issue’s Linear organization and open the correct team in Tasks.
  • Open the project on the computer where the agent will run. That computer needs an available project connection, Git, and the selected harness and model.
  • Check the repository and starting branch. A new worktree starts from a commit; do not assume uncommitted files from your current checkout will appear there.
  • Decide what the agent should achieve, how it should verify the result, and which actions need your approval.
Tasks submits its first prompt as a goal, which can continue across multiple responses. The task execution path supports Codex’s native goals and Claude Code’s goal integration. Other harnesses can appear in the model picker without supporting task goals. A provider or model being available for an ordinary chat does not establish task support.
Pi can run a goal in an ordinary Zen conversation, as shown in Verify a completed goal. The Linear task launcher currently rejects Pi with harness-does-not-support-goals:pi. Choose Codex or Claude Code for an issue-linked task, or use an ordinary conversation for the Pi goal workflow.

​
Start one issue

1

Open the issue's start dialog

Select the issue’s title or card, read its description, and choose Start task under Agent.The row’s Run task shortcut can start immediately using configured defaults. Use the issue details when you want to inspect and edit the start choices first.
2

Choose the project and starting branch

Select the project folder. This is the repository where the agent will work, distinct from the issue’s Linear project.Wait for its connection and repository check. The branch selector starts at Current HEAD; select another available branch when needed.Choose the project before editing the prompt. Changing projects resets the branch choice and regenerates the proposed prompt.
3

Review the prompt, model, and permissions

Edit the proposed prompt to state the result you want. Include acceptance criteria, tests, files to preserve, and any limits on committing or publishing.Check the harness, model, reasoning choice where available, and permission mode in the composer. Ask first keeps approval decisions in the conversation. Availability comes from the selected project’s computer.Task defaults or project workflow instructions can contribute context. Read the proposed prompt even when the issue description is already detailed.
4

Send and inspect the conversation

Choose Send message. Kisuke prepares the worktree and conversation, then dispatches the goal.When the dialog closes, use Open agent chat. Check that the intended task is open and look for the accepted goal, the agent’s response, or a pending approval. A closed dialog or visible workspace is not proof that the first response started successfully.
For example, refine a persistence issue’s proposed prompt with:

​
Initialize a project without a first commit

If the selected folder has no repository or no first commit, the dialog offers Initialize Git repository. Read the confirmation and choose Confirm initialization to proceed, or Cancel to leave it alone. Initialization creates a local repository when needed and an empty initial commit so a worktree can be created. It leaves your files uncommitted, including files already staged in an unborn repository. It does not publish a repository or push to GitHub.
An empty initial commit contains no project files. If the task needs files that exist only in your current checkout, prepare the intended starting commit before launching it. Initializing Git alone does not copy those files into the task’s worktree.
The dialog rechecks the repository before enabling branch selection and sending. If Git reports a missing author identity, configure it on the project computer and use Check repository again. Do not repeatedly initialize a folder whose existing Git metadata cannot be read.

​
Follow the work

The issue’s Details, Chat, and Changes views serve different purposes. Details shows the issue properties, workspace, and agent status. Chat contains the instructions, goal, responses, and decisions. Changes lets you inspect the task worktree’s files and Git changes. Keep the task conversation open when switching to Zen if you want its workspace tools alongside the discussion. Check the selected project and branch before using Files, Terminal, or Review; work in the task’s checkout when inspecting its result. Answer permission requests and questions in Chat. A goal does not answer them for you. You can add a follow-up, or use the goal controls to change the objective or pause automatic continuation. One response ending does not necessarily finish the task. While the goal remains active, the agent can continue working. A paused, blocked, or limited goal needs attention; an achieved goal moves the run toward review.
Reopening a task after a process restart can restore its conversation. For a prepared task whose first response never started, or a failed task awaiting recovery, opening Chat can also dispatch work again. Treat that recovery as potentially active execution.

​
Review and finish

Read the final explanation and verify the task’s acceptance criteria. Open Changes, inspect the diff, and run the relevant checks in its workspace. If a project Setup script is configured, confirm its result too: ordinary worktree setup can run separately from the agent’s first response. When the run reaches a completed state, workflow controls can offer Move to review and Mark as done. The chat composer uses Move to done for the latter action. The available destinations depend on the team’s configured or detected workflow columns. Task completion can also move the issue to its review destination automatically. Check the resulting issue status in Linear when handing work to someone else. A local status change is not a guarantee that Linear accepted it. Moving an issue to Done does not itself commit, push, or merge the changes. Use Commit and push and Pull requests when those actions are part of your workflow.
Preserve the work before moving an issue to a completed or cancelled workflow state. When the project computer’s Kisuke daemon starts, it can remove task worktrees in those states, including uncommitted and untracked files. This cleanup also runs with Auto-run off. A Ready for review agent label alone does not trigger it; the issue’s workflow state matters.
Keep any work you need outside the task checkout before cleanup or a fresh start. Preserve commits on a separate branch or in your normal remote workflow, and copy files that are not committed. Starting the task afresh can reset its task branch to the newly selected base, so the task branch alone is not a durable backup of an earlier attempt.

​
Interrupt a task

Choose Interrupt agent in the issue details when that control is available. It requests interruption, pauses an active goal, and cancels a pending task retry. The existing conversation and workspace remain attached so you can inspect the result. Check the conversation afterward. Interruption does not undo file edits, external actions, or necessarily stop every command or service the agent started. If the goal update or connection fails, do not assume the work stopped. To continue, open the same task conversation, resolve the reason for stopping, and use the available goal controls. Resuming the goal can start automatic work again. Interrupting one task is separate from the board’s Auto-run control. It does not disable automatic dispatch of other eligible issues. Conversely, stopping Auto-run does not interrupt agents already working. See Task automation for board scope and scheduling, and Task workflows for repository instructions and hooks.

​
Clear the task workspace

Use Clear task workspace only when you want to discard the attached attempt and start again with fresh choices. Read and confirm the destructive action. Clearing attempts to end the agent session, removes the task worktree, and clears its conversation binding and run counters. Indexed transcript history is archived under the parent project; that history is not a backup of the worktree’s files.
Clearing can permanently delete uncommitted and untracked files. Preserve the work first. Use Interrupt agent when your intent is to stop work while keeping the checkout.
If teardown or file removal takes too long, Kisuke can clear the task’s displayed binding while physical cleanup is still incomplete. Do not treat a reset-looking issue as proof that the old process and folder are gone. Inspect the folder and logs before starting another attempt, especially after a timeout.

​
Recover a failed start

Check that a project is open and its computer is connected. If the issue is Missing from Linear, refresh or restore its availability before starting. See Tasks and Linear.In the start dialog, wait for the selected project’s connection, repository check, and model choices. Sending also requires a nonempty prompt. Use Retry after resolving a connection error.
Review the composer controls against the selected computer’s current catalog. Choose an available model and reasoning level on a harness that supports task goals.If an attached run reports harness-does-not-support-goals, repeated retries with the same harness will not fix it. Interrupt any pending retry. Preserve its files before clearing the attempt to choose a supported harness.
Check the harness and model setup on the project computer. When Kisuke reports this bootstrap failure, it retains the workspace for a retry with the same project.Inspect the task before retrying. If it already has a conversation, opening it may recover and dispatch the goal. A partial workspace associated with another project must be preserved or deliberately cleared before starting elsewhere.
Check the issue for an attached workspace and conversation before trying again. A timeout can mean that the app missed the result, rather than that no worktree was created.For a repository or branch error, inspect Git on the selected computer. If the workspace exists, preserve its files before any cleanup. Avoid repeatedly clearing and recreating it to troubleshoot a connection problem.
Read the error in Details and the conversation. Explicit agent failures can schedule a retry with increasing delays; a quiet or stalled response alone does not trigger the same retry policy.Resolve unavailable credentials, model access, goal support, or project setup before continuing. Use Interrupt agent when a retry is pending and you need work to stop. Reopening a failed task can itself trigger recovery.
Reconnect the issue’s own Linear organization for a Linear-connection error. Restoring another organization does not restore that issue’s access.For a task chat connection error, check the computer and folder that own its worktree. If Files, Terminal, Git, and Chat are all unavailable, follow device connection recovery. Do not choose a different project’s route merely because it is online.