Appearance
Send work and handoffs
Send work hands one session's state to another agent, so it can continue without you re-explaining the task. It is the first, single-user form of a Workstate handoff.
Open the overlay (⌘⇧Space), click a session, and choose Send work…. The menu reads Continue this work in, followed by the targets below.
What gets sent: the handoff bundle
Vistara builds a HandoffBundle from facts it already holds: the session's Workstate, its checks, its transcript and Relay's record of confirmed decisions. Fields it does not know are left out rather than guessed.
| Field | Content | Where it comes from |
|---|---|---|
id | A short id such as ho_3f9a1c2b7d4e. | Hash of the source session and the time. |
title | The session's own title. | The agent's name for the conversation. |
objective | What you asked the agent, up to 400 characters. | The prompt that opened the current turn. |
current | Where the agent is now, up to 900 characters. | The agent's last message, or the Workstate's last change. |
decisions | Up to 8 confirmed decisions. | Relay's record for this work item. |
blocker | What it is blocked on, if anything. | Workstate v0 (for example, a check that failed twice). |
next | The next step. | Workstate v0. Left out when the next step is "answer a question". |
files | Up to 15 files the agent edited or wrote. | Edit and Write tool calls in the transcript. |
checks | Tests and build: pass, fail, with a short summary. | Workstate v0. Left out when both are unknown. |
recentActivity | The last 10 tool calls, one line each. | The transcript. |
project, branch | The working folder and git branch. | The session inventory. |
provenance | Source agent, source session id, workstream id, folder, time created. | Vistara. |
The receiving agent reads it as plain text. A rendered handoff looks like this:
text
WORK: Fix CSV export for large tenants
Continue this work, handed over from Codex through Vistara. Start by checking the current state (git status, the files below), then carry on with the next step. Ask me if something is unclear.
Objective
Fix the CSV export so tenants with more than 10k rows don't time out
Current
Streaming writer is in place; the old buffered path is still used by the admin route.
Decisions
- Keep the v1 route; add a version header instead of /v2
Next
Review and ship
Files
- src/export/csv.ts
- src/routes/admin.ts
Checks
tests ✓ · build ✓ (84 passed)
Recent activity
- Edit src/export/csv.ts
- Bash pnpm test
Source
Codex session 019a… · acme/api · fix/csv-streamTargets
| Target | What happens | Notes |
|---|---|---|
| A running Claude session | Vistara writes the handoff to that session's inbox socket, with "(Sent by the user from Vistara.)" at the end. The session continues from it. | Any live Claude Code session on this Mac, in any tab. The menu lists up to four, sessions on the same project first. |
| Claude Code (new session) | Vistara saves the handoff to ~/.vistara/handoffs/<id>.md and prepares claude "$(cat <that file>)" in the source session's folder. | If Warp is installed, Vistara opens a new Warp tab in that folder and puts the command on your clipboard; press ⌘V, then Enter. Warp cannot be told to run a command from outside. Without Warp, Vistara opens a Terminal window that runs it. |
| Codex (new session) | The same, with codex instead of claude. | |
| Copy handoff | The rendered handoff goes to your clipboard. | Paste it into any agent, a chat, or a message to a colleague. |
Sending to Cursor or another teammate is not available; the menu shows teammates as coming with Vistara teams.
How a handoff is tracked
Each handoff is recorded in the local events log (~/.vistara-relay/events/) as handoff_created. When the receiving session is known, Vistara records handoff_accepted:
- for a running Claude session, at once;
- for a new session, when a session of the same agent starts in the same folder within 10 minutes of the handoff.
Nothing about a handoff leaves your Mac.
Examples
Context is running out. A Claude session has been on a refactor for two hours and its context is nearly full. Send work → Claude Code (new session). The new session starts with the objective, the files changed, the last check result and the next step.
Switch agents. Codex wrote a migration and its tests pass, but you want Claude to review it. Send work → a running Claude session that is already open on the same repo.
Ask a colleague. Send work → Copy handoff, then paste it into Slack. Your colleague's agent can start from the same text.
From single-user handoffs to team handoffs
Today a handoff is text that moves between agents on one Mac, or to anyone by copy and paste. The whitepaper describes a fuller handoff: the transfer of a complete Workstate and the artifacts it points to, received by a teammate's daemon, which continues from the next action under the teammate's own mandate.
Planned for teams:
- Presence: see which workstreams your teammates have running and which are blocked.
- Handoffs: send a workstream to a teammate's Vistara, with decisions, files and checks, and see it marked as received.
- Questions: route a decision to the person who owns it.
- Verified results: share check results with the people who depend on the work.
Team features share state and results. They are not remote control: a teammate cannot run commands on your machine or answer your agents' approvals.
The HandoffBundle is transport-independent by design, so the same bundle can later travel to a teammate's Vistara. Encrypted, per-workstream sharing, in which fields can be withheld, is part of the whitepaper's design (Section 6) and is Planned.