opencode-humanlayer

An OpenCode v2 plugin that mirrors your opencode sessions to HumanLayer, so they show in the web app beside your other sessions, and lets you reply to them and stop them from there. It needs OpenCode 2 (@opencode/cli); it does not load in OpenCode 1. It does what the pi extension does, from the same shared packages.

You need OpenCode 2 (opencode --version shows 2.x) with a model set up, and git.

opencode plugin add git+https://github.com/humanlayer/humanlayer-opencode.git

This adds the plugin to ~/.config/opencode/opencode.json under "plugins". Then, in a git repo:

1. Run opencode, then /humanlayer login. Approve the code in the browser, and pick an organization if you have more than one. Add beta, dev or local for another environment, for example /humanlayer login beta.
2. Send a prompt. The footer shows HumanLayer: <task>, and /humanlayer open-session opens the session in the web app.

OpenCode 2 runs a shared background server by default, and the plugin's server half runs in it, with that server's environment. If you set a HUMANLAYER_* variable in your shell, run opencode --standalone, or restart the server from that shell with opencode service restart.

Headless, sign in with humanlayer-opencode login [channel] (also status and logout), or set HUMANLAYER_PAT.

To update, run opencode plugin update, then restart opencode (opencode service restart restarts the background server). To remove, run opencode plugin remove git+https://github.com/humanlayer/humanlayer-opencode.git.

If opencode stops at "Starting background server...", another process holds the server's port. Pick another with opencode service set port <port>, or run opencode --standalone.

The source lives in apps/riptide-opencode-plugin in humanlayer/synclayer. humanlayer/humanlayer-opencode holds a build of it: bun run build writes dist/, with the server half bundled into index.js along with the @humanlayer/session-sdk-* packages, the TUI half as source (tui.tsx, which opencode compiles), HumanLayer's skills, and cli.js. scripts/publish.sh [--dry-run] builds, replaces that repo's files with the build, commits Sync from humanlayer/synclayer@<sha> and pushes to main. It refuses while the plugin, the pi skills or packages/ have uncommitted changes.

OpenCode also loads any folder under .opencode/plugins/ in a project, or ~/.config/opencode/plugins/, with its server half in index.ts and its TUI half in tui.tsx. Two one-line files point at this repo, after bun install:

mkdir -p .opencode/plugins/humanlayer
echo "export { default } from '/path/to/humanlayer/apps/riptide-opencode-plugin/src/index.ts'" > .opencode/plugins/humanlayer/index.ts
echo "export { default } from '/path/to/humanlayer/apps/riptide-opencode-plugin/src/tui.tsx'" > .opencode/plugins/humanlayer/tui.tsx

• Sessions. The first prompt of an opencode session starts a HumanLayer session. The plugin sends the prompts, replies, thinking, tool calls and their results, your own shell commands, compactions, token use and cost, and the status: running, waiting for input, interrupted or failed. Subagent sessions show as the Task call in their parent.
• Which task. In order: the target of /humanlayer attach, then HUMANLAYER_TASK, then the worktree's own task (exactly one .humanlayer/tasks/<slug> link into a task's files that this plugin did not make, as in a HumanLayer worktree), else a new task named opencode-<id>.
• Task files. Every model request names the task folder, .humanlayer/tasks/<slug>, in the system prompt. The folder links to the task's files in ~/.humanlayer/riptide/artifacts/, and files the agent writes there sync to the task. Once the session is linked, the same section gives its web app link, so the agent can open it when asked.
• The task diff. For a task the session made, the working tree against HEAD at the first prompt, rebuilt after each write, edit and shell command. .env files and .humanlayer/ stay out.
• Web replies and stops. A message sent from the web app runs in opencode, or waits behind the running turn. /compact compacts, a skill's name runs that skill, and an opencode command's name runs that command. The stop button interrupts the run. A message or stop sent while opencode was closed runs when it next opens in that folder.
• Approvals. A tool opencode asks about (set to "ask" in its permission config) shows Approve and Deny on its card in the web app, and the session reads needs approval. Answer in either place: a web answer goes to opencode, with a denial's comment, and an answer in opencode clears the web card.
• Titles. opencode's title for a session names the HumanLayer session, and the task too when the session made it.
• Tools. get_artifact_comments, update_artifact_comments, reply_to_artifact_comment, get_diff_comments, reply_to_diff_comment, update_diff_comments and library_researcher. Calls in one session run one at a time, in order, since a reply reopens a thread that a resolve in the same turn closed.
• Skills. HumanLayer's skills (@create-research, @create-tech-design, @show-me and the rest; the pi extension's copy). The web composer offers the session's skills and commands after /.
• Host status. While signed in, the host beats every 15 s, so the web app shows it online and its composer works. The web app cannot start an opencode session.
• When opencode continues a session (opencode -c, -s), the plugin keeps sending to the same HumanLayer session.

/humanlayer with nothing after it opens a menu of these:

The plugin keeps its logins, host id and session links in ~/.humanlayer/riptide/opencode/, apart from pi's. Its log is logs/opencode-humanlayer.log there: one line per call to HumanLayer and its result, never a token or a message.

bun run check    # typecheck, then node --test

The tests run the real server half in a fake opencode (test/helpers/opencode.ts) against the pi extension's mock cloud and diff streams, so they need no network or model.

Login and tokens, the outbox, the prepare body and task picking, the task folder and its sync, the task diff, and the HumanLayer tools come from the @humanlayer/session-sdk-* packages in packages/, which the pi extension and riptide-daemon use too.