opencode-rebalancer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 s-w-choi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# opencode-rebalancer
+
+Model routing rebalancer skill for [OpenCode](https://opencode.ai) with [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode). Analyzes actual usage data from the OpenCode SQLite database and proposes optimized model routing across your providers (GPT, GLM, Kimi, Qwen, etc.).
+
+> **Note**: This skill edits `oh-my-openagent.json` and requires the [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) plugin. It also respects the `no-sisyphus-gpt` hook that prevents the Sisyphus orchestrator from using GPT models (GPT-5.4+ are exempt with specialized variant support).
+
+## What It Does
+
+- **Usage analysis**: Queries the OpenCode SQLite DB to show per-provider and per-agent call distribution over 7d/30d windows
+- **Plan-aware recommendations**: Stores your provider plan info persistently so you don't have to repeat it every session
+- **Config change tracking**: Archives previous configs and maintains a changelog so you can track what changed and when
+- **Smart routing rules**: Built-in knowledge of the `no-sisyphus-gpt` hook, agent classifications, and rate limit constraints
+
+## Prerequisites
+
+- [OpenCode](https://opencode.ai) CLI
+- [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) plugin (provides `oh-my-openagent.json` config and agent schema)
+- `sqlite3` — for querying usage data
+- `python3` — for cross-platform date math in SQL queries
+- macOS or Linux
+
+## Files Managed
+
+| File | Path | Action |
+|------|------|--------|
+| Skill (installed) | `~/.agents/skills/opencode-rebalancer/` | **Created** by postinstall |
+| Skill (symlink) | `~/.claude/skills/opencode-rebalancer` | **Symlinked** by postinstall |
+| Agent config | `~/.config/opencode/oh-my-openagent.json` | **Modified** — model routing |
+| Plan info | `~/.config/opencode/rebalancer/plans.json` | **Created** — your provider plans |
+| Changelog | `~/.config/opencode/rebalancer/changelog.md` | **Created** — change history |
+| Config backups | `~/.config/opencode/rebalancer/archive/*.json` | **Created** — timestamped snapshots |
+| Usage DB | `~/.local/share/opencode/opencode.db` | **Read-only** — SQLite usage data (respects `XDG_DATA_HOME`) |
+
+## Installation
+
+### From npm
+
+```bash
+npm install opencode-rebalancer
+```
+
+The `postinstall` script automatically:
+1. Copies the skill to `~/.agents/skills/opencode-rebalancer/`
+2. Symlinks it into `~/.claude/skills/` for broad agent compatibility
+3. Removes any old `model-rebalancer` skill (if upgrading from a previous name)
+4. Initializes `~/.config/opencode/rebalancer/` with `plans.json` and `changelog.md`
+
+### From source
+
+```bash
+git clone https://github.com/s-w-choi/opencode-rebalancer.git
+cd opencode-rebalancer
+node postinstall.mjs
+```
+
+### First-time setup
+
+On first run, the skill will ask for your provider plan info:
+
+```
+💰 Provider Plan info is needed:
+1. Your plan name and cost for each provider
+2. Usage limits (per 5h / weekly / monthly)
+3. Any agent-specific preferences
+```
+
+This is saved to `plans.json` and never asked again (unless you set `needs_update: true`).
+
+## Usage
+
+Just ask your agent:
+
+- "rebalance models"
+- "check current model usage"
+- "optimize provider distribution"
+- "I'm hitting rate limits on [provider]"
+
+The skill automatically:
+
+1. Reads your plan info from `plans.json`
+2. Queries the SQLite DB for 7d/30d usage data
+3. Cross-references usage against plan limits
+4. Proposes changes as a diff
+5. On approval: archives current config, applies changes, updates changelog
+
+## Routing Strategy
+
+The default strategy follows these principles:
+
+1. **Sisyphus = non-GPT** — The `no-sisyphus-gpt` hook from oh-my-opencode blocks GPT for the orchestrator. GPT-5.4+ are exempt (they have specialized variant support). Use GLM/Kimi for Sisyphus.
+2. **Reasoning agents = top-tier** — oracle, prometheus, metis, momus use the best available model (low frequency justifies cost).
+3. **Coding agents = codex** — hephaestus, sisyphus-junior, build use codex variants.
+4. **Lightweight = cheapest** — explore, librarian, atlas, quick, writing use the cheapest available model.
+5. **Conserve rate limits** — High-frequency agents (junior) use slightly lower model tiers to stay within message limits.
+
+### The `no-sisyphus-gpt` Hook
+
+oh-my-opencode ships a built-in hook that:
+
+1. Detects when Sisyphus uses a GPT model
+2. For GPT-5.4+: Sets a specialized variant instead of blocking (these have native Sisyphus support)
+3. For all other GPT models: Shows error toast and force-redirects to Hephaestus
+
+This rebalancer respects that constraint.
+
+## Example Configuration
+
+A best-practice setup using multiple providers (adjust model IDs to what `opencode models` lists for you):
+
+### Agent Routing
+
+| Role | Agent | Primary | Variant | Fallback 1 | Fallback 2 |
+|------|-------|---------|---------|-------------|-------------|
+| Orchestrator | `sisyphus` | `zai-coding-plan/glm-5.1` | — | `opencode-go/kimi-k2.6` | `opencode-go/kimi-k2.5` |
+| Reasoning | `oracle` | `openai/gpt-5.5` | `high` | `openai/gpt-5.4` | `opencode-go/glm-5.1` |
+| Reasoning | `prometheus` | `openai/gpt-5.5` | `high` | `openai/gpt-5.4` | `opencode-go/glm-5.1` |
+| Reasoning | `metis` | `openai/gpt-5.5` | `high` | `openai/gpt-5.4` | `opencode-go/glm-5.1` |
+| Reasoning | `momus` | `openai/gpt-5.5` | `high` | `openai/gpt-5.4` | `opencode-go/glm-5.1` |
+| Reasoning | `plan` | `openai/gpt-5.5` | `high` | `openai/gpt-5.4` | `opencode-go/glm-5.1` |
+| Coding | `hephaestus` | `openai/gpt-5.3-codex` | — | `openai/gpt-5.2-codex` | `openai/gpt-5.1-codex-max` |
+| Coding | `sisyphus-junior` | `openai/gpt-5.2-codex` | — | `openai/gpt-5.3-codex` | `openai/gpt-5.1-codex-max` |
+| Coding | `build` | `openai/gpt-5.2-codex` | — | `openai/gpt-5.3-codex` | `openai/gpt-5.1-codex-max` |
+| Lightweight | `explore` | `opencode-go/qwen3.6-plus` | — | `opencode-go/qwen3.5-plus` | `opencode-go/minimax-m2.7` |
+| Lightweight | `librarian` | `opencode-go/qwen3.6-plus` | — | `opencode-go/qwen3.5-plus` | `opencode-go/minimax-m2.7` |
+| Lightweight | `atlas` | `opencode-go/qwen3.6-plus` | — | `opencode-go/qwen3.5-plus` | `opencode-go/minimax-m2.7` |
+| Lightweight | `OpenCode-Builder` | `opencode-go/qwen3.6-plus` | — | `opencode-go/qwen3.5-plus` | `opencode-go/minimax-m2.7` |
+| Vision | `multimodal-looker` | `openai/gpt-5.2` | — | `openai/gpt-5.4` | `opencode/gpt-5-nano` |
+
+### Category Routing
+
+| Category | Primary | Variant | Fallback 1 | Fallback 2 |
+|----------|---------|---------|-------------|-------------|
+| `ultrabrain` | `openai/gpt-5.5` | `xhigh` | `openai/gpt-5.4` | `opencode-go/glm-5.1` |
+| `deep` | `openai/gpt-5.5` | `medium` | `openai/gpt-5.4` | `opencode-go/glm-5.1` |
+| `visual-engineering` | `openai/gpt-5.2` | — | `opencode-go/minimax-m2.7` | `openai/gpt-5.4` |
+| `artistry` | `openai/gpt-5.2` | — | `opencode-go/minimax-m2.7` | `openai/gpt-5.4` |
+| `unspecified-high` | `openai/gpt-5.2` | — | `opencode-go/minimax-m2.7` | `openai/gpt-5.4` |
+| `quick` | `opencode-go/qwen3.6-plus` | — | `opencode-go/qwen3.5-plus` | `opencode-go/minimax-m2.7` |
+| `unspecified-low` | `opencode-go/qwen3.6-plus` | — | `opencode-go/qwen3.5-plus` | `opencode-go/minimax-m2.7` |
+| `writing` | `opencode-go/qwen3.6-plus` | — | `opencode-go/qwen3.5-plus` | `opencode-go/minimax-m2.7` |
+
+### Provider Mix Rationale
+
+| Provider | Models | Best For | Cost |
+|----------|--------|----------|------|
+| **ZAI** (GLM) | `glm-5.1` | Sisyphus orchestrator — no weekly cap, generous | $9/mo |
+| **OpenCode Go** | `qwen3.6-plus`, `minimax-m2.7`, `kimi-k2.6` | Lightweight agents — cheapest per-call | $10/mo |
+| **OpenAI** | `gpt-5.5`, `gpt-5.3-codex`, `gpt-5.2-codex` | Reasoning & coding — highest quality | $20/mo (message-limited) |
+| **Kimi** | `k2p5`, `k2p6` | Sisyphus fallback — coding-optimized | $19/mo |
+
+Key principle: fallback chains always cross providers so one provider outage doesn't cascade.
+
+## Uninstall
+
+```bash
+npm uninstall opencode-rebalancer
+```
+
+The `preuninstall` script removes:
+- `~/.agents/skills/opencode-rebalancer/` (installed skill)
+- `~/.claude/skills/opencode-rebalancer` (symlink)
+- `~/.config/opencode/rebalancer/` (plans, changelog, archives)
+
+Your `oh-my-openagent.json` config is **not modified**.
+
+## Cross-Platform
+
+All SQLite queries use `python3` for date math instead of platform-specific `date` flags. Works on macOS and Linux. Respects `XDG_CONFIG_HOME` and `XDG_DATA_HOME` if set.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "opencode-rebalancer",
+  "version": "1.0.0",
+  "description": "Model routing rebalancer for OpenCode — analyze usage data, optimize provider distribution, track changes.",
+  "type": "module",
+  "keywords": [
+    "opencode",
+    "model-routing",
+    "rebalancer",
+    "provider-optimization",
+    "rate-limits"
+  ],
+  "license": "MIT",
+  "author": "s-w-choi <https://github.com/s-w-choi>",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/s-w-choi/opencode-rebalancer"
+  },
+  "files": [
+    "skills/",
+    "templates/",
+    "postinstall.mjs",
+    "preuninstall.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.mjs",
+    "preuninstall": "node preuninstall.mjs"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,86 @@
+import { mkdirSync, cpSync, rmSync, symlinkSync, lstatSync, statSync, existsSync, writeFileSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const xdgRaw = process.env.XDG_CONFIG_HOME;
+const XDG = (xdgRaw && isAbsolute(xdgRaw)) ? xdgRaw : join(homedir(), '.config');
+
+const SKILL_NAME = 'opencode-rebalancer';
+const SKILL_SRC = join(__dirname, 'skills', SKILL_NAME);
+const AGENTS_SKILLS_DIR = join(homedir(), '.agents', 'skills');
+const CLAUDE_SKILLS_DIR = join(homedir(), '.claude', 'skills');
+const SKILL_DEST = join(AGENTS_SKILLS_DIR, SKILL_NAME);
+const CLAUDE_LINK = join(CLAUDE_SKILLS_DIR, SKILL_NAME);
+
+const REBALANCER_DIR = join(XDG, 'opencode', 'rebalancer');
+const ARCHIVE_DIR = join(REBALANCER_DIR, 'archive');
+const PLANS_FILE = join(REBALANCER_DIR, 'plans.json');
+const CHANGELOG_FILE = join(REBALANCER_DIR, 'changelog.md');
+const TEMPLATE = join(__dirname, 'templates', 'plans.json');
+
+const OLD_SKILL_NAME = 'model-rebalancer';
+const OLD_SKILL_DEST = join(AGENTS_SKILLS_DIR, OLD_SKILL_NAME);
+const OLD_CLAUDE_LINK = join(CLAUDE_SKILLS_DIR, OLD_SKILL_NAME);
+
+const MINIMAL_PLANS = JSON.stringify(
+  { last_updated: null, needs_update: true, providers: {}, strategy: { summary: '', rules: [] } },
+  null,
+  2
+) + '\n';
+
+function isSymlink(p) {
+  try { return lstatSync(p).isSymbolicLink(); } catch { return false; }
+}
+
+try {
+  // ── 1. Remove old skill (model-rebalancer → opencode-rebalancer rename) ──
+  if (existsSync(OLD_SKILL_DEST)) {
+    rmSync(OLD_SKILL_DEST, { recursive: true, force: true });
+    console.log(`opencode-rebalancer: removed old skill '${OLD_SKILL_NAME}' from ${AGENTS_SKILLS_DIR}`);
+  }
+  if (isSymlink(OLD_CLAUDE_LINK) || existsSync(OLD_CLAUDE_LINK)) {
+    rmSync(OLD_CLAUDE_LINK, { force: true });
+    console.log(`opencode-rebalancer: removed old symlink '${OLD_SKILL_NAME}' from ${CLAUDE_SKILLS_DIR}`);
+  }
+
+  // ── 2. Install skill to ~/.agents/skills/ ──
+  if (existsSync(SKILL_SRC)) {
+    mkdirSync(AGENTS_SKILLS_DIR, { recursive: true });
+    if (existsSync(SKILL_DEST)) rmSync(SKILL_DEST, { recursive: true, force: true });
+    cpSync(SKILL_SRC, SKILL_DEST, { recursive: true });
+    console.log(`opencode-rebalancer: skill installed to ${SKILL_DEST}`);
+  }
+
+  // ── 3. Symlink into ~/.claude/skills/ ──
+  if (existsSync(SKILL_DEST)) {
+    mkdirSync(CLAUDE_SKILLS_DIR, { recursive: true });
+    if (isSymlink(CLAUDE_LINK) || existsSync(CLAUDE_LINK)) rmSync(CLAUDE_LINK, { recursive: true, force: true });
+    symlinkSync(SKILL_DEST, CLAUDE_LINK);
+    console.log(`opencode-rebalancer: symlinked to ${CLAUDE_LINK}`);
+  }
+
+  // ── 4. Create config directories ──
+  mkdirSync(ARCHIVE_DIR, { recursive: true });
+
+  // ── 5. Initialize plans.json if missing ──
+  if (!isSymlink(PLANS_FILE) && !statSync(PLANS_FILE, { throwIfNoEntry: false })) {
+    if (existsSync(TEMPLATE) && !isSymlink(TEMPLATE)) {
+      cpSync(TEMPLATE, PLANS_FILE);
+    } else {
+      writeFileSync(PLANS_FILE, MINIMAL_PLANS, { mode: 0o600 });
+    }
+  }
+
+  // ── 6. Initialize changelog.md if missing ──
+  if (!isSymlink(CHANGELOG_FILE) && !statSync(CHANGELOG_FILE, { throwIfNoEntry: false })) {
+    writeFileSync(CHANGELOG_FILE, '# Model Rebalancer Changelog\n', { mode: 0o600 });
+  }
+
+  console.log('opencode-rebalancer: initialized');
+} catch (err) {
+  console.warn('opencode-rebalancer: setup incomplete — ' + err.message);
+  console.warn('  Run manually: node ' + join(__dirname, 'postinstall.mjs'));
+}

package/preuninstall.mjs

@@ -0,0 +1,34 @@
+import { rmSync, lstatSync, existsSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+
+const xdgRaw = process.env.XDG_CONFIG_HOME;
+const XDG = (xdgRaw && isAbsolute(xdgRaw)) ? xdgRaw : join(homedir(), '.config');
+
+const SKILL_NAME = 'opencode-rebalancer';
+const AGENTS_SKILLS_DIR = join(homedir(), '.agents', 'skills');
+const CLAUDE_SKILLS_DIR = join(homedir(), '.claude', 'skills');
+const SKILL_DEST = join(AGENTS_SKILLS_DIR, SKILL_NAME);
+const CLAUDE_LINK = join(CLAUDE_SKILLS_DIR, SKILL_NAME);
+const REBALANCER_DIR = join(XDG, 'opencode', 'rebalancer');
+
+try {
+  if (existsSync(SKILL_DEST)) {
+    rmSync(SKILL_DEST, { recursive: true, force: true });
+    console.log(`opencode-rebalancer: removed skill from ${SKILL_DEST}`);
+  }
+  try {
+    const s = lstatSync(CLAUDE_LINK);
+    if (s.isSymbolicLink() || s.isDirectory()) {
+      rmSync(CLAUDE_LINK, { recursive: true, force: true });
+      console.log(`opencode-rebalancer: removed from ${CLAUDE_LINK}`);
+    }
+  } catch { /* doesn't exist */ }
+  if (existsSync(REBALANCER_DIR)) {
+    rmSync(REBALANCER_DIR, { recursive: true, force: true });
+    console.log(`opencode-rebalancer: removed config at ${REBALANCER_DIR}`);
+  }
+  console.log('opencode-rebalancer: uninstalled. Your oh-my-openagent.json was not modified.');
+} catch (err) {
+  console.warn('opencode-rebalancer: cleanup incomplete — ' + err.message);
+}

package/skills/opencode-rebalancer/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: opencode-rebalancer
+description: Analyzes actual OpenCode usage data from SQLite and redistributes model routing across providers to optimize cost and rate limit distribution. Use when the user asks to "rebalance models", "optimize model routing", "redistribute providers", "check model usage", or wants to adjust which models handle which agents based on real usage patterns.
+---
+
+# Model Rebalancer
+
+Analyzes real usage data from the OpenCode SQLite database and proposes optimized model routing configuration across available providers (GPT, GLM, Kimi, Qwen, etc.).
+
+**Requires**: [oh-my-openagent](https://github.com/code-yeongyu/oh-my-opencode) plugin with `no-sisyphus-gpt` hook enabled.
+
+## When to Use
+
+- User asks to rebalance/redistribute model routing
+- User wants to check current model usage distribution
+- User wants to optimize costs across multiple provider plans
+- User notices rate limiting on a specific provider
+- User wants to add a new provider/model to the rotation
+
+## Prerequisites Check
+
+Before proceeding, verify:
+
+**Hard prerequisites (STOP if missing)**:
+1. `sqlite3` CLI is available
+2. `python3` is available
+3. OpenCode SQLite database exists (default: `~/.local/share/opencode/opencode.db`, respects `XDG_DATA_HOME`)
+
+**Soft prerequisites (warn but continue)**:
+4. `opencode models` — if unavailable, skip model ID validation and warn user
+
+## File Locations
+
+| File | Path | Role |
+|------|------|------|
+| **Config** | `~/.config/opencode/oh-my-openagent.json` | Current agent/category model routing |
+| **Plan Info** | `~/.config/opencode/rebalancer/plans.json` | User's provider plans and limits |
+| **Change Archive** | `~/.config/opencode/rebalancer/archive/` | Timestamped config snapshots |
+| **Changelog** | `~/.config/opencode/rebalancer/changelog.md` | Human-readable change history |
+| **Usage DB** | `$XDG_DATA_HOME/.../opencode.db` (default `~/.local/share/opencode/opencode.db`) | SQLite with all message history |
+| **Scripts** | (this package) `scripts/` | Executable helpers |
+| **Lib** | (this package) `lib/` | Shared config and date helpers |
+
+> All paths under `~/.config/` respect `XDG_CONFIG_HOME`; the DB path respects `XDG_DATA_HOME`. Scripts and lib use the same XDG-aware resolution.
+
+## Script Resolution
+
+This skill ships executable helpers in `scripts/` with shared config in `lib/`. When installed via npm, the postinstall script copies the skill to `~/.agents/skills/opencode-rebalancer/`. Scripts are self-locating via `SCRIPT_DIR`:
+
+```bash
+# All scripts resolve their own location and source lib/ automatically.
+# Just invoke them directly:
+bash ~/.agents/skills/opencode-rebalancer/scripts/collect-usage.sh
+```
+
+Scripts auto-resolve all paths (XDG-aware) via `lib/config.sh`. No manual path setup needed.
+
+## Step 0: Load Persistent Context
+
+### 0a. Read plan info
+
+```bash
+REBALANCER_CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/opencode/rebalancer"
+cat "$REBALANCER_CONFIG/plans.json"
+```
+
+If the file exists and `needs_update` is `false`, use it directly — **DO NOT ask the user for plan info again**.
+
+If the file does NOT exist or `needs_update: true`, ask the user:
+
+```
+💰 Provider Plan info is needed to make good recommendations:
+1. Your plan name and cost for each provider (e.g. ZAI Starter $9/mo, OpenCode Go $10/mo)
+2. Usage limits (per 5h / weekly / monthly)
+3. Any agent-specific preferences or constraints
+```
+
+After collecting, save to `$REBALANCER_CONFIG/plans.json` (see [Plan Info Schema](#plan-info-schema)).
+
+### 0b. Read current config
+
+```bash
+cat "${XDG_CONFIG_HOME:-$HOME/.config}/opencode/oh-my-openagent.json"
+```
+
+## Step 1: Collect Usage Data
+
+Run the collection script:
+
+```bash
+bash ~/.agents/skills/opencode-rebalancer/scripts/collect-usage.sh
+```
+
+This outputs:
+- Provider distribution (30d & 7d)
+- Per-agent per-provider matrix (30d)
+- Agent usage ratio (30d)
+- Available models (via `opencode models`)
+
+## Step 2: Analyze Current Distribution
+
+Cross-reference usage data with plan limits from `plans.json`.
+
+**NOTE**: "Plan utilization" is a **call-share proxy**, not exact spend. Always present utilization as an estimate.
+
+For each provider:
+- **Call share** (from SQLite) vs **plan limit** = estimated utilization %
+- **Risk level**: Low (<50%), Medium (50-80%), High (>80%), Critical (>95%)
+
+For each agent:
+- **Current primary model** and its call count
+- **Whether the model tier matches task complexity**
+- **Rate limit risk** based on call frequency
+
+## Step 3: Apply Routing Rules
+
+### HARD CONSTRAINT: no-sisyphus-gpt Hook
+
+oh-my-opencode has a built-in `no-sisyphus-gpt` hook that:
+
+1. **Detects** when Sisyphus uses a GPT model (via `model.includes("gpt")`)
+2. **For GPT-5.4+** (`gpt-5.4`, `gpt-5.5`, `gpt-5.6`, etc.): Sets a specialized variant instead of blocking — these have native Sisyphus support
+3. **For all other GPT models**: Shows error toast "NEVER Use Sisyphus with GPT" and force-redirects Sisyphus → Hephaestus
+
+**Rule**: Sisyphus MUST use non-GPT models (GLM, Kimi, Qwen). GPT-5.4+ are technically exempt but should be avoided due to cost.
+
+### Agent Classification
+
+**ORCHESTRATOR (GLM/Kimi only — GPT blocked by runtime hook)**:
+- `sisyphus` → `zai-coding-plan/glm-5.1` (primary)
+  - Fallback: `opencode-go/kimi-k2.6` → `kimi-for-coding/k2p6`
+
+**REASONING (GPT-5.5, low frequency, high quality)**:
+- `oracle`, `prometheus`, `metis`, `momus` → `openai/gpt-5.5` (high variant)
+- `plan` → `openai/gpt-5.5` (high variant)
+
+**CODING (GPT codex, moderate frequency)**:
+- `hephaestus` → `openai/gpt-5.3-codex`
+- `sisyphus-junior` → `openai/gpt-5.2-codex` (slightly lower for rate limit headroom)
+- `build` → `openai/gpt-5.2-codex`
+
+**LIGHTWEIGHT (OpenCode Go or equivalent — cheapest, generous limits)**:
+- `explore`, `librarian`, `atlas` → cheapest available lightweight model
+- `OpenCode-Builder` → cheapest available lightweight model
+
+**SPECIAL CASES**:
+- `multimodal-looker` → Must use vision-capable model
+
+### Category Classification
+
+| Category | Typical Tier | Rationale |
+|----------|-------------|-----------|
+| `ultrabrain` | Highest | Hardest tasks, needs top reasoning |
+| `deep` | High | Deep autonomous work |
+| `visual-engineering` | Medium-High | UI/UX needs capable model |
+| `artistry` | Medium | Creative problem solving |
+| `unspecified-high` | Medium | General high-effort tasks |
+| `quick` | Low | Trivial tasks, save expensive model quota |
+| `unspecified-low` | Low | Low effort tasks |
+| `writing` | Low | Documentation |
+
+### Full Agent List (14 agents in oh-my-openagent schema)
+
+```
+sisyphus, sisyphus-junior, hephaestus, oracle, prometheus,
+metis, momus, explore, librarian, atlas, multimodal-looker,
+build, plan, OpenCode-Builder
+```
+
+### Redistribution Principles
+
+1. **no-sisyphus-gpt**: Sisyphus MUST NOT use GPT. GPT-5.4+ are technically exempt but costly. This is enforced by a runtime hook.
+2. **Codex for coding**: hephaestus, sisyphus-junior, build → GPT codex variants
+3. **Conserve expensive model rate limits**: Use top-tier models only for reasoning and coding agents.
+4. **Reserve primary cheap provider for orchestrator**: If the user has a provider with no weekly cap (e.g. ZAI Starter), use it primarily for Sisyphus.
+5. **Use secondary cheap provider for lightweight**: explore, librarian, atlas, writing → cheapest available.
+6. **Fallback chains**: Always specify 2-3 fallbacks with different providers.
+7. **Manual override**: Note that OpenCode Go includes kimi-k2.5, kimi-k2.6, glm-5.1 — user can manually switch Sisyphus to Go models when primary limits are hit.
+
+## Step 4: Generate Configuration
+
+Read the current config:
+```bash
+cat "${XDG_CONFIG_HOME:-$HOME/.config}/opencode/oh-my-openagent.json"
+```
+
+Generate the updated config. **Before applying, confirm with user**:
+
+```
+🎯 How would you like to proceed?
+1. **Full refresh**: Update all agents/categories at once
+2. **Partial update**: Only change specific agents (e.g. just sisyphus)
+3. **Accept recommendation**: Apply data-driven optimization as-is
+```
+
+Present changes as a diff.
+
+## Step 5: Apply, Archive, and Report
+
+### 5a. Archive current config
+
+```bash
+bash ~/.agents/skills/opencode-rebalancer/scripts/archive.sh
+```
+
+### 5b. Apply changes (SAFE WRITE)
+
+**NEVER write directly to `oh-my-openagent.json`.** Use the apply script:
+
+```bash
+bash ~/.agents/skills/opencode-rebalancer/scripts/apply.sh /path/to/new-config.json
+```
+
+The script validates JSON before replacing the original. If validation fails, the original is preserved untouched.
+
+### 5c. Create changelog entry
+
+```bash
+echo "### Changes
+- agent: model_before → model_after (reason)
+
+### Provider Distribution
+- provider-a: X% (Y calls/7d)
+
+### Plan Utilization
+- Plan A: Z% utilization" | bash ~/.agents/skills/opencode-rebalancer/scripts/changelog.sh
+```
+
+### 5d. Report to user
+
+1. **Before/After table** showing each agent's model change
+2. **Provider distribution projection** (estimated new call distribution)
+3. **Plan utilization** (each plan's usage vs limit)
+4. **Risk notes** (any agents where the model was changed)
+
+## Plan Info Schema
+
+`$XDG_CONFIG_HOME/opencode/rebalancer/plans.json` (default: `~/.config/opencode/rebalancer/plans.json`):
+
+```json
+{
+  "last_updated": "YYYY-MM-DD",
+  "needs_update": false,
+  "providers": {
+    "provider-id": {
+      "plan_name": "Plan Name",
+      "monthly_cost": 0,
+      "currency": "USD",
+      "limits": {
+        "5h": "description",
+        "weekly": "description",
+        "monthly": "description"
+      },
+      "notes": "Any provider-specific quirks",
+      "models": ["model-a", "model-b"]
+    }
+  },
+  "strategy": {
+    "summary": "One-line summary of the routing strategy",
+    "rules": [
+      "Rule 1",
+      "Rule 2"
+    ]
+  }
+}
+```
+
+## Config Schema Reference
+
+The `oh-my-openagent.json` file structure:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
+  "agents": {
+    "<agent-name>": {
+      "model": "provider/model-id",
+      "variant": "high|medium|low|xhigh",
+      "fallback_models": ["provider/model-2", "provider/model-3"]
+    }
+  },
+  "categories": {
+    "<category-name>": {
+      "model": "provider/model-id",
+      "variant": "high|medium|low|xhigh",
+      "fallback_models": ["provider/model-2", "provider/model-3"]
+    }
+  },
+  "_migrations": ["..."]
+}
+```
+
+## Important Constraints
+
+- **NEVER** set `sisyphus` to any GPT model (the hook redirects to Hephaestus; GPT-5.4+ are technically exempt but costly)
+- **NEVER** set `multimodal-looker` to a model without verified vision support
+- **NEVER** use model IDs that don't exist in `opencode models` output
+- **ALWAYS** validate fallback model IDs exist
+- **ALWAYS** preserve the `$schema` field in config
+- **ALWAYS** show changes as diff before applying
+- **NEVER** remove existing agent entries (only update/add)
+- **ALWAYS** archive current config before applying changes
+- **ALWAYS** read `plans.json` first — don't re-ask user for plan info
+- **ALWAYS** update `changelog.md` after applying changes
+- **ALWAYS** use `python3` for date math (cross-platform, not `date -v` or `date -d`)

package/skills/opencode-rebalancer/lib/config.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Usage: source "$(dirname "$0")/../lib/config.sh"
+
+_CONFIG_HOME="${XDG_CONFIG_HOME:-}"
+if [ -z "$_CONFIG_HOME" ] || [ ! -d "$_CONFIG_HOME" ]; then
+  _CONFIG_HOME="$HOME/.config"
+fi
+
+_DATA_HOME="${XDG_DATA_HOME:-}"
+if [ -z "$_DATA_HOME" ] || [ ! -d "$_DATA_HOME" ]; then
+  _DATA_HOME="$HOME/.local/share"
+fi
+
+REBALANCER_DIR="$_CONFIG_HOME/opencode/rebalancer"
+REBALANCER_ARCHIVE="$REBALANCER_DIR/archive"
+REBALANCER_PLANS="$REBALANCER_DIR/plans.json"
+REBALANCER_CHANGELOG="$REBALANCER_DIR/changelog.md"
+OPENAGENT_CONFIG="$_CONFIG_HOME/opencode/oh-my-openagent.json"
+OPENCODE_DB="$_DATA_HOME/opencode/opencode.db"
+
+unset _CONFIG_HOME _DATA_HOME

package/skills/opencode-rebalancer/lib/dates.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Usage: source "$(dirname "$0")/lib/dates.sh"
+set -euo pipefail
+
+THRESHOLD_30D=$(python3 -c "import time; print(int((time.time() - 30*86400) * 1000))")
+THRESHOLD_7D=$(python3 -c "import time; print(int((time.time() - 7*86400) * 1000))")

package/skills/opencode-rebalancer/scripts/apply.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/../lib/config.sh"
+
+if [ $# -lt 1 ]; then
+  echo "Usage: apply.sh <new-config.json>" >&2
+  exit 1
+fi
+
+NEW_CONFIG="$1"
+TMP="${OPENAGENT_CONFIG}.tmp"
+
+if [ ! -f "$NEW_CONFIG" ]; then
+  echo "ERROR: File not found: $NEW_CONFIG" >&2
+  exit 1
+fi
+
+export APPLY_TMP="$TMP"
+export APPLY_FINAL="$OPENAGENT_CONFIG"
+export APPLY_NEW="$NEW_CONFIG"
+
+python3 <<'PYEOF'
+import json, shutil, sys, os
+
+tmp = os.path.expandvars(os.environ["APPLY_TMP"])
+final = os.path.expandvars(os.environ["APPLY_FINAL"])
+new_config = os.path.expandvars(os.environ["APPLY_NEW"])
+
+try:
+    with open(new_config) as f:
+        data = json.load(f)
+
+    missing = [k for k in ['agents', 'categories'] if k not in data]
+    if missing:
+        print('ERROR: Config missing required keys:', ', '.join(missing))
+        sys.exit(1)
+
+    with open(tmp, 'w') as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write('\n')
+
+    shutil.move(tmp, final)
+    print('Config updated successfully')
+
+except json.JSONDecodeError as e:
+    if os.path.exists(tmp):
+        os.remove(tmp)
+    print('ERROR: Invalid JSON — original config preserved:', e)
+    sys.exit(1)
+except SystemExit:
+    if os.path.exists(tmp):
+        os.remove(tmp)
+    raise
+except Exception as e:
+    if os.path.exists(tmp):
+        os.remove(tmp)
+    print('ERROR:', e)
+    sys.exit(1)
+PYEOF

package/skills/opencode-rebalancer/scripts/archive.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/../lib/config.sh"
+
+if [ ! -f "$OPENAGENT_CONFIG" ]; then
+  echo "ERROR: Config not found at $OPENAGENT_CONFIG" >&2
+  exit 1
+fi
+
+mkdir -p "$REBALANCER_ARCHIVE"
+BACKUP="$REBALANCER_ARCHIVE/oh-my-openagent.$(date +%Y%m%d-%H%M%S).$$.json"
+cp "$OPENAGENT_CONFIG" "$BACKUP"
+echo "Archived: $BACKUP"
+
+ARCHIVE_COUNT=$(find "$REBALANCER_ARCHIVE" -name 'oh-my-openagent.*.json' -type f | wc -l | tr -d ' ')
+if [ "$ARCHIVE_COUNT" -gt 10 ]; then
+  echo "Cleaning up old archives (keeping 10 most recent)..."
+  cd "$REBALANCER_ARCHIVE"
+  DELETE_COUNT=$((ARCHIVE_COUNT - 10))
+  if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    find . -name 'oh-my-openagent.*.json' -type f -exec stat -c '%Y %n' {} \; | sort -n | head -n "$DELETE_COUNT" | cut -d' ' -f2- | xargs rm -f
+  else
+    find . -name 'oh-my-openagent.*.json' -type f -exec stat -f '%m %N' {} \; | sort -n | head -n "$DELETE_COUNT" | cut -d' ' -f2- | xargs rm -f
+  fi
+  echo "Cleanup done."
+fi

package/skills/opencode-rebalancer/scripts/changelog.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/../lib/config.sh"
+
+mkdir -p "$(dirname "$REBALANCER_CHANGELOG")"
+if [ ! -f "$REBALANCER_CHANGELOG" ]; then
+  echo "# Model Rebalancer Changelog" > "$REBALANCER_CHANGELOG"
+fi
+
+{
+  printf '\n## %s\n\n' "$(date '+%Y-%m-%d %H:%M')"
+  cat
+} >> "$REBALANCER_CHANGELOG"
+
+echo "Changelog updated."

package/skills/opencode-rebalancer/scripts/collect-usage.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/../lib/config.sh"
+source "$SCRIPT_DIR/../lib/dates.sh"
+
+if [ -z "${THRESHOLD_30D:-}" ] || [ -z "${THRESHOLD_7D:-}" ]; then
+  echo "ERROR: Failed to compute date thresholds (python3 required)" >&2
+  exit 1
+fi
+
+if [ ! -f "$OPENCODE_DB" ]; then
+  echo "ERROR: SQLite database not found at $OPENCODE_DB" >&2
+  exit 1
+fi
+
+DB="$OPENCODE_DB"
+
+echo "=== Provider Distribution (30d) ==="
+sqlite3 "$DB" <<SQL
+SELECT
+  json_extract(data, '\$.providerID') as provider,
+  COUNT(*) as calls,
+  CASE WHEN (SELECT COUNT(*) FROM message
+    WHERE json_extract(data, '\$.role')='assistant'
+      AND json_extract(data, '\$.time.created') > $THRESHOLD_30D) = 0
+    THEN 0.0
+    ELSE ROUND(COUNT(*) * 100.0 / (
+      SELECT COUNT(*) FROM message
+      WHERE json_extract(data, '\$.role')='assistant'
+        AND json_extract(data, '\$.time.created') > $THRESHOLD_30D
+    ), 1)
+  END as pct
+FROM message
+WHERE json_extract(data, '\$.role')='assistant'
+  AND json_extract(data, '\$.time.created') > $THRESHOLD_30D
+GROUP BY provider ORDER BY calls DESC;
+SQL
+
+echo ""
+echo "=== Provider Distribution (7d) ==="
+sqlite3 "$DB" <<SQL
+SELECT
+  json_extract(data, '\$.providerID') as provider,
+  COUNT(*) as calls,
+  CASE WHEN (SELECT COUNT(*) FROM message
+    WHERE json_extract(data, '\$.role')='assistant'
+      AND json_extract(data, '\$.time.created') > $THRESHOLD_7D) = 0
+    THEN 0.0
+    ELSE ROUND(COUNT(*) * 100.0 / (
+      SELECT COUNT(*) FROM message
+      WHERE json_extract(data, '\$.role')='assistant'
+        AND json_extract(data, '\$.time.created') > $THRESHOLD_7D
+    ), 1)
+  END as pct
+FROM message
+WHERE json_extract(data, '\$.role')='assistant'
+  AND json_extract(data, '\$.time.created') > $THRESHOLD_7D
+GROUP BY provider ORDER BY calls DESC;
+SQL
+
+echo ""
+echo "=== Per-Agent Per-Provider Matrix (30d) ==="
+sqlite3 "$DB" <<SQL
+SELECT
+  json_extract(data, '\$.providerID') as provider,
+  json_extract(data, '\$.agent') as agent,
+  COUNT(*) as calls
+FROM message
+WHERE json_extract(data, '\$.role')='assistant'
+  AND json_extract(data, '\$.time.created') > $THRESHOLD_30D
+GROUP BY provider, agent ORDER BY provider, calls DESC;
+SQL
+
+echo ""
+echo "=== Agent Usage Ratio (30d) ==="
+sqlite3 "$DB" <<SQL
+SELECT
+  json_extract(data, '\$.agent') as agent,
+  COUNT(*) as total,
+  CASE WHEN (SELECT COUNT(*) FROM message
+    WHERE json_extract(data, '\$.role')='assistant'
+      AND json_extract(data, '\$.time.created') > $THRESHOLD_30D) = 0
+    THEN 0.0
+    ELSE ROUND(COUNT(*) * 100.0 / (
+      SELECT COUNT(*) FROM message
+      WHERE json_extract(data, '\$.role')='assistant'
+        AND json_extract(data, '\$.time.created') > $THRESHOLD_30D
+    ), 1)
+  END as pct
+FROM message
+WHERE json_extract(data, '\$.role')='assistant'
+  AND json_extract(data, '\$.time.created') > $THRESHOLD_30D
+GROUP BY agent ORDER BY total DESC;
+SQL
+
+echo ""
+echo "=== Available Models ==="
+opencode models 2>/dev/null || echo "(opencode models unavailable — skip model ID validation)"

package/templates/plans.json

@@ -0,0 +1,9 @@
+{
+  "last_updated": null,
+  "needs_update": true,
+  "providers": {},
+  "strategy": {
+    "summary": "",
+    "rules": []
+  }
+}