Guides

opencode

A card appears on your Mac when an opencode session needs you: it asks for permission to run a command, edit a file, fetch a page or use a folder outside the project, it asks you a question, or it goes idle waiting for your next message. The card clears itself when you reply or the session starts working again.

Quickest: add --opencode-plugin --alerts to an invite link's one-liner (or paste the link's agent prompt into opencode; it names the flag):

curl -fsSL <join_url>/install.sh | bash -s -- --yes --opencode-plugin --alerts

Then restart opencode. Reference: integrations/opencode/README.md.

Manual install #

On a sender machine, from a checkout of this repo:

integrations/opencode/install-opencode-plugin.sh    # ~/.config/opencode/plugins/needs-you.js

--uninstall removes it, and so does needs-you uninstall-hooks --opencode, which needs no checkout and no hub (it leaves a symlinked plugin alone). No opencode config file is changed.

Opt in #

NEEDS_YOU_AGENT_ALERTS=1 opencode                            # one session
echo 'NEEDS_YOU_AGENT_ALERTS=1' >> ~/.config/needs-you/env   # every session on this machine

What you'll see #

One card per session, updated in place. Commands, patterns and answers aren't sent. A question's text and choices are on the card: the question (cleaned, anything token-shaped redacted, clamped) in the title, the question and its choices in the body, and the same as the item's question field for the Mac. When the card can show the question whole (1 to 4 questions, each with 1 to 8 options, not a plan approval) you can answer on the card too: click a choice (or your choices, then Send) and the plugin hands your answer to opencode through its own question API, as if you'd picked it in the TUI. The question stays in the TUI the whole time; whichever answer comes first wins, and answering in the TUI stops the wait. The plugin waits up to NEEDS_YOU_ANSWER_TIMEOUT seconds (600 by default; 30 to 3600) and never answers on its own: no click, no answer. Anything else, answer in opencode. NEEDS_YOU_AGENT_QUESTIONS=0 keeps question text off the card (ADR 0009). NEEDS_YOU_AGENT_TURN_CARDS=0 keeps only the permission and question cards.

Tell opencode when to post (optional) #

The hooks cover "opencode is waiting". For the agent to post on its own when it's blocked on you, finished something you're waiting on, or hit something broken, give it the rules the Claude Code skill gives Claude: add --agent-instructions opencode to the invite's one line.

curl -fsSL <join_url>/install.sh | bash -s -- --yes --agent-instructions opencode

It appends a marked block (<!-- needs-you:begin ... --> to <!-- needs-you:end -->) to ~/.config/opencode/AGENTS.md (opencode's global rules; once that file exists, opencode stops falling back to ~/.claude/CLAUDE.md). The file is created if it's missing, backed up before it changes, and never written through a symlink. The text is generated from the skill, so the two say the same. needs-you update keeps the block current, and needs-you uninstall-hooks --instructions takes exactly the block out again (and deletes the file if nothing else is in it). To give opencode the needs-you tools over MCP as well, see MCP server.

Check it works #

needs-you doctor    # the "opencode plugin" line should be OK
echo '{"hook_event_name":"Stop","session_id":"ses_test","cwd":"'"$PWD"'"}' |
  NEEDS_YOU_AGENT_ALERTS=1 ~/.config/opencode/hooks/needs-you-hook.sh notify opencode
echo '{"session_id":"ses_test"}' | NEEDS_YOU_AGENT_ALERTS=1 ~/.config/opencode/hooks/needs-you-hook.sh resolve opencode

No card from a real session? Restart opencode after installing or updating, and check that NEEDS_YOU_AGENT_ALERTS=1 reaches it. NEEDS_YOU_HOOK_LOG=/tmp/ny-hook.log logs each hook call.

This page is docs/guides/opencode.md in the repo. View or edit it on GitHub.