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

# Sessions that move

> One Kana session can move between machines, coding agents, and teammates turn by turn, and keep its whole history.

A Kana session isn't tied to one computer, one coding agent, or one person. Each **turn** (a message and the work Kana does for it) can run somewhere new:

* **On another machine.** Switch between cloud and local in any direction: cloud to local, local to cloud, one cloud machine to another, or one of your computers to another.
* **On another runtime.** Start in Claude Code, continue in Codex, and finish in any other [runtime](/machines/runtimes). Model and effort can change too.
* **For another person.** Anyone in your company can open the workspace chat and take the next turn, or queue a message for when the current turn finishes. Their turn runs on their own machine, with their own runtime and sign-ins.

The conversation, the code, and the plan follow the session. You don't start over, and you don't copy context by hand.

## A session in motion

Aiko starts a session on her laptop. When she shuts the laptop, she moves the session to her cloud machine and switches to Codex. Her teammate Ben queues a follow-up and later picks the session up on his own desktop and then his cloud machine. Every turn adds to the same history.

```mermaid theme={null}
%%{init: {"theme":"base","themeVariables":{"fontFamily":"Inter, ui-sans-serif, system-ui, sans-serif","fontSize":"16px","primaryColor":"#FFF1E0","primaryBorderColor":"#A94604","primaryTextColor":"#3B1A02","secondaryColor":"#FFE4C2","tertiaryColor":"#FFF8F0","lineColor":"#A94604","clusterBkg":"#FFF8F0","clusterBorder":"#E8B98A","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#FFE4C2","noteBorderColor":"#E8B98A","noteTextColor":"#3B1A02","actorBkg":"#FFF1E0","actorBorder":"#A94604","actorTextColor":"#3B1A02","signalColor":"#A94604","signalTextColor":"#3B1A02"}}}%%
sequenceDiagram
  participant AL as Aiko's laptop (local)
  participant AC as Aiko's cloud machine
  participant S as Kana session (history, plan, checkpoints)
  participant BL as Ben's desktop (local)
  participant BC as Ben's cloud machine

  Note over AL,S: Turn 1 · Aiko · Claude Code
  S->>AL: Run the turn
  AL-->>S: Reply
  Note over AC,S: Turn 2 · Aiko · Codex, moved to the cloud
  S->>AC: Wake, restore the checkpoint, replay history
  AC-->>S: Reply
  Note over S,BL: Turn 3 · Ben · Copilot CLI, queued while turn 2 ran
  S->>BL: Restore the checkpoint, replay history
  BL-->>S: Reply
  Note over S,BC: Turn 4 · Ben · Claude Code, back in the cloud
  S->>BC: Wake, restore the checkpoint, replay history
  BC-->>S: Reply
  Note over AL,S: Turn 5 · Aiko · Codex, back on her laptop
  S->>AL: Fetch the latest checkpoint, replay history
  AL-->>S: Reply
```

All five turns are one conversation. Kanaeru records who sent each message and which runtime, model, and machine answered it.

## Moving to another machine

Pick a different machine in the agent picker and send, or pass `--machine` to [`kana conv send`](/cli/reference). Before the new machine starts work, Kana:

1. Asks the machine that ran the last turn to commit and push its work to a checkpoint ref in your repository's own `origin`. A sleeping cloud machine is woken for this.
2. Wakes the new machine if it's an asleep cloud machine. It then fetches that checkpoint and sets up the same task worktrees.
3. Stops the old runtime and starts the session on the new machine with the conversation so far.
4. Tells the agent it has moved, so it re-checks its branches, tools, and environment before carrying on.

Task worktrees, where Kana builds each task, are also checkpointed after every completed turn and when the machine shuts down. A task's latest work is usually in your repository before you ever switch. Other sessions, such as planning or vision, push their work only when you move them.

### When the previous machine is off

A sleeping cloud machine is woken automatically. A local computer that's switched off or offline can't be woken. Kana shows a confirmation card and asks before continuing without it:

| What you get | When |
| - | - |
| **Everything** | The previous machine answered and pushed its current work |
| **The last checkpoint** | The previous machine is unreachable, but its last checkpoint or pushed branch is in your repository. Work it never pushed doesn't come along |
| **Conversation only** | Nothing for the session was ever pushed. The conversation, plan, and blueprints come along, but no code |

Nothing is deleted from a machine that didn't take part in the move. Unpushed work stays there for you to recover. If you later move the session back to that machine and its copy has drifted from the session's newer work, the move is refused until you reconcile or clean up that copy. If any repository didn't come along, you'll see a notice naming it. The agent is told too, so it checks the real state of each repository before continuing. From the CLI, `--accept-degraded-handoff` gives the same consent.

## Switching runtimes

Choose another runtime, model, or effort level in the agent picker before you send, or pass `--runtime`. The session keeps its history:

* **Same runtime, same machine:** the runtime resumes its own conversation where it left off.
* **New runtime, model, or machine:** Kanaeru replays the session to it from its saved history. The agent gets the most recent 40 messages word for word and a summary of everything older, and can page through the rest with Kanaeru's tools. Each message is labelled with who sent it and what produced it.

Every runtime gets the same harness of skills, rules, and hooks, plus the same plan and blueprints from Kanaeru, so it carries on with the same process. See [Session plugins](/machines/session-plugins).

## Working on a session together

Anyone in your company can open a workspace's chat and take part in its sessions.

* **Take the next turn.** Send a message once the current turn finishes. Your turn runs on one of **your** machines, with your runtime and your provider sign-ins. If the session last ran on a teammate's machine, Kana moves it to yours as described above.
* **Queue a message** while a turn is running. Everyone in the conversation sees the queue, and it's kept even if you close the tab. Messages go out oldest first when the turn ends. Your messages in a row go together as one turn. A teammate's message starts its own turn on their machine. Only the person who queued a message can edit or remove it. A session holds up to 50 queued messages.

<Note>
  You can only run turns on your own machines. Every machine belongs to one person, so you can't send a turn to a teammate's laptop or cloud machine, and your messages never run with their credentials. Your provider keys and sign-ins stay on your machines.
</Note>

A session runs one turn at a time and keeps a single history. It never splits into parallel copies, so everyone sees the same conversation and the same code.

## What travels with a session

| | Where it's kept | On the next machine or runtime |
| - | - | - |
| **Conversation** | Kanaeru | Recent messages are replayed word for word, and older ones are summarized |
| **Code and repository changes** | A checkpoint ref in your repository, `refs/kanaeru/checkpoints/<session>/<repo>` | Fetched and checked against the commit the previous machine reported |
| **Plan, blueprints, pipeline state, memory** | Kanaeru | Read from Kanaeru, the same on every machine |
| **Harness** | Each machine's Agent Manager | Installed with the Agent Manager. Every runtime gets the same skills, rules, and hooks |
| **Credentials** | The machine of the person running the turn | Never copied. Each turn uses its own machine's sign-ins |

Checkpoints refuse to include secrets such as `.env` files, private keys, or credential files. If a checkpoint would include one, it fails and tells you why.

<Tip>
  Both machines need a recent Agent Manager to move a session. If one is too old, Kana refuses the move and tells you which one. [Upgrade](/machines/connect-a-machine#upgrade) it and send again.
</Tip>


## Related topics

- [Runtimes](/machines/runtimes.md)
- [Kanaeru overview](/index.md)
- [Connect a machine](/machines/connect-a-machine.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.