e4d91aadf9
- Full Obsidian vault content - Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte) - Media stack documentation - Traefik HA setup - Automation scripts - Bachelor party planning
53 lines
2.4 KiB
Markdown
53 lines
2.4 KiB
Markdown
# oh-my-opencode Setup & Troubleshooting Runbook
|
|
|
|
## Overview
|
|
This runbook covers the steps required to enable `oh-my-opencode` properly, ensuring all primary agents (Sisyphus, Atlas, Prometheus) load and function correctly across the homelab infrastructure.
|
|
|
|
## Problem Context
|
|
Initially, `oh-my-opencode` was installed but failed to load primary agents. Symptoms included missing agents in the TUI and logs showing plugins loading except for `oh-my-opencode`.
|
|
|
|
## Root Causes Identified
|
|
1. **Malformed Configuration**: `oh-my-opencode.json` had broken JSON syntax and missing agent/hook blocks.
|
|
2. **Plugin Loading Order**: `oh-my-opencode` was not the first plugin in `opencode.json`, potentially causing initialization delays or conflicts.
|
|
3. **Missing Built-in Definitions**: Primary agents were not explicitly defined with correct model/category mappings.
|
|
|
|
## Step-by-Step Enablement
|
|
|
|
### 1. Update `opencode.json`
|
|
Ensure `oh-my-opencode@latest` is the first plugin in the list. This ensures it initializes before other plugins that might depend on it or conflict with its hooks.
|
|
|
|
```json
|
|
"plugin": [
|
|
"oh-my-opencode@latest",
|
|
"opencode-antigravity-auth@latest",
|
|
"./plugin/kilocode/plugin_kilocode.ts"
|
|
]
|
|
```
|
|
|
|
### 2. Standardize `oh-my-opencode.json`
|
|
Apply the standardized configuration with all hooks enabled and primary agents defined. Key sections to include:
|
|
- `sisyphus_agent`: Enable planner and plan replacement.
|
|
- `hooks`: Enable all 16+ hooks including `session-recovery`, `rules-injector`, and `think-mode`.
|
|
- `agents`: Define `sisyphus`, `atlas`, `prometheus`, `oracle`, `librarian`, and `explore` with appropriate models.
|
|
|
|
### 3. Verify Plugin Loading
|
|
Check OpenCode logs for successful plugin initialization:
|
|
```bash
|
|
grep "service=plugin.*loading" ~/.local/share/opencode/log/*.log
|
|
```
|
|
Look for: `service=plugin path=...oh-my-opencode/dist/index.js loading plugin`
|
|
|
|
### 4. Verify Agents in TUI
|
|
Launch OpenCode and verify `Sisyphus` appears in the agent selection. Also test slash commands like `/refactor` or `/git-master`.
|
|
|
|
## GitOps Workflow
|
|
All configuration changes must be made in the `homelabagentroot` repository and pushed to trigger the automated deployment sync.
|
|
|
|
1. Edit configs in `homelab/configs/opencode-global/`
|
|
2. Commit and push to `origin main`
|
|
3. The Gitea runner will pull changes and restart services as configured.
|
|
|
|
---
|
|
**Last Updated:** January 25, 2026
|
|
**Status:** Verified Working ✅
|