> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whim.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Lifecycle

> Manage task states — pause, resume, complete, archive, and fork.

## Task states

A task's **status** represents its lifecycle position:

| Status        | Description                                                                              |
| ------------- | ---------------------------------------------------------------------------------------- |
| **Active**    | Container is running and the AI agent is available (working, idle, or waiting for input) |
| **Sleeping**  | Paused — container suspended to save compute. All state preserved, ready to resume.      |
| **Completed** | Work finished. Container stopped, branch and changes preserved.                          |
| **Archived**  | Hidden from default view. Container stopped, changes remain in Git.                      |

## Agent states

While a task is **active**, the AI agent has its own state:

| Agent State      | Indicator        | Meaning                                        |
| ---------------- | ---------------- | ---------------------------------------------- |
| **WORKING**      | Spinning         | Actively reading, writing, or running commands |
| **IDLE**         | Paused           | Finished current work, waiting                 |
| **NEEDS\_INPUT** | Attention needed | Asking a question or waiting for your response |
| **STOPPED**      | Stopped          | Agent process has exited                       |

<Tip>
  When a task shows **NEEDS\_INPUT**, click into its terminal to read the agent's question and respond. An unread indicator also appears on the task in the sidebar.
</Tip>

## State transitions

```mermaid theme={null}
stateDiagram-v2
    [*] --> Active: Launch task
    Active --> Sleeping: Pause / Auto-sleep
    Sleeping --> Active: Resume
    Active --> Completed: Complete
    Sleeping --> Completed: Complete
    Completed --> Active: Resume
    Active --> Archived: Archive
    Sleeping --> Archived: Archive
    Completed --> Archived: Archive
```

## Pausing and resuming

### Pausing (sleep)

Pausing **suspends the container**, preserving the filesystem, running processes, and agent session. This saves compute units while keeping the task ready to resume.

Pause a task via the **pause button** in the task header or the task's context menu.

<Info>
  **Auto-sleep**: Whim automatically pauses idle tasks after a configurable timeout (set per-workspace in Settings). This prevents forgotten tasks from consuming compute.
</Info>

### Resuming

Resume a sleeping task to restart its container and restore the agent session. The agent picks up where it left off.

* Click the **resume button** on a sleeping task
* Optionally send a new prompt as part of resuming
* Resuming a **completed** task also works — it restarts the container so you can continue on the same branch

## Completing tasks

Mark a task as completed when you're satisfied with its work — via the **complete button** in the task header or the context menu. Completing stops the container and frees compute. The task's Git branch and changes are preserved.

Tasks can also **complete automatically** when the AI agent finishes and exits, or when the agent determines it has fulfilled the prompt.

### Cascading completion

When you complete a parent task with active children, Whim prompts you to confirm whether to also complete the children. This prevents orphaned subtasks from running.

## Archiving

Archiving moves a task out of your active workspace view. Archived tasks have their containers stopped but retain their Git branches and code changes. Archive tasks you no longer need to keep your workspace focused.

## Forking tasks

Forking creates a **new task from an existing one**, carrying forward code and optionally conversation context. It's useful for exploring alternative directions, continuing previous work, or branching off from a good checkpoint.

When you fork, Whim creates a new Git branch from the source task's branch — including any uncommitted changes via a code snapshot. The original task is untouched.

### Session mode

Copies the **full AI conversation** from the source task. The agent in the forked task has the complete history — every file it read, decision it made, command it ran. Your prompt becomes a follow-up message in the existing conversation.

Use session mode to:

* Continue exactly where a task left off
* Give follow-up instructions that build on all previous context
* Explore a "what if" from a specific point in the conversation

<Warning>
  Session mode requires the source task to be **actively running**. If it's sleeping or completed, resume it first or use summary mode.
</Warning>

### Summary mode

Starts a **fresh session** with a new prompt. The agent does not inherit conversation history — you provide whatever context is relevant. Your prompt is the starting prompt for a new conversation.

Use summary mode to:

* Take a different approach to the same problem
* Start clean on the same codebase state
* Provide curated context instead of carrying forward full history

### What carries forward

|                                        | Session mode           | Summary mode           |
| -------------------------------------- | ---------------------- | ---------------------- |
| Code changes (committed + uncommitted) | Yes                    | Yes                    |
| Git branch state                       | New branch from source | New branch from source |
| AI conversation history                | Full session           | No                     |
| Task settings (provider, model)        | Inherited              | Inherited              |
| File attachments                       | No                     | No                     |

<Info>
  Code snapshots ensure that even uncommitted work-in-progress is preserved in the fork. You don't need to commit before forking. Forks can be nested up to **3 levels deep**.
</Info>

## Unread indicators

Whim tracks whether you've seen the latest activity on each task:

* Tasks with new agent output show an **unread dot** in the sidebar
* Tasks in the **NEEDS\_INPUT** state are highlighted for attention
* Opening a task's terminal marks it as read