Skip to content
~/oleksandr-ponomarov Home

OpenCode + OmO

chezmoi, the dotfile manager, manages the shared OpenCode configuration, Oh My OpenAgent routing, fish integration, and tmux notification plumbing. Secrets and company-specific endpoints stay local.

What is managed

OmO ~/.omo/omo.jsonc

Agent categories, model choices, fallbacks, and disabled hooks.

The OpenCode configuration currently declares the opencode-claude-auth, Oh My OpenAgent, and contextual-notifier plugins. OpenCode installs these plugins with Bun when it starts.

First-run checklist

  1. Apply the dotfiles with the setup guide.
  2. Create the local secret files if you want to use the Home Assistant MCP server.
  3. Put only the secret value in each file—no quotes or variable names.
  4. Start a new fish shell so an optional corporate overlay is detected.
  5. Restart all running OpenCode processes after changing plugin declarations.

Local secrets

The managed OpenCode file references two files that are intentionally not tracked by Git:

  • ~/.config/opencode/secrets/home-assistant-mcp-url
  • ~/.config/opencode/secrets/home-assistant-access-token

Create them with restrictive permissions:

install -d -m 700 "$HOME/.config/opencode/secrets"
install -m 600 /dev/null "$HOME/.config/opencode/secrets/home-assistant-mcp-url"
install -m 600 /dev/null "$HOME/.config/opencode/secrets/home-assistant-access-token"

Edit each file and store only its value. OpenCode resolves the {file:...} references when it loads the configuration; chezmoi never reads or copies the secret contents.

The files start empty

The install commands create secure placeholders. Populate them before enabling or using the Home Assistant MCP integration.

Corporate overlay

Put company-specific OpenCode configuration in:

~/.config/opencode/opencode.corp.json

This file is unmanaged and should use mode 0600:

install -m 600 /dev/null "$HOME/.config/opencode/opencode.corp.json"

When the file exists, the managed fish snippet sets OPENCODE_CONFIG to its path. Keep company endpoints, profiles, and credentials there rather than adding them to the personal repository. The overlay can use the same {file:...} syntax for credentials stored in separate local files.

Start a new fish shell—or source the managed snippet—after creating or removing the overlay.

Model routing

~/.omo/omo.jsonc is the routing source of truth. It assigns primary and fallback models to named agents and task categories, using a fallback when the first choice is unavailable.

Model names change more often than the surrounding workflow, so consult the managed file for the current assignments rather than copying a list from this page. The session-notification hook is disabled there because notifications are handled by the dedicated contextual-notifier plugin.

Contextual notifications

OpenCode declares the opencode-contextual-notifier package in the managed opencode.json. Its tmux companion is declared through TPM in the managed tmux.conf.

Together they mark the originating tmux window when an OpenCode session needs attention and clear that state when the window is selected or focused. The notifier package repository contains its implementation and tests; this dotfiles repository only declares and configures it.

After changing the notifier declaration:

  1. Restart OpenCode so Bun can synchronize the package.
  2. Reload tmux with Ctrl+A then Ctrl+R.
  3. Run the TPM installation flow if the companion plugin is not present.

Deliberately unmanaged

opencode.corp.jsonCompany-specific configuration
opencode/secrets/Credentials and private endpoints
tui.jsonA separate server-side extension surface
opencode-notifier.jsonNot referenced by the active notifier
Runtime filesCaches, backups, lockfiles, and dependency directories

Troubleshooting

An MCP server fails to start

Confirm that both secret files exist, contain a value, and use mode 0600:

stat -f '%Sp %N' "$HOME/.config/opencode/secrets/"*  # macOS
stat -c '%A %n' "$HOME/.config/opencode/secrets/"*  # Linux

The corporate configuration is ignored

Open a new fish shell and confirm that the variable points to the expected file:

echo $OPENCODE_CONFIG

A notification or tmux marker is stale

Focus the originating tmux window first. If the marker remains, restart OpenCode and reload tmux configuration with Ctrl+A then Ctrl+R.