The open source AI coding agent.

English | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | Bosanski | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська | বাংলা | Ελληνικά | Tiếng Việt

Installation #

# YOLO
curl -fsSL https://opencode.ai/install | bash

# Package managers
npm i -g opencode-ai@latest        # or bun/pnpm/yarn
scoop install opencode             # Windows
choco install opencode             # Windows
brew install anomalyco/tap/opencode # macOS and Linux (recommended, always up to date)
brew install opencode              # macOS and Linux (official brew formula, updated less)
sudo pacman -S opencode            # Arch Linux (Stable)
paru -S opencode-bin               # Arch Linux (Latest from AUR)
mise use -g opencode               # Any OS
nix run nixpkgs#opencode           # or github:anomalyco/opencode for latest dev branch

Desktop App (BETA) #

OpenCode is also available as a desktop application. Download directly from the releases page or opencode.ai/download.

# macOS (Homebrew)
brew install --cask opencode-desktop
# Windows (Scoop)
scoop bucket add extras; scoop install extras/opencode-desktop

Installation Directory #

The install script respects the following priority order for the installation path:

1. $OPENCODE_INSTALL_DIR - Custom installation directory
2. $XDG_BIN_DIR - XDG Base Directory Specification compliant path
3. $HOME/bin - Standard user binary directory (if it exists or can be created)
4. $HOME/.opencode/bin - Default fallback

# Examples
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

Agents #

OpenCode includes two built-in agents you can switch between with the Tab key.

• build - Default, full-access agent for development work
• plan - Read-only agent for analysis and code exploration
  • Denies file edits by default
  • Asks permission before running bash commands
  • Ideal for exploring unfamiliar codebases or planning changes

Also included is a general subagent for complex searches and multistep tasks. This is used internally and can be invoked using @general in messages.

Learn more about agents.

Documentation #

For more info on how to configure OpenCode, head over to our docs.

Contributing #

If you're interested in contributing to OpenCode, please read our contributing docs before submitting a pull request.

Building on OpenCode #

If you are working on a project that's related to OpenCode and is using "opencode" as part of its name, for example "opencode-dashboard" or "opencode-mobile", please add a note to your README to clarify that it is not built by the OpenCode team and is not affiliated with us in any way.

Join our community Discord | X.com

Local patch: interactive child sessions #

This workspace carries the sub-interactive TUI patch on base commit dcfe1ec7bd49 (feat(app): add /btw side question panel (#49750)), freshened 2026-09-22 from the original 312651f68ed2 line. The source of truth is the TUI child-session interaction entry in [/home/rektide/a/doc/opencode/patches.md](file:///home/rektide/a/doc/opencode/patches.md), with lifecycle background in [/home/rektide/a/doc/opencode/subagents.md](file:///home/rektide/a/doc/opencode/subagents.md).

Behavior #

The patch gives a child Session (parentID set) the same ordinary prompt composer as any other Session. A human can steer a running child or continue an idle/completed child directly from its transcript. The prompt submits to the current route.sessionID; a response produced after the original subagent Job has settled remains in the child transcript and is not automatically returned to the parent.

Decision reversed 2026-09-22 (operator direction — feature flags on promoted lines). The 2026-09-11 decision was "disarm is global — no session.interactive_children config, no keybind gate". That is reversed: the feature now carries exactly that config key as a self-disable flag, so promotion into working is reversible at runtime without recomposing. The flag is a TUI config boolean read in routes/session/index.tsx:

• session.interactive_children — default true (unset = feature active: composer visible on child sessions). Set false in the TUI config file to restore exact upstream behavior: composer guards re-armed (composer force-opened on the subagents tab, prompt suppressed, picker toggle force-closes on children) and the child-only priority-2 session.parent keymap layer never enables. The flag hot-reloads with the rest of the TUI config.

The disarm sites are gated on that flag (line pins are on the current base):

When the picker is closed on a child (flag active), this child-only base-mode layer gives the existing session.parent command priority over the focused prompt's history binding. Thus up still navigates to the parent. When the picker is open, Composer activates composer mode as before; closing its subagents tab still uses the existing onClose path to navigate to the parent.

Deliberate v1 constraint — may revisit #

Do not remove the child-view early returns in descendantSessionIDs(), permissions(), or forms() at packages/tui/src/routes/session/index.tsx:178-195. The root view aggregates descendant blockers, while the child view exposes no child-local permissions and only global forms. Consequently, a child blocked on elicitation can accept a user steer into its queue without showing that blocker in the child view; answer the elicitation from the root view. This is accepted for v1 and may revisit later.

With the picker closed:

• no visible global form: the ordinary focused <Prompt> renders for the child;
• a global form present: the global <FormPrompt> renders instead;
• child-local forms or permissions: they remain hidden by the deliberate v1 filtering above, so the ordinary prompt remains visible.

With the picker open, <Composer> renders and the switch suppresses the prompt and blocker surfaces regardless of form state, matching the existing picker behavior.

Verification checklist #

Use bun run dev:live from this development worktree for manual verification against the elected background server and live Sessions.

• Run bun typecheck from packages/tui.
• Run the neighboring keymap/composer tests: bun test test/cli/tui/composer-keymap.test.tsx test/keymap.test.tsx from packages/tui (10 passed). There are no *.test.* files under packages/tui/src/routes/session, and no existing test directly covers these child-view guards; tests importing that module exercise exported display helpers instead.
• Run the flag suite bun test test/cli/tui/child-composer-flag.test.tsx (2 passed: default keeps the child composer interactive with up navigating to the parent; session.interactive_children: false restores stock masking). 2026-09-22 full set: child-composer-flag 2, composer-keymap 6, input-scope 5, keymap trio (keymap + keymap-scope + keybind) 9, typecheck clean.
• Open a running child and submit a prompt; verify it steers the active run.
• Open a completed child and submit a prompt; verify it continues in the child transcript without an implicit return to the parent.
• Drive a child whose agent has edit: allow; verify permitted edits happen silently under the child agent's own permission policy. Also verify an interactive ask still reaches the root view and remains first-reply-wins.
• With the picker closed on a child, press up and verify navigation to the parent. Reopen the subagents picker and verify its close action also navigates to the parent.
• Set session.interactive_children: false in the TUI config and verify a child session looks exactly stock: subagents picker force-opened, no prompt input, down does not open the picker on a child. Toggle the file back to confirm hot-reload re-activates the composer without a restart.