OpenACP/docs/gitbook/features/session-handoff.md
hightman 6f77aed353
feat(integrate): add OpenCode session handoff integration (#205)
* feat(integrate): add opencode handoff plugin strategy

Add a plugin-based integration path so OpenCode can hand off sessions bidirectionally while preserving the existing hooks flow for other agents. This enables /openacp:handoff in OpenCode and avoids jq requirements for that integration.

Co-authored-by: Codex <noreply@openai.com>

* fix(integrate): address PR review for opencode strategy

Make integration strategy discriminated and exhaustive, harden OpenCode injected text part shape, and improve plugin install/uninstall idempotency and messaging. Add regression tests for reinstall and empty uninstall paths.
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: 0xmrpeter <0xmrpeter@gmail.com>

---------

Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: 0xmrpeter <0xmrpeter@gmail.com>
2026-04-05 10:07:19 +07:00

3.3 KiB

Session Handoff

What it is

Session handoff lets you transfer a running agent session from your terminal to your phone (or any other device with Telegram or Discord), or in the other direction. You start a session in the terminal, realize you want to continue the conversation on the go, and hand it off to your messaging app with a single command.

No state is lost. The agent process keeps running; only the "owner" of the session changes from the terminal to the chat interface.


Use case: terminal to phone

A typical flow:

  1. You are working at your desk with Claude Code or OpenCode open in the terminal.
  2. You need to step away but want to keep supervising the agent.
  3. You run openacp integrate (or trigger the /openacp:handoff slash command from inside the agent).
  4. The session appears as a new topic in your Telegram group or Discord server.
  5. You continue sending prompts and approving permission requests from your phone.

How to set up handoff

Step 1: Install the integration

Run the integrate command and follow the prompts:

openacp integrate

You will be asked which agent to integrate (Claude Code, OpenCode, Cursor, Gemini CLI, GitHub Copilot, Cline, Codex, etc.). The command installs the needed integration so your agent can hand off sessions to OpenACP.

To uninstall later:

openacp integrate --uninstall

Step 2: Use the handoff command

Once integrated, you can hand off any session from your terminal to your messaging app:

/openacp:handoff              # hand off to the default platform
/openacp:handoff telegram     # hand off specifically to Telegram
/openacp:handoff discord      # hand off to Discord

The session appears as a new topic in your Telegram group or Discord server. You can continue sending prompts and approving permission requests from your phone.


Requirements

  • The OpenACP daemon must be running (openacp start) on the same machine as the terminal agent.
  • At least one messaging adapter (Telegram, Discord, or Slack) must be configured and connected.
  • jq is required only for hook-based integrations (Claude/Cursor/Gemini/Cline). OpenCode plugin integration does not require jq.

Supported agents

Currently supported agents include Claude Code, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, Cline, OpenAI Codex, and others. Run openacp integrate --list to see the full list.


Technical details

Most handoff integrations rely on two shell scripts installed by openacp integrate:

  • Inject hook (openacp-inject-session.sh) — runs as an agent hook on every conversation turn, reads the agent's session ID from the hook payload, and injects it as a context variable.
  • Handoff script (openacp-handoff.sh) — calls openacp adopt <agent> <session_id> to register the terminal session with the running OpenACP daemon, making it visible in the messaging platform.

For OpenCode, handoff is installed via a command + plugin pair under ~/.config/opencode/:

  • Command (commands/openacp-handoff.md) — provides /openacp:handoff.
  • Plugin (plugins/openacp-handoff.js) — injects current OpenCode session ID so the command can call openacp adopt opencode <session_id>.

If OpenCode is started with --pure, plugins are disabled and session ID injection is unavailable. In this mode, /openacp:handoff is not supported.