Skip to content

Take over a session

Use this procedure in Claude Code, Codex or another interactive MCP client. Coding runs started with scripts/heyaira-run.sh follow their brief instead; they do not claim tasks or update status. Write durable fields in the project's working language and speak to the owner in the language they use.

  1. Identity and rules. Call server_identity on the intended project's connection and compare resource, instance and project with the supplied connection profile. Stop on a mismatch; never guess or copy a different connection's identity. Call session_start, then continuity_context, read-only. Read the project's repository instructions and applicable work contract. Use the pinned profile in every write_context.
  2. Task and version. Given handoff: <id-prefix> v<version>, find the full UUID with task_list (in_progress, blocked, then todo); never choose an ambiguous match. Call task_get for the current task. If its version is higher than the handoff line, also read that historical version and report that changes were saved since the handoff. Use the latest version for writes.
  3. Read just enough. Read handoff_completed, handoff_next, handoff_blockers, the latest receipt and the decisions or notes it names. Check the named repository, branch, worktree and commit with Git, including git status --short --branch. Preserve unrelated work. Read only what the first next step needs; do not reconstruct the entire history.
  4. Confirm takeover. When the work contract permits taking over, call task_update with expected_version from the latest task_get and matching write_context. Set handoff_completed to its entire current text plus one line Taken over by session <session-reference>. The field is replaced, not appended server-side: sending only the line erases earlier work. Use the client's session ID or a stable session label; do not invent a native ID. On version_conflict, re-read, reconcile ownership and append once, without overwriting another session. Read back with task_get to confirm.
  5. Messages in flight. Take over any available messages sent after the handoff, incorporate them into the next steps and tell their senders where the work continues when messaging is available and authorized. Keep project decisions in HeyAira; never store conversation history there. If the client cannot retrieve messages, report that limitation and proceed from the task.
  6. Report and act. Briefly name the task, its current state and the first step. Report any client session actions actually performed or unavailable. Take the first authorized step; request only a required decision or approval.

If the client has session-management tools (for example Claude Desktop), read the previous session's last approximately 20 events before archiving, and identify messages that arrived after the saved handoff. Obtain its ID from Previous session: <id> in handoff_next (legacy Poprzednia sesja: is also accepted). Archive it only after takeover and only if it is no longer working; if the ID is missing or it remains active, report this and leave it alone. After successful archival, read its title and give this session that title so messages by name reach the successor. Do not duplicate the name of an active session. Include this session's actual ID in the report. Tools such as list_events, archive_session, get_session and set_session_title are optional client capabilities; their absence does not block the MCP takeover. A predecessor's background jobs (keep-awake, waits) block its archival: start your own first, then stop the predecessor's and archive it.

While you work: waiting and handing over

  • Wait with one command. Where HeyAira Bridge is installed, run in the background heyaira-bridge work-center tasks --counter unattended --wait --timeout 90 (a coordinator watches every project; another session adds --assignment-id <its assignment>). It prints the tasks whose handed-over move nobody took for 15 minutes, or whose due_at passed with no task write, with next_after and exits 0; it exits 3 at the timeout and 4 on a lasting error. Re-arm it after every exit, or you stop watching: after 0, act on each task and re-run with --after <next_after> (never a wall-clock time) so handled moves do not wake you again; after 3, re-run with the same --after; after 4, read the error, fix or report it, then re-run. Do not write session-local watchers over Bridge files or task lists; they stop at handoff and differ per session. Bridge workflows have their own stall alerts.
  • Hand over a move explicitly. When a task without a Bridge workflow waits for another session, call task_stage_set with next_actor_override_assignment_id (that session's assignment) and waiting_reason (what it must do). A message alone is invisible to the server; the override is what the unattended rule and the owner's alert measure. The recipient takes the move by writing the task (for example a review verdict in the handoff) or claiming it; clear the override when the move returns.
  • Schedule a check in due_at. A scheduled check belongs in due_at on the task (set with task_update or task_stage_set), not as text in the handoff, so the server wakes the coordinator if it is missed.

Sources