Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

opencode-ai-setup — Team Onboarding

One-command installer that brings every dev’s laptop to the same OpenCode environment. Lives at hungryhub-team/opencode-ai-setup.

Why this exists

Every dev on the team uses OpenCode as the AI coding agent — but a working OpenCode environment needs more than just the binary. It needs the shared LiteLLM proxy (centralized quota pool), the superpowers methodology plugin, the caveman token-saver, the hh-session-init skill, and (optionally) graphify for knowledge-graph queries and the shared agent-skills repo for our internal TDD / verify-PR / migration helpers.

Manually installing and configuring all of that takes ~20 minutes and drifts between machines. opencode-ai-setup makes it one command.

What it does

Running setup.sh:

  1. Installs the opencode binary via the official installer if it’s not already on PATH (curl -fsSL https://opencode.ai/install | bash).
  2. Checks that npx is available (Node.js prerequisite).
  3. Prompts for your LiteLLM API key (input masked; skipped if a key is already saved). DM @saiqulhaq on Slack if you don’t have one.
  4. Backs up any existing ~/.config/opencode/opencode.json.
  5. Writes the config with the LiteLLM provider + superpowers plugin entry. All MiniMax models (M2, M2.1, M2.5, M2.7, M3, …) are wired in.
  6. Installs superpowers into the OpenCode config dir (bun add / npm install --prefix) — OpenCode 1.17.x does not auto-install plugins on startup.
  7. Installs caveman globally via npx -y github:JuliusBrussee/caveman.
  8. Optionally installs graphify (Python knowledge-graph skill, ~71.5× fewer tokens on graph queries) when you answer Y to the prompt.
  9. Installs the hh-session-init skill — asks which superpowers modes and caveman terse-mode to activate at the start of each session.
  10. Patches ~/.config/opencode/AGENTS.md with the session-init trigger (idempotent — safe to re-run).
  11. Optionally installs shared agent skills from the private hungryhub-team/agent-skills repo — lists them and lets you pick which to copy into ~/.config/opencode/skills/. Skipped gracefully if gh isn’t authenticated and git can’t reach GitHub.

Run it

One-liner (requires gh authenticated to hungryhub-team)

gh repo clone hungryhub-team/opencode-ai-setup /tmp/opencode-ai-setup -- --depth 1 && bash /tmp/opencode-ai-setup/setup.sh

From a local clone

git clone git@github.com:hungryhub-team/opencode-ai-setup.git
cd opencode-ai-setup
bash setup.sh

The script is idempotent — running it again reuses your existing API key, backs up the current config, and skips already-installed plugins.

After setup

  1. Run opencode in your terminal.
  2. Open the model picker and pick LiteLLM as the provider.
  3. Choose any MiniMax model (default to M2.7 for typing, switch to M3 via /models for reasoning-heavy tasks — see Agentic Coding with OpenCode + MiniMax).
  4. Verify plugins loaded: ask OpenCode "Tell me about your superpowers" — it should describe the superpowers methodology.

Updating your API key

Keys are rotated periodically. To enter a new one without re-running the full setup:

bash setup.sh          # re-run; you'll be asked whether to keep or replace the existing key

Or use OpenCode’s built-in UI:

  1. Type /connect and press Enter.
  2. Search for LiteLLM and select it.
  3. Enter the new key.

Both paths back up your existing config automatically.

Troubleshooting

Plugin doesn’t load

Run a one-off prompt and inspect plugin logs:

opencode run --print-logs "hello" 2>&1 | grep -i "superpowers\|caveman"

The most common cause is the OpenCode config dir’s node_modules/ being missing — re-running setup.sh reinstalls superpowers into it.

agent-skills step silently skipped

That step needs GitHub access to the private hungryhub-team/agent-skills repo. If you see no skill list:

gh auth status          # is gh authenticated to hungryhub-team?
gh auth login --web     # if not

Re-run setup.sh after authenticating.

OpenCode binary missing after install

The official installer puts opencode in ~/.local/bin/ (Linux) or ~/.opencode/bin/ (macOS). Open a fresh shell so PATH updates, or add it manually:

export PATH="$HOME/.local/bin:$PATH"            # Linux
export PATH="$HOME/.opencode/bin:$PATH"         # macOS