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

# Hand work between local and cloud

> Send your current branch and a brief to a cloud agent, then continue locally from the result.

Handoff lets you leave a task with a cloud agent while you step away or work on something else. Your local agent pushes the current work and explains the goal, what is done, what remains, and what still needs checking.

The local and cloud chats stay linked. The cloud task has its own environment and can keep working after your computer is off.

## Send local work to the cloud

You need a local Git project with GitHub remotes, permission to push its branches, and a cloud workspace with access to every project repository. If that workspace isn't connected yet, Twill shows a setup card in the chat.

<Steps>
  <Step title="Choose Handoff">
    In the local task header, select **Handoff**. For the first handoff, choose
    the cloud agent and model in the confirmation dialog. You can also ask the
    local agent to delegate the work in a message.
  </Step>

  <Step title="Let the local agent prepare the work">
    Confirming stops the current run and puts the handoff request first in the
    queue. The local agent commits and pushes the current state, then sends a
    brief to the cloud agent. It skips pre-handoff tests and reviews so the
    cloud agent can pick those up.

    If several cloud workspaces match your repositories, the agent asks which
    one to use. If access is missing, follow the setup card, return to the chat,
    and ask the agent to retry.
  </Step>

  <Step title="Wait for the cloud task to start">
    Keep your computer connected until the cloud task card appears and its run
    starts. Open the card to follow progress. Cloud work uses the destination
    workspace's credits or configured provider keys.

    The local chat remains available. New local edits aren't continuously
    synced to the cloud task.
  </Step>
</Steps>

## Bring the result back locally

On the cloud task, choose **Continue locally**. Add an optional note about what to do next, or choose **Skip and continue**.

* **If the task started locally**, Twill returns to the original local chat. The agent receives the current pushed branches and PR states, fetches the work, and continues there.
* **If the task started in the cloud**, choose a matching local project. Twill creates a linked local chat in a new worktree and includes the cloud conversation with the branch and PR information. The original project checkout stays in place. In Desktop, **Add project** lets you connect a matching folder first.

Keep the destination computer connected. If its agent is already working, the continuation queues behind that run. A newly created local continuation uses **Approve for me**; you can change permissions for later turns.

<Note>
  **Continue locally** brings back pushed Git work. Uncommitted or unpushed
  changes in the cloud checkout aren't included. Ask the cloud agent to commit
  and push anything you want to continue locally first.
</Note>

## Hand off again

Using **Handoff** again in the same local chat continues its existing cloud task. The cloud agent receives a new brief with the latest pushed commits, and incorporates them into its existing checkout and PRs. Its workspace, agent, and model stay the same.

If the cloud agent is busy, the handoff queues behind that run. Restore an archived cloud task before handing off to it again.

## What carries over

| Carries over                                 | Stays with the environment                 |
| -------------------------------------------- | ------------------------------------------ |
| Pushed branches and commits                  | Running servers and processes              |
| The handoff brief and links between chats    | Local databases and installed dependencies |
| Branch and PR information on the return trip | Native agent logins and local credentials  |

A cloud agent receives a brief of the local work, not a copy of the local agent's native session. For a cloud task continuing in a new local chat, Twill also supplies the cloud conversation. Set up cloud dependencies and secrets through the [cloud environment guide](/environment); handoff doesn't reproduce your laptop automatically.