opencode-agent-modes 0.1.2 → 0.3.0

package/README.md

@@ -147,7 +147,42 @@ To add a custom preset (e.g., "premium"):
 
 3. Restart opencode to apply changes.
 
-## Notes
+> [!INFO]
+> - Changes require an opencode restart to take effect
+> - Custom mode presets can be added by editing the configuration file
+> - Built-in command files (`mode-performance.md`, `mode-economy.md`, etc.)
+>   are overwritten on every plugin startup. Do not modify them directly.
+> - Custom command files (e.g., `mode-premium.md`) are not affected by
+>   this overwrite and will persist across restarts.
 
-- Changes require an opencode restart to take effect
-- Custom mode presets can be added by editing the configuration file
+## Development
+
+This project uses [Bun](https://bun.sh/) as the runtime and package manager.
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) v1.0 or later
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/j4rviscmd/opencode-agent-modes.git
+cd opencode-agent-modes
+
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+
+# Lint & format
+bun run lint
+bun run format
+
+# Build
+bun run build
+```

package/dist/config/guards.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Type guard utilities for configuration processing.
+ */
+/**
+ * Checks if a value is a plain object (not null, not array).
+ *
+ * This is used throughout the codebase to distinguish between
+ * hierarchical structures and leaf values when processing
+ * configurations.
+ *
+ * @param obj - Value to check
+ * @returns True if the value is a plain object
+ */
+export declare function isObject(obj: unknown): obj is Record<string, unknown>;

package/dist/config/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.ts';
+export * from './guards.ts';
 export * from './loader.ts';
 export * from './initializer.ts';
 export * from './command-installer.ts';

package/dist/config/initializer.d.ts

@@ -1,10 +1,46 @@
 import type { ModeSwitcherConfig } from './types.ts';
 /**
- * Initialize the plugin configuration if it doesn't exist
- * @returns The configuration (existing or newly created)
+ * Initializes the plugin configuration if it doesn't exist.
+ *
+ * This function performs the following steps:
+ * 1. Checks if a configuration file already exists
+ * 2. If exists, loads and returns it
+ * 3. If not, creates a new configuration by:
+ *    - Building a performance preset from current settings
+ *    - Building an economy preset with free models
+ *    - Setting default mode to "performance"
+ *    - Saving the configuration to disk
+ *
+ * This is called on plugin startup to ensure a valid configuration
+ * is always available.
+ *
+ * @returns Promise resolving to the configuration (existing or newly created)
+ * @throws {Error} If configuration creation or file I/O fails
+ * @example
+ * ```typescript
+ * const config = await initializeConfig();
+ * console.log(config.currentMode); // "performance"
+ * ```
  */
 export declare function initializeConfig(): Promise<ModeSwitcherConfig>;
 /**
- * Ensure configuration is valid and has required presets
+ * Validates that a configuration object is well-formed and has required presets.
+ *
+ * This function performs the following checks:
+ * - `currentMode` field is present and non-empty
+ * - `presets` object exists and contains at least one preset
+ * - A preset exists for the current mode
+ *
+ * @param config - The configuration object to validate
+ * @returns True if configuration is valid, false otherwise
+ * @example
+ * ```typescript
+ * const config = await loadPluginConfig();
+ * if (validateConfig(config)) {
+ *   console.log('Configuration is valid');
+ * } else {
+ *   console.error('Invalid configuration detected');
+ * }
+ * ```
  */
 export declare function validateConfig(config: ModeSwitcherConfig): boolean;

package/dist/config/loader.d.ts

@@ -1,4 +1,4 @@
-import type { ModeSwitcherConfig, OpencodeConfig, OhMyOpencodeConfig } from './types.ts';
+import type { ModeSwitcherConfig, OhMyOpencodeConfig, OpencodeConfig } from './types.ts';
 /**
  * Expands tilde (~) notation to the user's home directory path.
  *

package/dist/config/types.d.ts

@@ -1,17 +1,38 @@
 /**
- * Agent preset configuration for a single agent
+ * Generic model configuration for any agent.
+ *
+ * This interface is intentionally flexible to support arbitrary
+ * properties beyond just `model` and `variant`.
  */
-export interface AgentPreset {
-    model: string;
+export interface ModelConfig {
+    model?: string;
+    variant?: string;
+    [key: string]: unknown;
 }
 /**
- * Mode preset containing configurations for both opencode and oh-my-opencode agents
+ * Hierarchical preset structure supporting arbitrary nesting.
+ *
+ * This type recursively represents the configuration structure for
+ * both opencode and oh-my-opencode, supporting any level of nesting
+ * (e.g., agents/categories, future sections).
+ *
+ * Note: This type alias has a circular reference by design to support
+ * recursive structures. The TypeScript compiler warning about this
+ * can be safely ignored.
+ */
+export type HierarchicalPreset = Record<string, ModelConfig | HierarchicalPreset>;
+/**
+ * Mode preset containing configurations for both opencode and oh-my-opencode agents.
+ *
+ * Both opencode and oh-my-opencode use the same HierarchicalPreset type,
+ * allowing them to have arbitrary nested structures that are handled
+ * uniformly by recursive merge functions.
  */
 export interface ModePreset {
     description: string;
     model?: string;
-    opencode: Record<string, AgentPreset>;
-    'oh-my-opencode': Record<string, AgentPreset>;
+    opencode: HierarchicalPreset;
+    'oh-my-opencode': HierarchicalPreset;
 }
 /**
  * Main configuration for the mode switcher plugin
@@ -23,6 +44,9 @@ export interface ModeSwitcherConfig {
 }
 /**
  * OpenCode agent configuration structure in opencode.json
+ *
+ * @deprecated This type is kept for backward compatibility but may not
+ * accurately represent the actual structure. Use ModelConfig directly.
  */
 export interface OpencodeAgentConfig {
     model?: string;
@@ -31,17 +55,21 @@ export interface OpencodeAgentConfig {
 }
 /**
  * OpenCode configuration file structure
+ *
+ * Supports arbitrary properties beyond the documented ones.
  */
 export interface OpencodeConfig {
     model?: string;
-    agent?: Record<string, OpencodeAgentConfig>;
+    agent?: HierarchicalPreset;
     [key: string]: unknown;
 }
 /**
  * Oh-my-opencode configuration file structure
+ *
+ * Supports arbitrary properties and nested structures like
+ * agents, categories, and any future sections.
  */
 export interface OhMyOpencodeConfig {
-    agents?: Record<string, AgentPreset>;
     [key: string]: unknown;
 }
 /**

package/dist/index.d.ts

@@ -1,9 +1,34 @@
-import type { Plugin } from "@opencode-ai/plugin";
 /**
- * OpenCode Agent Mode Switcher Plugin
+ * @fileoverview OpenCode Agent Mode Switcher Plugin.
  *
- * Allows switching between different agent mode presets (e.g., performance vs economy)
- * that configure which AI models are used for each agent type.
+ * This plugin provides tools for managing agent mode presets in OpenCode.
+ * It allows users to switch between different configurations (e.g., performance
+ * vs economy modes) that determine which AI models are used for each agent type.
+ *
+ * @module index
+ */
+import type { Plugin } from '@opencode-ai/plugin';
+/**
+ * OpenCode Agent Mode Switcher Plugin.
+ *
+ * Provides tools for switching between agent mode presets (e.g., performance
+ * vs economy) that configure which AI models are used for each agent type.
+ * The plugin initializes on startup by loading configurations and copying
+ * slash command files to the OpenCode command directory.
+ *
+ * @param params - Plugin initialization parameters
+ * @param params.client - OpenCode client for SDK interactions
+ * @returns Plugin object containing mode management tools
+ *
+ * @example
+ * ```typescript
+ * // Plugin is automatically loaded by OpenCode
+ * // Users can then use slash commands:
+ * // /mode-performance
+ * // /mode-economy
+ * // /mode-status
+ * // /mode-list
+ * ```
  */
 declare const modeSwitcherPlugin: Plugin;
 export default modeSwitcherPlugin;

package/dist/index.js

@@ -12330,6 +12330,12 @@ function tool(input) {
   return input;
 }
 tool.schema = exports_external;
+// src/config/types.ts
+var DEFAULT_ECONOMY_MODEL = "opencode/glm-4.7-free";
+// src/config/guards.ts
+function isObject2(obj) {
+  return typeof obj === "object" && obj !== null && !Array.isArray(obj);
+}
 // src/config/loader.ts
 import { homedir } from "os";
 import { join } from "path";
@@ -13790,43 +13796,32 @@ async function saveOhMyOpencodeConfig(config2) {
   await saveJsonFile(getOhMyOpencodeConfigPath(), config2);
 }
 async function pluginConfigExists() {
-  const file2 = Bun.file(getPluginConfigPath());
-  return await file2.exists();
+  return Bun.file(getPluginConfigPath()).exists();
 }
-
-// src/config/types.ts
-var DEFAULT_ECONOMY_MODEL = "opencode/glm-4.7-free";
-
 // src/config/initializer.ts
-var OPENCODE_AGENTS = [
-  "build",
-  "plan",
-  "summary",
-  "compaction",
-  "title",
-  "explore",
-  "general"
-];
-async function buildPerformancePreset() {
-  const opencodeConfig = await loadOpencodeConfig();
-  const ohMyOpencodeConfig = await loadOhMyOpencodeConfig();
-  const opencodePreset = {};
-  const ohMyOpencodePreset = {};
-  if (opencodeConfig?.agent) {
-    for (const agentName of OPENCODE_AGENTS) {
-      const agentConfig = opencodeConfig.agent[agentName];
-      if (agentConfig?.model) {
-        opencodePreset[agentName] = { model: agentConfig.model };
-      }
-    }
-  }
-  if (ohMyOpencodeConfig?.agents) {
-    for (const [agentName, agentConfig] of Object.entries(ohMyOpencodeConfig.agents)) {
-      if (agentConfig?.model) {
-        ohMyOpencodePreset[agentName] = { model: agentConfig.model };
+function applyEconomyModel(config2, economyModel) {
+  const result = {};
+  for (const [key, value] of Object.entries(config2)) {
+    if (isObject2(value)) {
+      if ("model" in value) {
+        result[key] = {
+          ...value,
+          model: economyModel
+        };
+      } else {
+        result[key] = applyEconomyModel(value, economyModel);
       }
+    } else {
+      result[key] = value;
     }
   }
+  return result;
+}
+async function buildPerformancePreset() {
+  const opencodeConfig = await loadOpencodeConfig();
+  const ohMyOpencodeConfig = await loadOhMyOpencodeConfig();
+  const opencodePreset = opencodeConfig?.agent || {};
+  const ohMyOpencodePreset = ohMyOpencodeConfig || {};
   const globalModel = opencodeConfig?.model;
   return {
     description: "High-performance models for complex tasks",
@@ -13838,22 +13833,8 @@ async function buildPerformancePreset() {
 async function buildEconomyPreset() {
   const opencodeConfig = await loadOpencodeConfig();
   const ohMyOpencodeConfig = await loadOhMyOpencodeConfig();
-  const opencodePreset = {};
-  const ohMyOpencodePreset = {};
-  if (opencodeConfig?.agent) {
-    for (const agentName of Object.keys(opencodeConfig.agent)) {
-      opencodePreset[agentName] = { model: DEFAULT_ECONOMY_MODEL };
-    }
-  } else {
-    for (const agentName of OPENCODE_AGENTS) {
-      opencodePreset[agentName] = { model: DEFAULT_ECONOMY_MODEL };
-    }
-  }
-  if (ohMyOpencodeConfig?.agents) {
-    for (const agentName of Object.keys(ohMyOpencodeConfig.agents)) {
-      ohMyOpencodePreset[agentName] = { model: DEFAULT_ECONOMY_MODEL };
-    }
-  }
+  const opencodePreset = applyEconomyModel(opencodeConfig?.agent || {}, DEFAULT_ECONOMY_MODEL);
+  const ohMyOpencodePreset = applyEconomyModel(ohMyOpencodeConfig || {}, DEFAULT_ECONOMY_MODEL);
   return {
     description: "Cost-efficient free model for routine tasks",
     model: DEFAULT_ECONOMY_MODEL,
@@ -13882,8 +13863,101 @@ async function initializeConfig() {
   await savePluginConfig(config2);
   return config2;
 }
-
+// src/config/command-installer.ts
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+var COMMANDS_DEST = join2(homedir2(), ".config", "opencode", "command");
+function findCommandsDir() {
+  const __dirname2 = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join2(__dirname2, "..", "commands"),
+    join2(__dirname2, "..", "..", "commands")
+  ];
+  return candidates.find(existsSync) ?? null;
+}
+function copyCommandFiles() {
+  const commandsSrc = findCommandsDir();
+  if (!commandsSrc) {
+    return -1;
+  }
+  try {
+    mkdirSync(COMMANDS_DEST, { recursive: true });
+    const files = readdirSync(commandsSrc).filter((f) => f.endsWith(".md"));
+    for (const file2 of files) {
+      copyFileSync(join2(commandsSrc, file2), join2(COMMANDS_DEST, file2));
+    }
+    return files.length;
+  } catch (error45) {
+    console.warn("[agent-mode-switcher] Warning: Could not copy command files:", error45 instanceof Error ? error45.message : String(error45));
+    return -1;
+  }
+}
 // src/modes/manager.ts
+function isLeafNode(value) {
+  return "model" in value && typeof value.model === "string";
+}
+function deepMergeModel(target, preset) {
+  for (const [key, value] of Object.entries(preset)) {
+    if (!isObject2(value))
+      continue;
+    const actualValue = target[key];
+    if (isLeafNode(value)) {
+      const valueRecord = value;
+      const existing = actualValue ?? {};
+      const merged = {
+        ...existing,
+        ...valueRecord
+      };
+      target[key] = merged;
+    } else {
+      const childTarget = actualValue ?? {};
+      target[key] = childTarget;
+      deepMergeModel(childTarget, value);
+    }
+  }
+}
+function hasDriftRecursive(actual, expected) {
+  for (const [key, expectedValue] of Object.entries(expected)) {
+    if (!isObject2(expectedValue))
+      continue;
+    const actualValue = actual[key];
+    if (isLeafNode(expectedValue)) {
+      const actualObj = actualValue;
+      if (!actualObj) {
+        return true;
+      }
+      for (const [propKey, expectedPropValue] of Object.entries(expectedValue)) {
+        if (actualObj[propKey] !== expectedPropValue) {
+          return true;
+        }
+      }
+    } else if (hasDriftRecursive(actualValue || {}, expectedValue)) {
+      return true;
+    }
+  }
+  return false;
+}
+function formatHierarchicalTree(preset, indent = "  ") {
+  const lines = [];
+  for (const [key, value] of Object.entries(preset)) {
+    if (!isObject2(value))
+      continue;
+    if (isLeafNode(value)) {
+      const variant = value.variant ? ` (${value.variant})` : "";
+      const otherProps = Object.keys(value).filter((k) => k !== "model" && k !== "variant").map((k) => `${k}: ${JSON.stringify(value[k])}`).join(", ");
+      const extra = otherProps ? ` [${otherProps}]` : "";
+      lines.push(`${indent}${key}: ${value.model}${variant}${extra}`);
+    } else {
+      lines.push(`${indent}${key}:`);
+      lines.push(formatHierarchicalTree(value, `${indent}  `));
+    }
+  }
+  return lines.join(`
+`);
+}
+
 class ModeManager {
   client;
   config = null;
@@ -13892,6 +13966,7 @@ class ModeManager {
   }
   async initialize() {
     this.config = await initializeConfig();
+    await this.applyCurrentModeIfNeeded();
   }
   async ensureConfig() {
     if (!this.config) {
@@ -13899,6 +13974,46 @@ class ModeManager {
     }
     return this.config;
   }
+  async applyCurrentModeIfNeeded() {
+    if (!this.config) {
+      return;
+    }
+    const preset = this.config.presets[this.config.currentMode];
+    if (!preset) {
+      return;
+    }
+    const drifted = await this.hasConfigDrift(preset);
+    if (!drifted) {
+      return;
+    }
+    await this.updateOpencodeConfig(preset.model, preset.opencode);
+    await this.updateOhMyOpencodeConfig(preset["oh-my-opencode"]);
+    this.client.tui.showToast({
+      body: {
+        title: "Mode Applied",
+        message: `Applied "${this.config.currentMode}" mode. Restart opencode to take effect.`,
+        variant: "warning",
+        duration: 5000
+      }
+    }).catch(() => {});
+  }
+  async hasConfigDrift(preset) {
+    const opencodeConfig = await loadOpencodeConfig();
+    const ohMyConfig = await loadOhMyOpencodeConfig();
+    if (!opencodeConfig && !ohMyConfig) {
+      return false;
+    }
+    if (preset.model && opencodeConfig?.model !== preset.model) {
+      return true;
+    }
+    if (opencodeConfig?.agent && hasDriftRecursive(opencodeConfig.agent, preset.opencode)) {
+      return true;
+    }
+    if (ohMyConfig && hasDriftRecursive(ohMyConfig, preset["oh-my-opencode"])) {
+      return true;
+    }
+    return false;
+  }
   async getCurrentMode() {
     const config2 = await this.ensureConfig();
     return config2.currentMode;
@@ -13926,20 +14041,18 @@ ${modes}`;
       return `Current mode: ${currentMode} (preset not found)`;
     }
     const globalModel = preset.model ? `Global model: ${preset.model}` : "Global model: (not set)";
-    const opencodeAgents = Object.entries(preset.opencode).map(([name, cfg]) => `  - ${name}: ${cfg.model}`).join(`
-`);
-    const ohMyOpencodeAgents = Object.entries(preset["oh-my-opencode"]).map(([name, cfg]) => `  - ${name}: ${cfg.model}`).join(`
-`);
+    const opencodeTree = formatHierarchicalTree(preset.opencode);
+    const ohMyOpencodeTree = formatHierarchicalTree(preset["oh-my-opencode"]);
     return [
       `Current mode: ${currentMode}`,
       `Description: ${preset.description}`,
       globalModel,
       "",
-      "OpenCode agents:",
-      opencodeAgents || "  (none configured)",
+      "OpenCode config:",
+      opencodeTree || "  (none configured)",
       "",
-      "Oh-my-opencode agents:",
-      ohMyOpencodeAgents || "  (none configured)"
+      "Oh-my-opencode config:",
+      ohMyOpencodeTree || "  (none configured)"
     ].join(`
 `);
   }
@@ -13959,16 +14072,14 @@ ${modes}`;
     this.config = config2;
     await savePluginConfig(config2);
     results.push("agent-mode-switcher.json: updated");
-    try {
-      await this.client.tui.showToast({
-        body: {
-          title: "Mode Switched",
-          message: `Switched to "${modeName}". Restart opencode to apply.`,
-          variant: "warning",
-          duration: 5000
-        }
-      });
-    } catch {}
+    this.client.tui.showToast({
+      body: {
+        title: "Mode Switched",
+        message: `Switched to "${modeName}". Restart opencode to apply.`,
+        variant: "warning",
+        duration: 5000
+      }
+    }).catch(() => {});
     return [
       `Switched to ${modeName} mode`,
       preset.description,
@@ -13989,15 +14100,8 @@ ${modes}`;
       if (globalModel) {
         opencodeConfig.model = globalModel;
       }
-      if (Object.keys(agentPresets).length > 0) {
-        opencodeConfig.agent = opencodeConfig.agent || {};
-        for (const [agentName, preset] of Object.entries(agentPresets)) {
-          opencodeConfig.agent[agentName] = {
-            ...opencodeConfig.agent[agentName],
-            model: preset.model
-          };
-        }
-      }
+      opencodeConfig.agent = opencodeConfig.agent || {};
+      deepMergeModel(opencodeConfig.agent, agentPresets);
       await saveOpencodeConfig(opencodeConfig);
       return "updated";
     } catch (error45) {
@@ -14005,16 +14109,13 @@ ${modes}`;
       return `error: ${message}`;
     }
   }
-  async updateOhMyOpencodeConfig(agentPresets) {
+  async updateOhMyOpencodeConfig(preset) {
     try {
       const ohMyConfig = await loadOhMyOpencodeConfig();
       if (!ohMyConfig) {
         return "skipped (not found)";
       }
-      ohMyConfig.agents = ohMyConfig.agents || {};
-      for (const [agentName, preset] of Object.entries(agentPresets)) {
-        ohMyConfig.agents[agentName] = { model: preset.model };
-      }
+      deepMergeModel(ohMyConfig, preset);
       await saveOhMyOpencodeConfig(ohMyConfig);
       return "updated";
     } catch (error45) {
@@ -14027,37 +14128,6 @@ ${modes}`;
     return config2.showToastOnStartup;
   }
 }
-// src/config/command-installer.ts
-import { copyFileSync, mkdirSync, readdirSync, existsSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname, join as join2 } from "path";
-import { fileURLToPath } from "url";
-var COMMANDS_DEST = join2(homedir2(), ".config", "opencode", "command");
-function findCommandsDir() {
-  const __dirname2 = dirname(fileURLToPath(import.meta.url));
-  const candidates = [
-    join2(__dirname2, "..", "commands"),
-    join2(__dirname2, "..", "..", "commands")
-  ];
-  return candidates.find(existsSync) ?? null;
-}
-function copyCommandFiles() {
-  const commandsSrc = findCommandsDir();
-  if (!commandsSrc) {
-    return -1;
-  }
-  try {
-    mkdirSync(COMMANDS_DEST, { recursive: true });
-    const files = readdirSync(commandsSrc).filter((f) => f.endsWith(".md"));
-    for (const file2 of files) {
-      copyFileSync(join2(commandsSrc, file2), join2(COMMANDS_DEST, file2));
-    }
-    return files.length;
-  } catch (error45) {
-    console.warn("[agent-mode-switcher] Warning: Could not copy command files:", error45 instanceof Error ? error45.message : String(error45));
-    return -1;
-  }
-}
 // src/index.ts
 var modeSwitcherPlugin = async ({ client }) => {
   const modeManager = new ModeManager(client);

package/dist/modes/manager.d.ts

@@ -1,54 +1,235 @@
 import type { OpencodeClient } from '@opencode-ai/sdk';
 import type { ModePreset } from '../config/types.ts';
 /**
- * Manages agent mode switching between different presets
+ * Manages agent mode switching between different presets.
+ *
+ * This class provides the core functionality for switching between
+ * performance and economy modes (or custom presets). It handles:
+ * - Loading and managing plugin configuration
+ * - Switching between different model presets
+ * - Updating OpenCode configuration files
+ * - Providing status and listing available modes
+ *
+ * The manager updates three configuration files when switching modes:
+ * - `~/.config/opencode/agent-mode-switcher.json` (plugin state)
+ * - `~/.config/opencode/opencode.json` (OpenCode agents)
+ * - `~/.config/opencode/oh-my-opencode.json` (oh-my-opencode agents)
+ *
+ * @example
+ * ```typescript
+ * const manager = new ModeManager(client);
+ * await manager.initialize();
+ *
+ * // Switch to economy mode
+ * const result = await manager.switchMode('economy');
+ * console.log(result);
+ *
+ * // Get current status
+ * const status = await manager.getStatus();
+ * console.log(status);
+ * ```
  */
 export declare class ModeManager {
     private readonly client;
     private config;
     constructor(client: OpencodeClient);
     /**
-     * Initialize the mode manager and load configuration
+     * Initializes the mode manager and loads configuration.
+     *
+     * This method should be called before using any other manager methods.
+     * It loads or creates the plugin configuration file, ensuring all
+     * required presets are available.
+     *
+     * @throws {Error} If configuration initialization fails
+     * @example
+     * ```typescript
+     * const manager = new ModeManager(client);
+     * await manager.initialize();
+     * ```
      */
     initialize(): Promise<void>;
     /**
-     * Ensure configuration is loaded
+     * Ensures configuration is loaded before any operation.
+     *
+     * This internal method is called by all public methods to lazily
+     * initialize the configuration if it hasn't been loaded yet.
+     *
+     * @returns Promise resolving to the loaded configuration
+     * @throws {Error} If configuration loading fails
+     * @private
      */
     private ensureConfig;
     /**
-     * Get the current mode name
+     * Checks if actual config files have drifted from the current
+     * mode preset and applies the preset if needed.
+     *
+     * This handles the case where a user manually edits
+     * `agent-mode-switcher.json` to change `currentMode` while
+     * OpenCode is not running. On next startup, the actual config
+     * files are updated to match the expected preset values,
+     * and a toast notification prompts the user to restart.
+     *
+     * @private
+     */
+    private applyCurrentModeIfNeeded;
+    /**
+     * Compares a mode preset against the actual opencode.json and
+     * oh-my-opencode.json files to detect configuration drift.
+     *
+     * Checks global model and per-agent model values recursively. Returns true
+     * if any expected value differs from the actual file content.
+     *
+     * @param preset - The mode preset to compare against
+     * @returns True if actual configs differ from the preset
+     * @private
+     */
+    private hasConfigDrift;
+    /**
+     * Gets the name of the currently active mode.
+     *
+     * @returns Promise resolving to the current mode name (e.g., "performance", "economy")
+     * @example
+     * ```typescript
+     * const currentMode = await manager.getCurrentMode();
+     * console.log(`Current mode: ${currentMode}`);
+     * ```
      */
     getCurrentMode(): Promise<string>;
     /**
-     * Get a specific preset by name
+     * Gets a specific mode preset by name.
+     *
+     * @param modeName - The name of the mode to retrieve (e.g., "performance", "economy")
+     * @returns Promise resolving to the preset configuration, or undefined if not found
+     * @example
+     * ```typescript
+     * const preset = await manager.getPreset('economy');
+     * if (preset) {
+     *   console.log(preset.description);
+     *   console.log(preset.model);
+     * }
+     * ```
      */
     getPreset(modeName: string): Promise<ModePreset | undefined>;
     /**
-     * Get all available mode names
+     * Gets a formatted list of all available modes.
+     *
+     * Returns a multi-line string listing each mode with its description,
+     * marking the currently active mode with "(current)".
+     *
+     * @returns Promise resolving to formatted string listing all available modes
+     * @example
+     * ```typescript
+     * const list = await manager.listModes();
+     * console.log(list);
+     * // Output:
+     * // Available modes:
+     * // - performance (current): High-performance models for complex tasks
+     * // - economy: Cost-efficient free model for routine tasks
+     * ```
      */
     listModes(): Promise<string>;
     /**
-     * Get current status including mode and agent configurations
+     * Gets detailed status information for the current mode.
+     *
+     * Returns a formatted multi-line string showing:
+     * - Current mode name and description
+     * - Global model setting (if configured)
+     * - Hierarchical tree of OpenCode configuration
+     * - Hierarchical tree of oh-my-opencode configuration
+     *
+     * @returns Promise resolving to formatted status string
+     * @example
+     * ```typescript
+     * const status = await manager.getStatus();
+     * console.log(status);
+     * // Output:
+     * // Current mode: performance
+     * // Description: High-performance models for complex tasks
+     * // Global model: (not set)
+     * //
+     * // OpenCode config:
+     * //   agent:
+     * //     build: anthropic/claude-sonnet-4
+     * //     plan: anthropic/claude-sonnet-4
+     * // ...
+     * ```
      */
     getStatus(): Promise<string>;
     /**
-     * Switch to a different mode
+     * Switches to a different mode by updating all configuration files.
+     *
+     * This method performs the following operations:
+     * 1. Validates that the requested mode exists
+     * 2. Updates `opencode.json` with new global model and agent settings
+     * 3. Updates `oh-my-opencode.json` with new agent settings
+     * 4. Updates `agent-mode-switcher.json` with the new current mode
+     * 5. Shows a toast notification (if available)
+     *
+     * Configuration files that don't exist are skipped with a warning.
+     * Changes take effect after restarting OpenCode.
+     *
+     * @param modeName - The name of the mode to switch to
+     * @returns Promise resolving to a formatted result message with status of each config update
+     * @example
+     * ```typescript
+     * const result = await manager.switchMode('economy');
+     * console.log(result);
+     * // Output:
+     * // Switched to economy mode
+     * // Cost-efficient free model for routine tasks
+     * //
+     * // Results:
+     * //   - opencode.json: updated
+     * //   - oh-my-opencode.json: updated
+     * //   - agent-mode-switcher.json: updated
+     * //
+     * // Note: Restart opencode to apply changes.
+     * ```
      */
     switchMode(modeName: string): Promise<string>;
     /**
-     * Update opencode.json with global model and agent section
-     * @param globalModel - Global model setting (optional)
-     * @param agentPresets - Agent-specific model settings
-     * @returns Result status: "updated", "skipped (not found)", or "error: ..."
+     * Updates opencode.json with global model and agent section.
+     *
+     * This internal method modifies the OpenCode configuration file to apply
+     * the new preset's settings. It preserves other configuration properties
+     * and only updates model-related fields using recursive merge.
+     *
+     * @param globalModel - Global model setting (optional). If provided, sets the top-level "model" field
+     * @param agentPresets - Hierarchical preset structure for agent configuration
+     * @returns Promise resolving to result status: "updated", "skipped (not found)", or "error: ..."
+     * @private
      */
     private updateOpencodeConfig;
     /**
-     * Update oh-my-opencode.json agents section with preset values
-     * @returns Result status: "updated", "skipped (not found)", or "error: ..."
+     * Updates oh-my-opencode.json with preset values.
+     *
+     * This internal method modifies the oh-my-opencode configuration file
+     * to apply the new preset's settings using recursive merge. The entire
+     * structure (agents, categories, etc.) is updated while preserving
+     * other properties.
+     *
+     * @param preset - Hierarchical preset structure for oh-my-opencode configuration
+     * @returns Promise resolving to result status: "updated", "skipped (not found)", or "error: ..."
+     * @private
      */
     private updateOhMyOpencodeConfig;
     /**
-     * Check if toast should be shown on startup
+     * Checks if a toast notification should be shown on plugin startup.
+     *
+     * This is controlled by the `showToastOnStartup` configuration flag,
+     * which can be useful for reminding users of the current mode when
+     * OpenCode starts.
+     *
+     * @returns Promise resolving to true if toast should be shown, false otherwise
+     * @example
+     * ```typescript
+     * if (await manager.shouldShowToastOnStartup()) {
+     *   const mode = await manager.getCurrentMode();
+     *   await client.tui.showToast({
+     *     body: { message: `Current mode: ${mode}` }
+     *   });
+     * }
+     * ```
      */
     shouldShowToastOnStartup(): Promise<boolean>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-agent-modes",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "OpenCode plugin to switch agent modes between performance and economy presets",
   "module": "src/index.ts",
   "main": "dist/index.js",
@@ -25,29 +25,23 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun build src/index.ts --outdir dist --format esm --target bun && tsc -p tsconfig.build.json",
-    "lint": "bunx biome check src/",
-    "format": "prettier --write 'src/**/*.ts'",
-    "format:check": "prettier --check 'src/**/*.ts'",
+    "lint": "bunx biome check .",
+    "format": "bunx biome format --write .",
+    "format:check": "bunx biome format .",
     "test": "bun test",
     "test:watch": "bun test --watch",
     "test:coverage": "bun test --coverage",
     "prepublishOnly": "bun run build"
   },
-  "keywords": [
-    "opencode",
-    "plugin",
-    "agent",
-    "mode",
-    "switcher"
-  ],
+  "keywords": ["opencode", "plugin", "agent", "mode", "switcher"],
   "author": "j4rviscmd",
   "license": "MIT",
   "engines": {
     "node": ">=18"
   },
   "devDependencies": {
-    "@types/bun": "latest",
-    "prettier": "^3.8.0"
+    "@biomejs/biome": "^1.9.4",
+    "@types/bun": "latest"
   },
   "peerDependencies": {
     "typescript": "^5"