oh-my-opencode-slim/docs/installation.md

Installation Guide

Complete installation instructions for oh-my-opencode-slim.

Table of Contents

• For Humans
• For LLM Agents
• Troubleshooting
• Uninstallation

---

For Humans

Quick Install

Run the interactive installer:

bunx oh-my-opencode-slim@latest install

Or use non-interactive mode:

bunx oh-my-opencode-slim@latest install --no-tui --tmux=no --skills=yes

Configuration Options

The installer supports the following options:

Option	Description
`--tmux=yes	no`
`--skills=yes	no`
--no-tui	Non-interactive mode
--dry-run	Simulate install without writing files
--reset	Force overwrite of existing configuration

Non-Destructive Behavior

By default, the installer is non-destructive. If an oh-my-opencode-slim.json configuration file already exists, the installer will not overwrite it. Instead, it will display a message:

ℹ Configuration already exists at ~/.config/opencode/oh-my-opencode-slim.json. Use --reset to overwrite.

To force overwrite of your existing configuration, use the --reset flag:

bunx oh-my-opencode-slim@latest install --reset

Note: When using --reset, the installer creates a .bak backup file before overwriting, so your previous configuration is preserved.

After Installation

The installer generates an OpenAI configuration by default (using gpt-5.4 and gpt-5-codex models). To use alternative providers like Kimi, GitHub Copilot, or ZAI Coding Plan, see Provider Configurations for step-by-step instructions.

Authenticate with your provider:

opencode auth login
# Select your provider → Complete OAuth flow

Once authenticated, run OpenCode and ping all agents to verify all agents respond.

💡 Tip: Models are fully customizable. The installer sets sensible defaults, but you can assign any model to any agent. Edit ~/.config/opencode/oh-my-opencode-slim.json (or .jsonc for comments support) to override models, adjust reasoning effort, or disable agents entirely.

Alternative: Ask Any Coding Agent

Paste this into Claude Code, AmpCode, Cursor, or any coding agent:

Install and configure by following the instructions here:
https://raw.githubusercontent.com/alvinunreal/oh-my-opencode-slim/refs/heads/master/README.md

---

For LLM Agents

If you're an LLM Agent helping set up oh-my-opencode-slim, follow these steps.

Step 1: Check OpenCode Installation

opencode --version

If not installed, direct the user to https://opencode.ai/docs first.

Step 2: Run the Installer

The installer generates an OpenAI configuration by default:

bunx oh-my-opencode-slim@latest install --no-tui --tmux=no --skills=yes

Examples:

# Interactive install (asks about tmux and skills)
bunx oh-my-opencode-slim@latest install

# Non-interactive with tmux and skills
bunx oh-my-opencode-slim@latest install --no-tui --tmux=yes --skills=yes

# Non-interactive without tmux or skills
bunx oh-my-opencode-slim@latest install --no-tui --tmux=no --skills=no

# Force overwrite existing configuration
bunx oh-my-opencode-slim@latest install --reset

The installer automatically:

• Adds the plugin to ~/.config/opencode/opencode.json
• Disables default OpenCode agents
• Generates agent model mappings in ~/.config/opencode/oh-my-opencode-slim.json (or .jsonc)

Step 3: Authenticate with Providers

Ask user to run the following command. Don't run it yourself, it requires user interaction.

opencode auth login
# Select your provider and complete OAuth flow

Step 4: Verify Installation

Ask the user to:

1. Start OpenCode: opencode
2. Run: ping all agents

Verify all agents respond successfully.

Crucial Advice for the User:

• They can easily assign different models to different agents by editing ~/.config/opencode/oh-my-opencode-slim.json (or .jsonc).
• If they want to add a different provider later (Kimi, GitHub Copilot, ZAI), they can update this file manually. See Provider Configurations for examples.
• Read the generated ~/.config/opencode/oh-my-opencode-slim.json (or .jsonc) file to understand the current configuration.

---

Troubleshooting

Installer Fails

Check the expected config format:

bunx oh-my-opencode-slim@latest install --help

Then manually create the config files at:

• ~/.config/opencode/oh-my-opencode-slim.json (or .jsonc)

Configuration Already Exists

If the installer reports that the configuration already exists, you have two options:

1. Keep existing config: The installer will skip the configuration step and continue with other operations (like adding the plugin or installing skills).

2. Reset configuration: Use --reset to overwrite:

   bunx oh-my-opencode-slim@latest install --reset
   

   A .bak backup file will be created automatically.

Agents Not Responding

1. Check your authentication:

   opencode auth status
   

2. Verify your config file exists and is valid:

   cat ~/.config/opencode/oh-my-opencode-slim.json
   

3. Check that your provider is configured in ~/.config/opencode/opencode.json

Authentication Issues

If providers are not working:

1. Check your authentication status:

   opencode auth status
   

2. Re-authenticate if needed:

   opencode auth login
   

3. Verify your config file has the correct provider configuration:

   cat ~/.config/opencode/oh-my-opencode-slim.json
   

Editor Validation

Add a $schema reference to your config for autocomplete and inline validation:

{
  "$schema": "https://unpkg.com/oh-my-opencode-slim@latest/oh-my-opencode-slim.schema.json",
  // your config...
}

Works in VS Code, Neovim (with jsonls), and any editor that supports JSON Schema. Catches typos and wrong nesting immediately.

Tmux Integration Not Working

Make sure you're running OpenCode with the --port flag and the port matches your OPENCODE_PORT environment variable:

tmux
export OPENCODE_PORT=4096
opencode --port 4096

See the Tmux Integration Guide for more details.

---

Uninstallation

1. Remove the plugin from your OpenCode config:

Edit ~/.config/opencode/opencode.json and remove "oh-my-opencode-slim" from the plugin array.

1. Remove configuration files (optional):

   rm -f ~/.config/opencode/oh-my-opencode-slim.json
   rm -f ~/.config/opencode/oh-my-opencode-slim.json.bak
   

2. Remove skills (optional):

   npx skills remove simplify
   npx skills remove agent-browser