habithive-code 0.2.0

package/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: karpathy-guidelines
+description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
+license: MIT
+---
+
+<!--
+  Bundled by habithive-code, unmodified, under the MIT License.
+  Source:  andrej-karpathy-skills by forrestchang
+           https://github.com/forrestchang/andrej-karpathy-skills
+  Derived from Andrej Karpathy's observations on LLM coding pitfalls.
+  See habithive-code THIRD-PARTY-NOTICES.md for the full license text.
+-->
+
+# Karpathy Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

package/src/config.js

@@ -0,0 +1,97 @@
+// habithive-code — opencode config wiring + mode switching.
+//
+// Surgically toggles oh-my-opencode in the opencode config while ALWAYS keeping
+// the habithive plugin loaded, so /habithive-mode works in both modes:
+//   complex: oh-my-opencode ON  (opencode.jsonc + tui.json) + habithive (tui.json)
+//   simple : oh-my-opencode OFF                              + habithive (tui.json)
+// Preserves every other plugin/key. Atomic writes. Idempotent.
+//
+// We DEPEND on oh-my-opencode via npm (never bundle its code) and pin a tested
+// version. Bump OMO_SPEC in a new habithive-code release after re-testing.
+
+import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+export const OMO_SPEC = "oh-my-openagent@4.19.1"; // pinned, tested version
+export const CONFIG_DIR = join(homedir(), ".config", "opencode");
+const OPENCODE_JSONC = join(CONFIG_DIR, "opencode.jsonc");
+const OPENCODE_JSON = join(CONFIG_DIR, "opencode.json");
+const TUI_JSON = join(CONFIG_DIR, "tui.json");
+
+// file:// URL to this package's plugin entry (works when installed globally or local).
+export const HABITHIVE_PLUGIN_URL = new URL("./plugin.js", import.meta.url).href;
+
+const isOmo = (e) => typeof e === "string" && /oh-my-open(agent|code)/.test(e);
+const isHabithive = (e) => typeof e === "string" && e.includes("habithive");
+
+function readJson(path) {
+  try {
+    const raw = readFileSync(path, "utf8");
+    return JSON.parse(raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, ""));
+  } catch { return null; }
+}
+function writeAtomic(path, obj) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  renameSync(tmp, path);
+}
+const dropOmo = (arr) => (arr || []).filter((e) => !isOmo(e));
+const dropHabithive = (arr) => (arr || []).filter((e) => !isHabithive(e));
+const ensure = (arr, v) => (arr.includes(v) ? arr : [...arr, v]);
+
+// mode: "simple" | "complex". Idempotent. Returns a short summary.
+export function setMode(mode) {
+  const complex = mode === "complex";
+
+  // server plugins (opencode.jsonc): toggle oh-my-opencode only (habithive is TUI-only)
+  {
+    const c = readJson(OPENCODE_JSONC) || { "$schema": "https://opencode.ai/config.json" };
+    let arr = dropOmo(Array.isArray(c.plugin) ? c.plugin : []);
+    if (complex) arr = ensure(arr, OMO_SPEC);
+    c.plugin = arr;
+    writeAtomic(OPENCODE_JSONC, c);
+  }
+  // safety: keep opencode.json in sync only if it already declares plugins
+  if (existsSync(OPENCODE_JSON)) {
+    const c = readJson(OPENCODE_JSON);
+    if (c && Array.isArray(c.plugin)) {
+      let arr = dropOmo(c.plugin);
+      if (complex) arr = ensure(arr, OMO_SPEC);
+      c.plugin = arr;
+      writeAtomic(OPENCODE_JSON, c);
+    }
+  }
+  // tui plugins (tui.json): ALWAYS keep habithive; toggle oh-my-opencode
+  {
+    const c = readJson(TUI_JSON) || {};
+    let arr = dropHabithive(dropOmo(Array.isArray(c.plugin) ? c.plugin : []));
+    arr = ensure(arr, HABITHIVE_PLUGIN_URL);
+    if (complex) arr = ensure(arr, OMO_SPEC);
+    c.plugin = arr;
+    writeAtomic(TUI_JSON, c);
+  }
+  return `config set to ${mode} mode`;
+}
+
+// Add an MCP server to the opencode config if not already present (in either
+// opencode.jsonc or opencode.json). Non-destructive; preserves other mcp entries.
+export function ensureMcp(name, spec) {
+  const inJson = (() => { const c = readJson(OPENCODE_JSON); return c && c.mcp && c.mcp[name]; })();
+  const c = readJson(OPENCODE_JSONC) || { "$schema": "https://opencode.ai/config.json" };
+  if ((c.mcp && c.mcp[name]) || inJson) return false; // already configured somewhere
+  c.mcp = { ...(c.mcp || {}), [name]: spec };
+  writeAtomic(OPENCODE_JSONC, c);
+  return true;
+}
+
+// Is oh-my-opencode currently wired (i.e., are we in complex on disk)?
+export function currentMode() {
+  const c = readJson(OPENCODE_JSONC);
+  return c && Array.isArray(c.plugin) && c.plugin.some(isOmo) ? "complex" : "simple";
+}
+
+export const PATHS = { OPENCODE_JSONC, OPENCODE_JSON, TUI_JSON, CONFIG_DIR };
+export { fileURLToPath };

package/src/core.js

@@ -0,0 +1,242 @@
+// habithive-code — core engine (pure Node/Bun ESM, no opencode deps).
+//
+// Owns:
+//   1. The model-tree store + resolver, compiled into oh-my-opencode's
+//      oh-my-openagent.json (subagent/category models). Applied on next launch.
+//   2. The on-screen (primary agent) model = opencode's picker state model.json.
+//   3. The mode marker used to hand an in-app simple/complex switch to the CLI.
+//
+// Model resolution tree (most specific wins):
+//   agent override  >  category override  >  "all" override  >  baseline
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, copyFileSync, rmSync } from "node:fs";
+
+const HOME = homedir();
+export const CONFIG_DIR = join(HOME, ".config", "opencode");
+export const OMO_CONFIG = join(CONFIG_DIR, "oh-my-openagent.json");
+export const STORE_DIR = join(HOME, ".habithive");
+export const STORE_FILE = join(STORE_DIR, "overrides.json");
+export const BASELINE_FILE = join(STORE_DIR, "baseline.json");
+export const OMO_BACKUP = join(STORE_DIR, "oh-my-openagent.first-backup.json");
+export const MODE_MARKER = join(STORE_DIR, "next-mode");
+export const SESSION_MARKER = join(STORE_DIR, "next-session");
+// opencode's native model-picker state — recent[0] is the current on-screen model.
+export const MODEL_STATE = join(HOME, ".local", "state", "opencode", "model.json");
+
+// Authoritative from oh-my-opencode's BuiltinCategoryNameSchema — 8 tiers.
+export const KNOWN_CATEGORIES = [
+  "ultrabrain", "deep", "quick", "visual-engineering",
+  "artistry", "writing", "unspecified-low", "unspecified-high",
+];
+
+// Authoritative agent registry (BuiltinAgentNameSchema + live /agent modes).
+// MAIN = primary mode (Tab-between; use the on-screen/UI-selected model).
+// SUB  = subagent mode (spawned via task; own model from oh-my-openagent.json).
+export const MAIN_AGENTS = [
+  { key: "sisyphus",   label: "Sisyphus — ultraworker" },
+  { key: "prometheus", label: "Prometheus — plan builder" },
+  { key: "atlas",      label: "Atlas — plan executor" },
+  { key: "hephaestus", label: "Hephaestus — deep (GPT-only)" },
+];
+export const SUB_AGENTS = [
+  { key: "oracle",            label: "Oracle — deep reasoning / debugging" },
+  { key: "explore",           label: "Explore — codebase search" },
+  { key: "librarian",         label: "Librarian — external docs" },
+  { key: "multimodal-looker", label: "Multimodal-looker — images / visual" },
+  { key: "metis",             label: "Metis — plan consultant" },
+  { key: "momus",             label: "Momus — plan critic" },
+  { key: "sisyphus-junior",   label: "Sisyphus-Junior — worker" },
+];
+export const MAIN_KEYS = MAIN_AGENTS.map((a) => a.key);
+export const ALL_AGENTS = [...MAIN_AGENTS, ...SUB_AGENTS].map((a) => a.key);
+export function isMainAgent(key) { return MAIN_KEYS.includes(key); }
+
+export function defaultStore() {
+  return { version: 1, modelOverrides: { all: null, categories: {}, agents: {} } };
+}
+
+function readJson(path, fallback) {
+  try {
+    if (!existsSync(path)) return fallback;
+    const raw = readFileSync(path, "utf8");
+    const stripped = raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+    return JSON.parse(stripped);
+  } catch { return fallback; }
+}
+
+function writeJsonAtomic(path, obj) {
+  mkdirSync(STORE_DIR, { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${globalThis.performance ? Math.floor(performance.now()) : "t"}`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  renameSync(tmp, path);
+}
+
+export function loadStore() {
+  const s = readJson(STORE_FILE, null);
+  if (!s) return defaultStore();
+  return {
+    version: s.version || 1,
+    modelOverrides: {
+      all: s.modelOverrides?.all ?? null,
+      categories: { ...(s.modelOverrides?.categories || {}) },
+      agents: { ...(s.modelOverrides?.agents || {}) },
+    },
+  };
+}
+
+export function saveStore(store) { writeJsonAtomic(STORE_FILE, store); }
+
+export function ensureBaseline() {
+  mkdirSync(STORE_DIR, { recursive: true });
+  if (!existsSync(BASELINE_FILE)) {
+    const current = readJson(OMO_CONFIG, {});
+    writeJsonAtomic(BASELINE_FILE, current);
+    try { if (existsSync(OMO_CONFIG)) copyFileSync(OMO_CONFIG, OMO_BACKUP); } catch {}
+  }
+  return readJson(BASELINE_FILE, {});
+}
+
+export function loadBaseline() { return readJson(BASELINE_FILE, {}); }
+
+// ---- resolution ----------------------------------------------------------
+
+export function resolveCategoryModel(store, baseline, cat) {
+  return (
+    store.modelOverrides.categories[cat] ??
+    store.modelOverrides.all ??
+    baseline?.categories?.[cat]?.model ??
+    null
+  );
+}
+
+function hasAnyCategoryOverride(store) {
+  return Object.keys(store.modelOverrides.categories || {}).length > 0;
+}
+
+// Compile store + baseline -> oh-my-openagent.json content. Non-destructive.
+export function compileOmoConfig(store, baseline) {
+  const out = structuredClone(baseline || {});
+  out.categories = { ...(out.categories || {}) };
+  out.agents = { ...(out.agents || {}) };
+
+  for (const c of new Set([...KNOWN_CATEGORIES, ...Object.keys(out.categories)])) {
+    const model = resolveCategoryModel(store, baseline, c);
+    if (model) out.categories[c] = { ...(out.categories[c] || {}), model };
+  }
+
+  const hasCat = hasAnyCategoryOverride(store);
+  const hasAll = store.modelOverrides.all != null;
+  for (const a of new Set([...ALL_AGENTS, ...Object.keys(out.agents)])) {
+    const leaf = store.modelOverrides.agents[a];
+    if (leaf) {
+      out.agents[a] = { ...(out.agents[a] || {}), model: leaf };
+    } else if (hasCat) {
+      // category overrides active: drop the agent model, let oh-my-opencode cascade from its category
+      if (out.agents[a] && "model" in out.agents[a]) {
+        const { model, ...rest } = out.agents[a];
+        if (Object.keys(rest).length) out.agents[a] = rest; else delete out.agents[a];
+      }
+    } else if (hasAll) {
+      out.agents[a] = { ...(out.agents[a] || {}), model: store.modelOverrides.all };
+    } else {
+      const base = baseline?.agents?.[a];
+      if (base) out.agents[a] = structuredClone(base); else delete out.agents[a];
+    }
+  }
+  return out;
+}
+
+export function applyStore(store) {
+  try {
+    const baseline = ensureBaseline();
+    if (!baseline || !baseline.agents || Object.keys(baseline.agents).length === 0) {
+      return { ok: false, error: "baseline not captured (oh-my-openagent.json empty/missing); refusing to write" };
+    }
+    writeJsonAtomic(OMO_CONFIG, compileOmoConfig(store, baseline));
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: String(e?.message || e) };
+  }
+}
+
+// ---- mutations -----------------------------------------------------------
+
+export function setModelOverride(store, level, target, modelId) {
+  if (level === "all") store.modelOverrides.all = modelId || null;
+  else if (level === "category") store.modelOverrides.categories[target] = modelId;
+  else if (level === "agent") store.modelOverrides.agents[target] = modelId;
+  return store;
+}
+
+export function clearModelOverride(store, level, target) {
+  if (level === "all") store.modelOverrides.all = null;
+  else if (level === "category") delete store.modelOverrides.categories[target];
+  else if (level === "agent") delete store.modelOverrides.agents[target];
+  return store;
+}
+
+export function effectiveModel(store, baseline, level, target) {
+  if (level === "all") return store.modelOverrides.all ?? null;
+  if (level === "category") return resolveCategoryModel(store, baseline, target);
+  if (level === "agent") return store.modelOverrides.agents[target] ?? baseline?.agents?.[target]?.model ?? null;
+  return null;
+}
+
+// ---- on-screen (primary) model = model.json recent[0] --------------------
+
+function splitModelId(idStr) {
+  const i = String(idStr).indexOf("/");
+  if (i < 0) return null;
+  return { providerID: idStr.slice(0, i), modelID: idStr.slice(i + 1) };
+}
+
+export function currentMainModel() {
+  try {
+    const s = JSON.parse(readFileSync(MODEL_STATE, "utf8"));
+    const m = s?.recent?.[0];
+    return m ? `${m.providerID}/${m.modelID}` : null;
+  } catch { return null; }
+}
+
+export function setMainModel(idStr) {
+  try {
+    const parts = splitModelId(idStr);
+    if (!parts) return { ok: false, error: "bad model id (expected provider/model)" };
+    let state = {};
+    try { state = JSON.parse(readFileSync(MODEL_STATE, "utf8")); } catch {}
+    if (!Array.isArray(state.recent)) state.recent = [];
+    state.recent = state.recent.filter((m) => !(m.providerID === parts.providerID && m.modelID === parts.modelID));
+    state.recent.unshift(parts);
+    mkdirSync(join(HOME, ".local", "state", "opencode"), { recursive: true });
+    const tmp = `${MODEL_STATE}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(state), "utf8");
+    renameSync(tmp, MODEL_STATE);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: String(e?.message || e) };
+  }
+}
+
+// ---- mode marker (in-app switch handshake with the `habithive` launcher) ------
+
+export function writeNextMode(mode, session) {
+  mkdirSync(STORE_DIR, { recursive: true });
+  writeFileSync(MODE_MARKER, `${mode}\n`, "utf8");
+  // Record the exact session to reopen so the relaunch returns HERE. A new/empty
+  // session has no id yet → no marker → the launcher opens a fresh session
+  // (never --continue, which would reopen the last saved conversation).
+  if (session) writeFileSync(SESSION_MARKER, `${session}\n`, "utf8");
+  else { try { rmSync(SESSION_MARKER, { force: true }); } catch {} }
+}
+export function readNextMode() {
+  try { return existsSync(MODE_MARKER) ? readFileSync(MODE_MARKER, "utf8").trim() : null; } catch { return null; }
+}
+export function readNextSession() {
+  try { return existsSync(SESSION_MARKER) ? readFileSync(SESSION_MARKER, "utf8").trim() : null; } catch { return null; }
+}
+export function clearNextMode() {
+  try { rmSync(MODE_MARKER, { force: true }); } catch {}
+  try { rmSync(SESSION_MARKER, { force: true }); } catch {}
+}

package/src/logo.js

@@ -0,0 +1,37 @@
+// habithive-code — home-screen wordmark in opencode's TUI.
+//
+// Renders a big <ascii_font> "HABITHIVE" (block font, clean outline) into the
+// `home_logo` slot. A @opentui/core renderable is a valid slot node, so there's
+// no JSX build step. We probe-construct once at register time (inside try/catch,
+// OUTSIDE opencode's render loop) so any failure aborts gracefully instead of
+// crashing the home screen — the slot is only registered if the probe succeeds.
+
+const TEXT = "habithive";     // ascii_font uppercases it
+const FONT = "block";     // tiny | slick | block | huge | shade | grid | pallet
+const COLOR = "#7c3aed";  // violet
+
+export async function registerLogo(api) {
+  try {
+    if (!api || !api.slots || typeof api.slots.register !== "function") return;
+    const rnd = api.renderer;
+    let rctx = null;
+    try { rctx = (rnd && rnd.renderContext) || (rnd && rnd.root && rnd.root.ctx) || null; } catch {}
+    if (!rctx) return;
+
+    let AsciiFont;
+    try { AsciiFont = (await import("@opentui/core")).ASCIIFontRenderable; } catch { return; }
+    if (typeof AsciiFont !== "function") return;
+
+    const make = () => new AsciiFont(rctx, { text: TEXT, font: FONT, color: COLOR });
+
+    // Prove construction works before registering (a throw here is caught → no crash).
+    try {
+      const probe = make();
+      if (probe && typeof probe.destroyRecursively === "function") probe.destroyRecursively();
+    } catch { return; }
+
+    api.slots.register({ slots: { home_logo: () => make() } });
+  } catch {
+    // never break the home screen
+  }
+}

package/src/plugin.js

@@ -0,0 +1,217 @@
+// habithive-code — opencode TUI plugin. Loaded in complex mode (oh-my-opencode on).
+// Plain ESM, no JSX: host UI components are plain functions from api.ui.*, so
+// dialogs are nested calls. Everything is wrapped so it can never throw at init.
+//
+// Commands:
+//   /habithive        umbrella menu (set model / switch mode / reset)
+//   /model        nested model tree: level (main / all / group / agent / category) -> model
+//   /habithive-mode   switch complex <-> simple: queues a marker + quits (app.exit);
+//                 the `habithive` launcher relaunches in the queued mode, same session.
+
+import {
+  loadStore, saveStore, applyStore, loadBaseline, ensureBaseline,
+  setModelOverride, clearModelOverride, effectiveModel, writeNextMode,
+  setMainModel, currentMainModel, isMainAgent,
+  KNOWN_CATEGORIES, MAIN_AGENTS, SUB_AGENTS,
+} from "./core.js";
+import { registerLogo } from "./logo.js";
+
+function listModels(api) {
+  const out = [];
+  const providers = (api && api.state && api.state.provider) || [];
+  for (const p of providers) {
+    const pid = p?.id || p?.providerID || p?.name;
+    if (!pid) continue;
+    const models = p.models;
+    const entries = Array.isArray(models) ? models.map((m) => [m?.id || m?.modelID, m]) : Object.entries(models || {});
+    for (const [mid, m] of entries) {
+      if (!mid) continue;
+      out.push({ id: `${pid}/${mid}`, providerID: pid, label: `${pid}/${mid}`, name: (m && (m.name || m.id)) || mid });
+    }
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+}
+
+function toast(api, message, variant = "info") {
+  try { api.ui.toast({ message, variant }); } catch {}
+}
+
+// Queue a mode switch and quit; the launcher relaunches (same session, --continue).
+async function switchMode(api, mode) {
+  // Only target a REAL session (one with messages). A brand-new/empty session has
+  // no persisted id yet, so we leave it null and the launcher opens a fresh session.
+  let sessionID = null;
+  try {
+    const cur = api?.route?.current;
+    if (cur && cur.name === "session" && cur.params && cur.params.sessionID) {
+      const id = cur.params.sessionID;
+      const msgs = api?.state?.session?.messages?.(id);
+      if (msgs && msgs.length > 0) sessionID = id;
+    }
+  } catch {}
+  try { writeNextMode(mode, sessionID); }
+  catch (e) { toast(api, `could not queue switch: ${String(e?.message || e)}`, "error"); return; }
+  toast(api, `Switching to ${mode.toUpperCase()} — reopening this session…`, "info");
+  let exited = false;
+  for (const cmd of ["app.exit", "app.quit", "quit", "exit"]) {
+    try { await api.keymap.dispatchCommand(cmd); exited = true; break; } catch {}
+  }
+  if (!exited) toast(api, `Quit opencode — it relaunches in ${mode} mode (habithive launcher).`, "warning");
+}
+
+// ---- model tree ----------------------------------------------------------
+
+function openModelPicker(api, level, target) {
+  const models = listModels(api);
+  const current = level === "main" ? currentMainModel()
+    : (level === "agent" || level === "category") ? effectiveModel(loadStore(), loadBaseline(), level, target)
+    : null;
+  const label = level === "main" ? "MAIN agent (this screen)"
+    : level === "all" ? "ALL (on-screen + subagents)"
+    : level === "main-group" ? "ALL main agents"
+    : level === "sub-group" ? "ALL sub agents"
+    : `${level}: ${target}`;
+
+  const options = [
+    { title: "↺ Clear override (use default)", value: { clear: true }, category: "Actions" },
+    ...models.map((m) => ({
+      title: m.id + (m.id === current ? "  ·current" : ""),
+      value: { id: m.id }, description: m.name, category: m.providerID,
+    })),
+  ];
+
+  api.ui.dialog.replace(() =>
+    api.ui.DialogSelect({
+      title: `habithive · set model for ${label}`,
+      placeholder: "filter models…",
+      options, current,
+      onSelect: async (opt) => {
+        const clear = !!opt.value.clear;
+        const id = opt.value.id;
+
+        if (level === "main") {
+          if (clear) { toast(api, "main agent: pick a model (nothing to clear)", "warning"); return; }
+          const r = setMainModel(id);
+          api.ui.dialog.clear();
+          if (!r.ok) { toast(api, `main set failed: ${r.error}`, "error"); return; }
+          toast(api, `${label} → ${id} · applying (reopening session)…`, "info");
+          await switchMode(api, "complex");
+          return;
+        }
+
+        const s = loadStore();
+        const setKeys = (keys) => keys.forEach((k) => clear ? clearModelOverride(s, "agent", k) : setModelOverride(s, "agent", k, id));
+        let touchesMainScreen = false;
+
+        if (level === "main-group") { setKeys(MAIN_AGENTS.map((a) => a.key)); touchesMainScreen = true; }
+        else if (level === "sub-group") { setKeys(SUB_AGENTS.map((a) => a.key)); }
+        else if (level === "all") { clear ? clearModelOverride(s, "all") : setModelOverride(s, "all", null, id); touchesMainScreen = true; }
+        else {
+          clear ? clearModelOverride(s, level, target) : setModelOverride(s, level, target, id);
+          if (level === "agent" && isMainAgent(target)) touchesMainScreen = true;
+        }
+
+        saveStore(s);
+        const r = applyStore(s);
+        if (!clear && touchesMainScreen) setMainModel(id);
+        api.ui.dialog.clear();
+        if (!r.ok) { toast(api, `apply failed: ${r.error}`, "error"); return; }
+        toast(api, `${label} → ${clear ? "default" : id} · applying (reopening session)…`, "info");
+        await switchMode(api, "complex");
+      },
+    }),
+  );
+}
+
+function openLevelPicker(api) {
+  ensureBaseline();
+  const store = loadStore();
+  const baseline = loadBaseline();
+  const fmt = (lvl, tgt) => {
+    const m = lvl === "main" ? currentMainModel() : effectiveModel(store, baseline, lvl, tgt);
+    return m ? `→ ${m}` : "→ (default)";
+  };
+  const groupModel = (keys) => {
+    const uniq = [...new Set(keys.map((k) => effectiveModel(store, baseline, "agent", k)))];
+    return uniq.length === 1 ? (uniq[0] ? `→ all: ${uniq[0]}` : "→ (default)") : "→ (mixed)";
+  };
+  const options = [
+    { title: "Main agent — this screen", description: fmt("main"), value: { level: "main" }, category: "Quick" },
+    { title: "ALL — on-screen + every subagent + tier", description: fmt("all"), value: { level: "all" }, category: "Quick" },
+
+    { title: "★ All main agents (set together)", description: groupModel(MAIN_AGENTS.map((a) => a.key)), value: { level: "main-group" }, category: "Main agents (primary)" },
+    ...MAIN_AGENTS.map((a) => ({ title: a.label, description: fmt("agent", a.key), value: { level: "agent", target: a.key }, category: "Main agents (primary)" })),
+
+    { title: "★ All sub agents (set together)", description: groupModel(SUB_AGENTS.map((a) => a.key)), value: { level: "sub-group" }, category: "Subagents" },
+    ...SUB_AGENTS.map((a) => ({ title: a.label, description: fmt("agent", a.key), value: { level: "agent", target: a.key }, category: "Subagents" })),
+
+    ...KNOWN_CATEGORIES.map((c) => ({ title: c, description: fmt("category", c), value: { level: "category", target: c }, category: "Categories (tiers)" })),
+  ];
+  api.ui.dialog.replace(() =>
+    api.ui.DialogSelect({
+      title: "habithive · set model — pick a level (most-specific wins)",
+      placeholder: "filter…", options,
+      onSelect: (opt) => openModelPicker(api, opt.value.level, opt.value.target),
+    }),
+  );
+}
+
+function openModeMenu(api) {
+  api.ui.dialog.replace(() =>
+    api.ui.DialogSelect({
+      title: "habithive · mode (you are in COMPLEX mode)",
+      options: [
+        { title: "→ Simple mode (vanilla opencode, fast)", value: "simple", description: "quits & relaunches vanilla, same session" },
+        { title: "→ Complex mode (relaunch to apply model changes)", value: "complex", description: "quits & relaunches full, same session" },
+      ],
+      onSelect: (opt) => { api.ui.dialog.clear(); switchMode(api, opt.value); },
+    }),
+  );
+}
+
+function openUmbrella(api) {
+  api.ui.dialog.replace(() =>
+    api.ui.DialogSelect({
+      title: "habithive-code",
+      options: [
+        { title: "Set model (main / all / groups / agent / tier)", value: "model" },
+        { title: "Switch mode (simple / complex)", value: "mode" },
+        { title: "Reset all model overrides", value: "reset" },
+      ],
+      onSelect: (opt) => {
+        if (opt.value === "model") openLevelPicker(api);
+        else if (opt.value === "mode") openModeMenu(api);
+        else if (opt.value === "reset") {
+          const s = loadStore();
+          s.modelOverrides = { all: null, categories: {}, agents: {} };
+          saveStore(s);
+          const r = applyStore(s);
+          api.ui.dialog.clear();
+          toast(api, r.ok ? "overrides cleared (baseline restored) · relaunch to apply" : `reset failed: ${r.error}`, r.ok ? "success" : "error");
+        }
+      },
+    }),
+  );
+}
+
+const HabithiveTui = async (api) => {
+  try {
+    const reg = api && api.command && api.command.register;
+    if (typeof reg !== "function") {
+      try { api.ui.toast({ message: "habithive-code: command API unavailable", variant: "warning" }); } catch {}
+      return;
+    }
+    reg(() => [
+      { title: "habithive-code", value: "habithive.menu", description: "model tree + mode switch", category: "habithive-code", slash: { name: "habithive", aliases: ["habithive-code"] }, onSelect: () => openUmbrella(api) },
+      { title: "habithive · set model", value: "habithive.model", description: "set model by level (main / all / groups / agent / tier)", category: "habithive-code", slash: { name: "model", aliases: ["habithivemodel"] }, onSelect: () => openLevelPicker(api) },
+      { title: "habithive · switch mode", value: "habithive.mode", description: "complex <-> simple (relaunch, same session)", category: "habithive-code", slash: { name: "habithive-mode", aliases: ["habithivemode"] }, onSelect: () => openModeMenu(api) },
+    ]);
+    registerLogo(api); // v2 — HABITHIVE wordmark in home_logo (self-guarded, test-constructed)
+  } catch (e) {
+    try { api.ui.toast({ message: `habithive-code init failed: ${String(e?.message || e)}`, variant: "error" }); } catch {}
+  }
+};
+
+export default { id: "habithive-code", tui: HabithiveTui };
+export const HabithivePlugin = HabithiveTui;