Home / OpenCode Tutorial

OpenCode Tutorial

From zero to a working OpenCode + Oh My OpenCode setup in one sitting

1. What You’ll Learn

This tutorial walks you through installing OpenCode, adding the Oh My OpenCode plugin, and running your first AI-assisted session on a real project. It assumes basic command-line familiarity but no prior OpenCode experience.

  • Install and verify OpenCode
  • Install the Oh My OpenCode plugin
  • Run OpenCode in a project using the Sisyphus agent
  • Understand where configuration lives and how to tweak it

2. Prerequisites

  • A recent Node.js or Bun installation
  • macOS, Linux, or WSL (Windows Subsystem for Linux)
  • Git installed
  • OpenCode 1.0.133 or newer (older versions have a config bug)

3. Install OpenCode

Use the official installer from opencode.ai:

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

After installation, verify the CLI:

opencode --version

If this prints a version ≥ 1.0.133, you are good to continue.

4. Install Oh My OpenCode (Plugin)

Oh My OpenCode is distributed as a plugin. The recommended installation method is via bunx:

Recommended

bunx oh-my-opencode install

Alternative package managers:

# npm
npm install -g oh-my-opencode

# bun
bun install -g oh-my-opencode

# yarn
yarn global add oh-my-opencode

# pnpm
pnpm add -g oh-my-opencode

Full details live in the installation guide, but this is enough for most setups.

5. Open Your First Project

  1. Choose or clone a project, for example: 
    git clone <your-repo-url>
cd <your-repo-folder>
  2. Launch OpenCode inside the project: 
    opencode
  3. Oh My OpenCode will automatically attach as the orchestration layer. The Sisyphus agent becomes available out of the box.

For a more detailed breakdown of how agents work, see the agents page.

6. Configuration Basics

Configuration is stored in JSON files:

  • .opencode/oh-my-opencode.json — project-specific (checked into the repo)
  • ~/.config/opencode/oh-my-opencode.json — user-wide defaults

Project configuration wins if both are present. Start with defaults, then tweak agents, hooks, MCPs, and LSP servers as you get comfortable.

See the configuration page for full field-by-field documentation.

7. Your First Guided Task

With OpenCode running, try a simple but realistic task, such as:

  • “Add dark mode toggle to the settings page, including tests.”
  • “Refactor the user service into smaller modules.”
  • “Write end-to-end documentation for the payment flow.”

The Sisyphus agent will plan steps, edit files, and keep going until the task is done. Hooks handle context management and recovery behind the scenes.

8. Next Steps

  • Read the use cases to see where Oh My OpenCode shines (monorepos, hybrid stacks, CI changes).
  • Compare Oh My OpenCode vs plain OpenCode to decide how heavily to lean on the plugin.
  • Browse the documentation for advanced features, hooks, MCPs, and LSP setup.
  • Check the FAQ if you run into installation or configuration questions.