# Tasks

The outcome agents work toward, and the worktree, branch, pull request, reviews and notes that come with it.

Tasks are concrete items of work you want komrad to complete, such as fixing a bug or building a small feature. Agents in komrad work on tasks, and a task keeps its work through every restart or removal of agents.

> This guide assumes you have created a [workflow](https://komrad.dev/latest/guides/workflows.md).

Agents are ephemeral CLIs, so komrad tracks work through tasks instead. The task holds all durable state: the worktree state, the git branch, the pull request for the work, and the reviews from you and other agents.

![The fix-login task holds a writer that edits its worktree and a reviewer that reads it. The worktree's branch becomes the task's pull request.](https://komrad.dev/latest/diagrams/tasks.png)

## Starting a task

Hover the workflow, open the menu with [`space`](https://komrad.dev/latest/config.md#keybindings.menu.open), and pick new task with [`c`](https://komrad.dev/latest/config.md#keybindings.menu.new_agent).

The form is comprehensive, but generally you will only need to write a short brief for the task, outlining what you want to accomplish. Tasks run in worktrees by default, set to the root directory of the workflow.

Komrad gives each task its own slug automatically, such as `fix-login`, and you can rename it. You can also ask the workflow’s orchestrator to spawn tasks on your behalf.

### Stacking tasks

A task can depend on another task, so a large change can go up as a stack of small pull requests. The task it depends on is its parent, and the new task is a child. In a workflow that creates worktrees, pick the parent in the new task form’s Depends on field. The child’s worktree starts from the newest commit of the parent’s branch, and that commit becomes the child’s fork point. The child’s snapshots and line counts measure from its fork point, so they hold only the child’s own work.

Komrad keeps the child on its parent’s newest commit, and on the base branch once the parent merges. It stops and tells the writer when a rebase conflicts, when the parent’s pull request closes without merging, or when it can no longer tell where the child’s own commits begin. The task’s git menu re-targets the child onto the base branch with [`R`](https://komrad.dev/latest/config.md#keybindings.git.rebase_onto_base), or picks a new fork point with [`s`](https://komrad.dev/latest/config.md#keybindings.git.pick_fork_point).

Komrad rebases a stack itself, so an agent never rebases a child by hand.

The review’s sidebar lists every task in the stack. Move the cursor onto one and press [`o`](https://komrad.dev/latest/config.md#keybindings.review_folders.toggle_folder) to open its review.

## Task state

Each task holds a few pieces of state. This state outlives any agents working on it.

### Task notes

Each task stores a short markdown page about where the work stands, covering what was decided, what was tried, and what is left. Agents on the task keep it current as they work, so new agents can pick up where they left off. You can edit the notes yourself, along with the title and goal, with [`E`](https://komrad.dev/latest/config.md#keybindings.menu.edit_row) from the task’s menu.

### Worktrees, PRs and Reviews

A task can get a worktree, which isolates its edits and enables pull request and review workflows. This is the typical pattern for development with komrad.

When the workflow creates worktrees, each task gets one of its own, on a branch named `task/the-task-id`. Komrad generates the task id. Every agent on the task works in that checkout, which isolates tasks from each other.

> Agents spawned into tasks without a worktree will not have isolation between edits. Be careful; these types of tasks should only be used for research tasks, or within projects or directories that don’t use version control.

Tasks set up to run without worktrees work in the workflow’s directory instead.

Komrad syncs pull request information from the task’s worktree branch automatically, such as whether the PR is still open, whether its CI checks pass, and whether it is approved or merged. You can manage the task’s git state from its git menu, and leave local or remote [reviews](https://komrad.dev/latest/guides/reviews.md#shipping-the-work).

## Managing task agents

Every task has one agent that writes in its checkout, which komrad calls the task’s _writer_. The writer starts with the task and stays with it until the task is deleted.

To start the writer on a new conversation, open the task’s menu with [`space`](https://komrad.dev/latest/config.md#keybindings.menu.open) and pick restart with [`o`](https://komrad.dev/latest/config.md#keybindings.menu.restart). The old conversation stays in its transcript.

[Reviewers](https://komrad.dev/latest/guides/agents.md#reviewers) can join the task too, and show up beneath it in italics. They share the task’s checkout and read the change, but they never write to it.

## Archiving

When you finish a task, you can _archive_ it.

Archiving does not delete anything. The task’s worktree stays on disk, and the conversations, notes, reviews and documents stay in the database. Archived tasks move out of the list to the archive, which you reach by pressing [`F`](https://komrad.dev/latest/config.md#keybindings.kinds.focus) and switching from live to archived.

From the archive, restore a task to put it back in the list. Restoring a task brings back only its writer, by design.

## Deletion

Komrad is deliberately pretty conservative in what it deletes.

When you delete a task, komrad will ask what exactly you want to delete. By default, komrad will only delete the task’s worktree from disk.

Be careful: deleting the worktree loses its uncommitted files, and its branch keeps any commits that are on no other branch. If removing the worktree fails, the task stays in the archive with the reason for the failure.

Deleting the worktree frees up space on your machine, without removing the task’s conversations, documents and reviews, which can still be useful later, for looking back retrospectively at why a decision was made, or getting the historical changes into a decision.

Only you can delete a task or a workflow. Komrad refuses the delete when an agent asks for it.
