opencode-morphllm 0.0.9 → 0.1.0

package/DEVELOPMENT.md

@@ -0,0 +1,32 @@
+# Development
+
+To work on the plugin locally:
+
+1. Clone the repository
+2. Point OpenCode to your local copy in `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugins": ["/path/to/morph-opencode-plugin/"]
+}
+```
+
+3. Changes are immediately reflected when you run OpenCode
+
+## Scripts
+
+```bash
+# Build
+bun run build
+
+# Test
+bun test
+
+# Format
+bun run format
+```
+
+## Developer Notes
+
+- The config logic now exposes a small helper function (computeRouterEnabled) that encapsulates the decision logic for whether the router is enabled. This is exported primarily to make the behavior easily testable and to avoid brittle module-cache workarounds in tests.
+- If you change how config values are consumed, prefer adding unit tests that call computeRouterEnabled with a trimmed test fixture rather than trying to reload module-level constants.

package/README.md

@@ -1,65 +1,203 @@
 # MorphLLM OpenCode Plugin
 
-[![coverage](https://github.com/VitoLin/opencode-morphllm/blob/main/coverage/coverage.svg)](https://www.npmjs.com/package/opencode-morphllm)
+[![coverage](coverage/coverage.svg)](https://www.npmjs.com/package/opencode-morphllm)
 [![npm](https://img.shields.io/npm/v/opencode-morphllm?style=flat-square)](https://www.npmjs.com/package/opencode-morphllm)
 [![downloads](https://img.shields.io/npm/dt/opencode-morphllm?style=flat-square)](https://www.npmjs.com/package/opencode-morphllm)
 
-This is an OpenCode Plugin for [MorphLLM](https://morphllm.com/). This plugin just adds in `edit_file` and `warpgrep_codebase_search` from MorphLLM to your agent configs as well as the intelligent model router for choosing different models based on the difficulty of the prompt.
+An [OpenCode](https://opencode.ai/) plugin that integrates [MorphLLM](https://morphllm.com/)'s intelligent model routing and powerful MCP tools into your AI coding workflow.
 
-Github: https://github.com/VitoLin/opencode-morphllm
+- **GitHub**: https://github.com/VitoLin/opencode-morphllm
+- **NPM**: https://www.npmjs.com/package/opencode-morphllm
 
-NPM: https://www.npmjs.com/package/opencode-morphllm
+## Features
+
+### Intelligent Model Router
+
+Automatically classifies your prompts by complexity (easy/medium/hard) and routes them to the most cost-effective and appropriate model. Save money on simple tasks while using powerful models only when needed.
+
+### MCP Tools
+
+Adds MorphLLM's specialized MCP tools to OpenCode:
+
+- **`edit_file`** - Fast, precise file editing tool optimized for code modifications
+- **`warpgrep_codebase_search`** - Advanced codebase search with contextual understanding
+
+### Prompt Caching Optimization
+
+Optional mode that maintains model consistency within a session, reducing costs through prompt caching.
 
 ## Installation
 
-In `~/.config/opencode/opencode.json`, add the following config:
+### 1. Install the Plugin
 
-```
-"plugin": [
-  "opencode-morphllm"
-]
+Add the plugin to your OpenCode configuration at `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugins": ["opencode-morphllm"]
+}
 ```
 
-You can also set the `opencode-morphllm` config variables by creating a `json` file at `~/.config/opencode/morph.json`. You can find the provider and model ids from https://models.dev
+### 2. Configure MorphLLM
 
-Example configs:
+Create a configuration file at `~/.config/opencode/morph.json` or for repo level configs, you can create the config at your repo root at `.opencode/morph.json`.
+
+Example:
 
 ```json
 {
-  "MORPH_API_KEY": "YOUR_API_KEY_HERE",
+  "MORPH_API_KEY": "your_morph_api_key_here",
   "MORPH_ROUTER_CONFIGS": {
     "MORPH_MODEL_EASY": "github-copilot/gpt-5-mini",
     "MORPH_MODEL_MEDIUM": "opencode/minimax-m2.1-free",
     "MORPH_MODEL_HARD": "github-copilot/gemini-2.5-pro",
     "MORPH_ROUTER_ENABLED": true,
-    "MORPH_ROUTER_PROMPT_CACHING_AWARE": true
+    "MORPH_ROUTER_PROMPT_CACHING_AWARE": false
   }
 }
 ```
 
-Legacy format (still supported):
+Find available models at [models.dev](https://models.dev).
+
+## Configuration Reference
+
+### Core Settings
+
+| Option          | Description           | Required |
+| --------------- | --------------------- | -------- |
+| `MORPH_API_KEY` | Your MorphLLM API key | Yes      |
+
+### Router Settings (inside `MORPH_ROUTER_CONFIGS`)
+
+| Option                              | Description                                               | Default                         |
+| ----------------------------------- | --------------------------------------------------------- | ------------------------------- |
+| `MORPH_ROUTER_ENABLED`              | Enable/disable the intelligent router                     | `true`                          |
+| `MORPH_MODEL_EASY`                  | Model for easy prompts (simple questions, formatting)     | `your currently selected model` |
+| `MORPH_MODEL_MEDIUM`                | Model for medium prompts (standard coding tasks)          | `your currently selected model` |
+| `MORPH_MODEL_HARD`                  | Model for hard prompts (complex architecture, debugging)  | `your currently selected model` |
+| `MORPH_MODEL_DEFAULT`               | Fallback model when classification fails                  | `MORPH_MODEL_MEDIUM`            |
+| `MORPH_ROUTER_PROMPT_CACHING_AWARE` | Stick to first model per session for caching optimization | `false`                         |
+
+> Note about router enablement
+>
+> - The router will be automatically disabled if none of the model slots (`MORPH_MODEL_EASY`, `MORPH_MODEL_MEDIUM`, `MORPH_MODEL_HARD`) are configured (i.e., all are empty strings). This prevents the router from being active when there are no target models configured. An explicit `MORPH_ROUTER_ENABLED: false` in your config will also disable the router even if models are present.
+
+### System Message Customization
+
+| Option                 | Description                                                | Default   |
+| ---------------------- | ---------------------------------------------------------- | --------- |
+| `MORPH_SYSTEM_MESSAGE` | Custom system message appended to OpenCode's system prompt | See below |
+
+The `MORPH_SYSTEM_MESSAGE` setting allows you to customize or override the default system message that MorphLLM appends to OpenCode's system prompt. This message guides the AI on using Morph's MCP tools effectively.
+
+**Default message:**
+
+```
+You **MUST** consider using morph_mcp. For editing files, consider using morph_mcp_edit_file. For searching the code base, consider using warpgrep_codebase_search
+```
+
+**When to customize:**
+
+- You want to emphasize different tool preferences for your workflow
+- You need to add project-specific conventions or guidelines
+- You want to disable the default guidance entirely (set to empty string `""`)
+
+**Example:**
+
+```json
+{
+  "MORPH_API_KEY": "your_morph_api_key_here",
+  "MORPH_SYSTEM_MESSAGE": "Your custom system message here"
+}
+```
+
+### Model Format
+
+Models are specified as `provider/model-id`. Examples:
+
+- `github-copilot/gpt-5-mini`
+- `github-copilot/gemini-2.5-pro`
+- `opencode/minimax-m2.1-free`
+
+### Legacy Format
+
+For backward compatibility, you can also use flat configuration:
 
 ```json
 {
-  "MORPH_API_KEY": "YOUR_API_KEY_HERE",
+  "MORPH_API_KEY": "your_key",
   "MORPH_MODEL_EASY": "github-copilot/gpt-5-mini",
   "MORPH_MODEL_MEDIUM": "opencode/minimax-m2.1-free",
   "MORPH_MODEL_HARD": "github-copilot/gemini-2.5-pro",
-  "MORPH_ROUTER_ENABLED": true,
-  "MORPH_ROUTER_PROMPT_CACHING_AWARE": true
+  "MORPH_ROUTER_ENABLED": true
 }
 ```
 
+### Project-Level Configuration
+
+You can also configure per-project settings by creating `.opencode/morph.json` in your project root. Project settings override user settings.
+
+```
+my-project/
+├── .opencode/
+│   └── morph.json      # Project-specific Morph config
+└── src/
+```
+
+Both `.json` and `.jsonc` (with comments) formats are supported.
+
+## How It Works
+
+### Intelligent Routing
+
+When you send a prompt, the plugin:
+
+1. **Classifies** the prompt complexity using MorphLLM's classification engine
+2. **Selects** the appropriate model based on your configuration
+3. **Routes** the request to the chosen model
+
+Example routing:
+
+- "Format this JSON" → Easy → `MORPH_MODEL_EASY` (cheaper, faster)
+- "Add a React component" → Medium → `MORPH_MODEL_MEDIUM`
+- "Debug this race condition" → Hard → `MORPH_MODEL_HARD` (powerful)
+
+### Prompt Caching Mode
+
+When `MORPH_ROUTER_PROMPT_CACHING_AWARE` is enabled:
+
+- The first prompt in a session determines the model for all subsequent prompts
+- Reduces costs through prompt caching with compatible providers
+- Best for long conversations on similar topics
+
 ## Development
 
-After pulling down the package, set the OpenCode config path to the local repo
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup instructions and development notes.
+
+## Troubleshooting
+
+### Plugin not loading
 
-`~/.config/opencode/opencode.json`
+Ensure the plugin is properly listed in your OpenCode config:
 
 ```json
-"plugin": [
-  "/path/to/morph-opencode-plugin/"
-]
+{
+  "plugins": ["opencode-morphllm"]
+}
 ```
 
-Now your changes will be reflected when you run OpenCode.
+### Router not working
+
+Check that:
+
+1. `MORPH_API_KEY` is set correctly
+2. `MORPH_ROUTER_ENABLED` is not set to `false`
+3. At least one model is configured
+
+### Where to find models
+
+Visit [models.dev](https://models.dev) to browse available models and their IDs.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.js

@@ -1,7 +1,9 @@
 import { createBuiltinMcps } from './morph/mcps';
 import { createModelRouterHook } from './morph/router';
+import { createSystemTransformHook } from './morph/system-transform';
 const MorphOpenCodePlugin = async () => {
     const builtinMcps = createBuiltinMcps();
+    const systemTransformHook = createSystemTransformHook();
     const routerHook = createModelRouterHook();
     return {
         config: async (currentConfig) => {
@@ -10,6 +12,7 @@ const MorphOpenCodePlugin = async () => {
                 ...builtinMcps,
             };
         },
+        ...systemTransformHook,
         ...routerHook,
     };
 };

package/dist/morph/system-transform.d.ts

@@ -0,0 +1,5 @@
+export declare function createSystemTransformHook(): {
+    'experimental.chat.system.transform': (_input: unknown, output: {
+        system: string[];
+    }) => Promise<void>;
+};

package/dist/morph/system-transform.js

@@ -0,0 +1,8 @@
+import { MORPH_SYSTEM_MESSAGE } from '../shared/config';
+export function createSystemTransformHook() {
+    return {
+        'experimental.chat.system.transform': async (_input, output) => {
+            output.system.push(MORPH_SYSTEM_MESSAGE);
+        },
+    };
+}

package/dist/shared/config.d.ts

@@ -9,6 +9,7 @@ interface MorphRouterConfigs {
 }
 interface MorphConfig {
     MORPH_API_KEY?: string;
+    MORPH_SYSTEM_MESSAGE?: string;
     MORPH_ROUTER_CONFIGS?: MorphRouterConfigs;
     MORPH_ROUTER_ENABLED?: boolean;
     MORPH_ROUTER_PROMPT_CACHING_AWARE?: boolean;
@@ -24,6 +25,12 @@ export declare const MORPH_MODEL_EASY: string;
 export declare const MORPH_MODEL_MEDIUM: string;
 export declare const MORPH_MODEL_HARD: string;
 export declare const MORPH_MODEL_DEFAULT: string;
+/**
+ * Computes whether the router should be enabled based on config and model availability.
+ * Exported for testing purposes.
+ */
+export declare function computeRouterEnabled(routerConfigs: MorphRouterConfigs, config: MorphConfig): boolean;
 export declare const MORPH_ROUTER_ENABLED: boolean;
 export declare const MORPH_ROUTER_PROMPT_CACHING_AWARE: boolean;
+export declare const MORPH_SYSTEM_MESSAGE: string;
 export {};

package/dist/shared/config.js

@@ -74,7 +74,22 @@ export const MORPH_MODEL_HARD = routerConfigs.MORPH_MODEL_HARD || config.MORPH_M
 export const MORPH_MODEL_DEFAULT = routerConfigs.MORPH_MODEL_DEFAULT ||
     config.MORPH_MODEL_DEFAULT ||
     MORPH_MODEL_MEDIUM;
-export const MORPH_ROUTER_ENABLED = routerConfigs.MORPH_ROUTER_ENABLED ?? config.MORPH_ROUTER_ENABLED ?? true;
+/**
+ * Computes whether the router should be enabled based on config and model availability.
+ * Exported for testing purposes.
+ */
+export function computeRouterEnabled(routerConfigs, config) {
+    const easy = routerConfigs.MORPH_MODEL_EASY || config.MORPH_MODEL_EASY || '';
+    const medium = routerConfigs.MORPH_MODEL_MEDIUM || config.MORPH_MODEL_MEDIUM || '';
+    const hard = routerConfigs.MORPH_MODEL_HARD || config.MORPH_MODEL_HARD || '';
+    // Router should be disabled if all model values are empty strings
+    const allModelsEmpty = !easy && !medium && !hard;
+    return (!allModelsEmpty &&
+        (routerConfigs.MORPH_ROUTER_ENABLED ?? config.MORPH_ROUTER_ENABLED ?? true));
+}
+export const MORPH_ROUTER_ENABLED = computeRouterEnabled(routerConfigs, config);
 export const MORPH_ROUTER_PROMPT_CACHING_AWARE = routerConfigs.MORPH_ROUTER_PROMPT_CACHING_AWARE ??
     config.MORPH_ROUTER_PROMPT_CACHING_AWARE ??
     false;
+const DEFAULT_SYSTEM_MESSAGE = '\nYou **MUST** consider using morph_mcp. For editing files, consider using morph_mcp_edit_file. For searching the code base, consider using warpgrep_codebase_search';
+export const MORPH_SYSTEM_MESSAGE = config.MORPH_SYSTEM_MESSAGE || DEFAULT_SYSTEM_MESSAGE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-morphllm",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "author": "Vito Lin",
   "main": "dist/index.js",
   "description": "OpenCode plugin for MorphLLM",