* 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>
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:
- You are working at your desk with Claude Code or OpenCode open in the terminal.
- You need to step away but want to keep supervising the agent.
- You run
openacp integrate(or trigger the/openacp:handoffslash command from inside the agent). - The session appears as a new topic in your Telegram group or Discord server.
- 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.
jqis required only for hook-based integrations (Claude/Cursor/Gemini/Cline). OpenCode plugin integration does not requirejq.
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) — callsopenacp 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 callopenacp 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.