Quiper

Appearance

Setting Up OpenCode ​

← All engines

This guide takes you from wherever you are right now to a working OpenCode inside Quiper — no prior setup assumed. The goal is simple: after you follow these steps, OpenCode works. It covers the full path, from installing Quiper (if you don't have it) to installing OpenCode and starting its local web server (if you haven't) to opening it inside the overlay.

NOTE

OpenCode is an open-source AI coding agent that runs on your own machine (opencode.ai). Quiper embeds its local web interface. OpenCode needs a configured model provider to answer, and its server must be running for the engine tab to load. This guide runs http://127.0.0.1:4096 inside Quiper, where OpenCode shares an overlay with your other engines.

Starting point: what do you already have? ​

Pick the section that matches your situation and start there. You can skip anything marked "only if you don't have this yet."

If you…Start with
Haven't installed QuiperStep 1: Install Quiper
Installed Quiper but never launched itStep 2: Launch Quiper
Launched Quiper but don't see OpenCodeStep 4: Open OpenCode in Quiper
Haven't installed OpenCodeStep 3: Install OpenCode and start its server
OpenCode tab shows a connection errorStart the server (Step 3), then reload with ⌘ R

1. Install Quiper ​

Requirements: macOS 14.6 (Sonoma) or newer. No other hardware requirements.

  1. Download the latest disk image from the releases page (Quiper.dmg).
  2. Double-click the downloaded .dmg to mount it.
  3. Drag Quiper.app into your Applications folder.
  4. (Optional but recommended) Verify the download came from this repository's CI:
    bash
    gh attestation verify Quiper.dmg --repo sassanh/quiper
  5. Double-click Quiper.app in Applications to launch it. If macOS warns about an app from an unidentified developer, open System Settings → Privacy & Security and click Open Anyway.

TIP

Built Quiper from source or running the Debug build? The setup steps below are identical.

2. Launch Quiper ​

  1. Launch Quiper. It runs as a menu-bar application — you'll see its icon in the top-right menu bar. By default a Dock icon appears only while the overlay is open; set Dock visibility to Always or Never under Settings (⌘ ⇧ ,) → Appearance.
  2. When macOS asks to allow notifications, click Allow. Quiper needs this to show native notifications when an OpenCode generation finishes in the background. (You can change this later under System Settings → Notifications.)
  3. Open the overlay by pressing ⌥ Space (Option + Space). If the hotkey doesn't respond, Quiper needs Accessibility permission — see Troubleshooting.
  4. Dismiss the overlay with ⌥ Space again, ⌘ H, or ⌘ Q.

The overlay is now your home base: press ⌥ Space from any app to summon it.

3. Install OpenCode and start its server (only if you haven't) ​

Quiper embeds OpenCode's local web interface, so the OpenCode server must be installed and running on your Mac. If your server is already running, skip ahead to Step 4.

  1. Install OpenCode with the install script — this gives you the current v2 (see opencode.ai/v2/docs):
    bash
    curl -fsSL https://opencode.ai/v2/install | bash
    Alternatives: v2 — npm install -g @opencode/cli or brew install anomalyco/tap/opencode-v2; legacy v1 — curl -fsSL https://opencode.ai/install | bash, npm install -g opencode-ai, or brew install anomalyco/tap/opencode (see opencode.ai/docs). Both majors install the same opencode command — opencode --version tells you which one you have.
  2. OpenCode needs a configured model provider before it can answer. Run opencode once in a terminal and use /connect to sign in and add a provider (see opencode.ai/docs). If you already use OpenCode in the terminal, skip this.
  3. In a terminal, change to the project directory you want OpenCode to work in and start the server on the port Quiper expects — run the line for the major you installed:
    bash
    cd /path/to/project
opencode serve --port 4096  # v2
opencode web --port 4096    # v1
    Quiper's template points at the fixed http://127.0.0.1:4096 — v2's serve already uses that port (the flag is optional), while v1's web picks a random port unless you pass --port 4096.
  4. Leave that terminal running. Quiper loads the engine from this server, so quitting the terminal (or sleeping the Mac) disconnects the OpenCode tab until you start it again.

TIP

To pick the server password yourself, prefix either start command with OPENCODE_SERVER_PASSWORD=secret (see opencode.ai/docs/web) — without it, v2's serve prints a generated server password line at startup and v1's web runs without one. The user name defaults to opencode (override it with OPENCODE_SERVER_USERNAME). When you open the tab, Quiper shows a native sign-in sheet: enter your credentials, tick Remember this password to reuse them automatically, and click Sign In — one sign-in unlocks every OpenCode tab.

4. Open OpenCode in Quiper ​

OpenCode ships as a built-in engine template, so on a fresh install it's already in your engine selector — no configuration needed.

  1. Make sure the server from Step 3 is running.
  2. Press ⌥ Space to open the overlay.
  3. Click the OpenCode tab in the engine selector at the top. (If you've registered an engine hotkey in Settings → Shortcuts → Engine Hotkeys, press it to jump straight to OpenCode.)
  4. A session tab opens and Quiper automatically places the keyboard cursor inside OpenCode's prompt field, ready to type.

NOTE

Don't see an OpenCode tab? On a fresh install all default engines are preloaded, but if OpenCode was removed earlier you can add it again: open Settings (⌘ ⇧ ,) → Engines, click Add Engine, choose Blank, set the name to OpenCode and the URL to http://127.0.0.1:4096, then save. See Managing Engines for the focus selector (div[data-component='prompt-input'][contenteditable='true'], div[role='textbox'][contenteditable='true'], textarea, div[contenteditable='true']) and custom CSS defaults.

5. Verify OpenCode works ​

  1. Press ⌥ Space to open the overlay (if it isn't already open).
  2. Confirm the OpenCode tab is active and the prompt field is focused.
  3. Type a test message — for example, "Reply with OK" — and press Enter.
  4. Wait for the response to stream in. A generated answer means OpenCode is fully working in Quiper.

Optional refinements ​

  • Native notifications: Background generations surface as macOS notifications (requires the permission you granted in Step 2).
  • Persistent sessions: Use ⌘ 1–⌘ 0 to keep up to ten separate OpenCode threads alive. See Daily Workflow & Shortcuts.
  • Native look: Enable the transparent-background CSS in Settings (⌘ ⇧ ,) → Engines → OpenCode → Custom CSS and a matching vibrancy material under Settings → Appearance.
  • Extra privacy: Lock OpenCode's local data behind Touch ID under Settings → Engines → OpenCode → Secure Storage (the Encrypt Local Storage toggle). See Touch ID & Security.

Troubleshooting ​

ProblemLikely fix
⌥ Space doesn't open the overlayGrant Quiper Accessibility permission in System Settings → Privacy & Security → Accessibility, then re-bind the hotkey in Settings (⌘ ⇧ ,) → Shortcuts.
OpenCode tab shows a connection error or blank pageThe server isn't running. In a terminal, cd to your project and run opencode serve --port 4096 (v2) or opencode web --port 4096 (v1), then reload the tab with ⌘ R.
The server says the port is in useAnother server already occupies 4096 — either stop it, or point the engine at its port in Settings → Engines → OpenCode (URL).
Sign-in sheet keeps reappearingWrong user name or password. The user name defaults to opencode; check OPENCODE_SERVER_USERNAME / OPENCODE_SERVER_PASSWORD in the terminal you launched the server from.
Agent doesn't reply / asks for provider setupNo model provider is configured. Run opencode in a terminal and use /connect to add one (see opencode.ai/docs), then reload the tab.
No OpenCode tab in the selectorRe-add the engine manually (see Step 4).
Focus doesn't land in the prompt fieldThe focus selector is stale. Reset it in Settings → Engines → OpenCode → Prompt Input (enable Use Latest Default) and reload with ⌘ R.
No notifications for finished repliesCheck System Settings → Notifications → Quiper is set to Banners or Alerts.

For anything else, see Troubleshooting & Diagnostics.

Released under the MIT License.

Copyright © 2024-present Sassan Haradji