From 1a0e72b39cd092f1c52654a6e314959c496ca746 Mon Sep 17 00:00:00 2001 From: isamu Date: Sun, 25 Jan 2026 09:11:03 +0900 Subject: [PATCH 1/3] docs: add Key Innovation and Plugin Configuration sections - Add Key Innovation section explaining dual-output architecture - Add Plugin Configuration section for user-configurable settings - Update CLAUDE.md to reference docs as self-contained documentation - Update table of contents in plugin-development-guide.md Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 22 ++++- docs/plugin-development-guide.md | 138 +++++++++++++++++++++++++++++-- 2 files changed, 150 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d4fa371..51ddc17 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,10 +4,27 @@ This file provides guidance to Claude Code (claude.ai/code) when working with th ## Project Overview -GUIChatPluginTemplate is a template for creating GUI plugins for MulmoChat. It supports both Vue and React. +GUIChatPluginTemplate is a **self-contained template** for creating GUI plugins for MulmoChat. It includes all documentation needed for plugin development - no need to reference MulmoChat docs. **Current Sample**: Quiz plugin (displays multiple choice questions) +## Documentation + +All plugin development documentation is in the `docs/` directory: + +| Document | Description | +|----------|-------------| +| [Plugin Development Guide](./docs/plugin-development-guide.md) | Complete reference (architecture, types, patterns) | +| [Getting Started](./docs/getting-started.md) | Beginner tutorial | +| [Advanced Features](./docs/advanced-features.md) | sendTextMessage, viewState, Tailwind CSS | +| [npm Publishing Guide](./docs/npm-publishing-guide.md) | Package publishing steps | + +**Key concepts covered in docs:** +- **Key Innovation**: Dual-output architecture (GUI for users + JSON for AI) +- **Plugin Configuration**: User-configurable settings with config components +- **External API Keys**: Integration with host app API keys +- **Advanced Patterns**: Games, file uploads, state persistence + ## Philosophy This project is an implementation of **[gui-chat-protocol](https://github.com/receptron/gui-chat-protocol)**. @@ -832,6 +849,9 @@ This ensures future Claude sessions have accurate context. ## Reference Documentation +See the `docs/` directory for detailed guides: + +- [Plugin Development Guide](./docs/plugin-development-guide.md) - Complete reference - [Getting Started](./docs/getting-started.md) - Beginner tutorial - [Advanced Features](./docs/advanced-features.md) - sendTextMessage, viewState, Tailwind CSS - [npm Publishing Guide](./docs/npm-publishing-guide.md) - Package publishing diff --git a/docs/plugin-development-guide.md b/docs/plugin-development-guide.md index 7ffab77..9a53ca4 100644 --- a/docs/plugin-development-guide.md +++ b/docs/plugin-development-guide.md @@ -4,15 +4,50 @@ Complete reference for developing GUIChat plugins. This guide covers all aspects ## Table of Contents -1. [Architecture Overview](#architecture-overview) -2. [Type System](#type-system) -3. [Directory Structure](#directory-structure) -4. [Core Implementation](#core-implementation) -5. [UI Components](#ui-components) -6. [Advanced Patterns](#advanced-patterns) -7. [External API Key Integration](#external-api-key-integration) -8. [Testing](#testing) -9. [Checklist](#checklist) +1. [Key Innovation](#key-innovation) +2. [Architecture Overview](#architecture-overview) +3. [Type System](#type-system) +4. [Directory Structure](#directory-structure) +5. [Core Implementation](#core-implementation) +6. [UI Components](#ui-components) +7. [Advanced Patterns](#advanced-patterns) +8. [Plugin Configuration](#plugin-configuration) +9. [External API Key Integration](#external-api-key-integration) +10. [Testing](#testing) +11. [Checklist](#checklist) + +--- + +## Key Innovation + +**GUIChat extends OpenAI's function calling mechanism to enable direct GUI communication between plugins and users.** + +Traditional function calling systems follow this pattern: +``` +User → AI → Function Call → Backend → JSON Response → AI → User +``` + +GUIChat's innovation adds a **visual layer** to this flow: +``` +User → AI → Function Call → Plugin Execution → Rich GUI Result → User + ↓ + AI receives JSON summary for context +``` + +**What this means:** +- **Dual Output:** Each plugin returns both machine-readable data (for the AI) and human-readable UI (for the user) +- **Rich Interactions:** Users see images, maps, interactive games, videos—not just text +- **Persistent Results:** Plugin outputs remain visible in the sidebar and can be re-selected +- **Visual Context:** The AI knows what the user is seeing and can reference it naturally +- **Bidirectional Communication:** Users can interact with plugin UIs while conversing with the AI + +**Example:** When the AI calls `generateImage("sunset over mountains")`: +1. Plugin generates the image +2. **User sees:** Full-resolution image rendered on canvas +3. **AI receives:** `"Image generated successfully and displayed to user"` +4. Conversation continues with both parties aware of the visual context + +This architecture transforms function calling from a backend integration pattern into a **multimodal user experience**. --- @@ -580,6 +615,91 @@ export const pluginCore: ToolPluginCore = { --- +## Plugin Configuration + +Add user-configurable settings to your plugin. This is useful when you want users to customize plugin behavior through a settings UI. + +> **Note:** Plugin configuration is a host app feature. The examples below show how MulmoChat implements this. Your host app may implement configuration differently. + +### Step 1: Create Config Component + +Create a Vue component for your configuration UI: + +```vue + + + +``` + +**Requirements:** +- Props: `{ value: T }` - Current config value +- Emits: `{ 'update:value': [newValue: T] }` - Value change events + +### Step 2: Add Config to Plugin + +```typescript +import ConfigComponent from "./ConfigComponent.vue"; + +export const plugin: ToolPlugin = { + // ... other properties + config: { + key: "myConfigKey", // Storage key (unique per plugin) + defaultValue: "default", // Default value + component: ConfigComponent, // Vue component + }, +}; +``` + +### Step 3: Use Config in Execute Function + +Access the configuration value through `context`: + +```typescript +const execute = async ( + context: ToolContext, + args: MyArgs, +): Promise> => { + // Get user's configured value + const configValue = context.getPluginConfig?.("myConfigKey") || "default"; + + // Use configValue in your logic + const result = processWithConfig(args, configValue); + + return { + toolName: TOOL_NAME, + message: "Success", + data: result, + }; +}; +``` + +**How it works (in MulmoChat):** +- Configs are automatically saved to `localStorage` under key `plugin_configs_v1` +- The value is accessible via `context.getPluginConfig(key)` +- The config UI is automatically rendered in the settings modal + +--- + ## External API Key Integration When your plugin requires an external API key (e.g., Google Maps, weather services), you need to: From 51b8df1bd95e1d23b86de81001f8031613282044 Mon Sep 17 00:00:00 2001 From: isamu Date: Sun, 25 Jan 2026 09:18:18 +0900 Subject: [PATCH 2/3] docs: add GitHub installation guide and update CSS documentation - Add "Adding Plugin to MulmoChat" section to CLAUDE.md - Add "GitHub Installation (Without npm Publish)" section to npm-publishing-guide.md - Update CSS sections to reflect automatic @source inclusion (no manual import needed) - Update troubleshooting for CSS issues Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 43 ++++++++++++ docs/npm-publishing-guide.md | 124 ++++++++++++++++++++++++++++++++--- 2 files changed, 159 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 51ddc17..fdd3994 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -847,6 +847,49 @@ This ensures future Claude sessions have accurate context. --- +## Adding Plugin to MulmoChat + +After developing your plugin, you can add it to MulmoChat via GitHub (for testing) or npm (for production). + +### Quick Steps (GitHub Installation) + +1. **Build and commit dist**: + ```bash + yarn build + git add -f dist + git commit -m "build: add dist for GitHub installation" + git push origin main + ``` + +2. **Add to MulmoChat's package.json**: + ```json + { + "dependencies": { + "@gui-chat-plugin/your-plugin": "github:your-username/GUIChatPluginYourName" + } + } + ``` + +3. **Register plugin in MulmoChat** (`src/tools/index.ts`): + ```typescript + import YourPlugin from "@gui-chat-plugin/your-plugin/vue"; + + const pluginList = [ + // ... existing plugins + YourPlugin, + ]; + ``` + +4. **CSS is automatic** - MulmoChat uses `@source` directive to include plugin styles: + ```css + /* src/index.css - already configured */ + @source "../node_modules/@gui-chat-plugin/*/dist/vue.js"; + ``` + +For detailed instructions including npm publishing, see [npm Publishing Guide](./docs/npm-publishing-guide.md). + +--- + ## Reference Documentation See the `docs/` directory for detailed guides: diff --git a/docs/npm-publishing-guide.md b/docs/npm-publishing-guide.md index 6c3cb9e..25be101 100644 --- a/docs/npm-publishing-guide.md +++ b/docs/npm-publishing-guide.md @@ -194,15 +194,16 @@ export const plugins = [ ]; ``` -### Import CSS +### CSS (Automatic) -Edit `src/main.ts`: +MulmoChat's `src/index.css` uses `@source` to automatically include plugin styles: -```typescript -// Import plugin styles -import "guichat-plugin-your-plugin-name/style.css"; +```css +@source "../node_modules/@gui-chat-plugin/*/dist/vue.js"; ``` +**No manual import needed** - plugin styles are automatically included. + ### Verify Integration ```bash @@ -244,14 +245,121 @@ Ensure `types` field in exports points to correct `.d.ts` files. ### CSS not loading Check: -1. `style.css` is in `files` array -2. Export path `./style.css` is correct -3. Import path in MulmoChat is correct +1. `style.css` is in `files` array in package.json +2. Export path `./style.css` is correct in package.json exports +3. MulmoChat's `src/index.css` has `@source` directive for your plugin path +4. You are NOT using Tailwind arbitrary values (e.g., `bg-[#1a1a2e]`) ### Build files missing Run `npm run build` before publishing. Check `vite.config.ts` for correct output configuration. +## GitHub Installation (Without npm Publish) + +If you want to test your plugin in MulmoChat before publishing to npm, you can install directly from GitHub. + +### Step 1: Build and Commit dist + +```bash +# Build the plugin +yarn build + +# Force add dist (normally gitignored) +git add -f dist + +# Commit +git commit -m "build: add dist for GitHub installation" + +# Push to GitHub +git push origin main +``` + +### Step 2: Add to MulmoChat + +In MulmoChat's `package.json`, add your plugin using GitHub reference: + +```json +{ + "dependencies": { + "@gui-chat-plugin/your-plugin": "github:your-username/GUIChatPluginYourName" + } +} +``` + +Then install: + +```bash +yarn install +``` + +### Step 3: Configure MulmoChat + +You need to make changes in the MulmoChat repository: + +#### 3a. Register Plugin (src/tools/index.ts) + +```typescript +// Add import at the top +import YourPlugin from "@gui-chat-plugin/your-plugin/vue"; + +// Add to pluginList array +const pluginList = [ + // ... existing plugins + YourPlugin, +]; +``` + +#### 3b. CSS (Automatic via @source) + +MulmoChat uses Tailwind's `@source` directive to automatically include plugin styles: + +```css +/* src/index.css - already configured */ +@source "../node_modules/@gui-chat-plugin/*/dist/vue.js"; +``` + +**No manual CSS import needed** - just make sure your plugin uses standard Tailwind classes (no arbitrary values like `bg-[#1a1a2e]`). + +#### 3c. (Optional) Pass API Keys to View Component + +If your plugin requires API keys, update `src/views/HomeView.vue`: + +```vue + +``` + +And add to `server/routes/api.ts`: + +```typescript +const yourApiKey = process.env.YOUR_API_KEY; + +// In the start endpoint response +res.json({ + // ... other fields + yourApiKey, +}); +``` + +### Step 4: Test + +```bash +yarn install +yarn typecheck +yarn dev +``` + +### Important Notes + +- **dist must be committed**: GitHub installation requires built files +- **Update dist on changes**: Run `git add -f dist && git commit` after each build +- **Switch to npm later**: Once stable, publish to npm and update package.json reference + +--- + ## Local Development with MulmoChat For developing your plugin alongside MulmoChat: From 91645ddda7e9b4c4d9a7189f3a5a6b0f95fa082f Mon Sep 17 00:00:00 2001 From: isamu Date: Sun, 25 Jan 2026 09:24:40 +0900 Subject: [PATCH 3/3] docs: add development guidelines and npm release instructions - Add Development Guidelines section (yarn, code quality, project setup, coding style, Vue.js rules) - Add npm Package Release section with step-by-step instructions Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index fdd3994..55cf04f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -54,6 +54,54 @@ yarn lint # Lint check --- +## Development Guidelines + +### Package Manager + +Use **yarn** instead of npm. + +- `yarn` for installing dependencies +- `yarn add ` for adding packages +- Do NOT use npm commands + +### Code Quality + +After making code changes, always run: + +1. `yarn lint` - Check for linting errors +2. `yarn build` - Verify build succeeds + +### Project Setup + +- Node.js version: **24** or later +- ESLint must use **flat config** (eslint.config.js), not legacy .eslintrc +- Use **Tailwind CSS v4** (not v3) with `@tailwindcss/vite` plugin + +ESLint rules: +- Indent: 2 spaces +- Quotes: double (`"`) +- Semicolons: required +- Unused variables: prefix with `__` to ignore + +### Coding Style + +- Keep functions under 20 lines; split into smaller functions if needed +- Prefer `const` over `let`; never use `var` +- Prefer functional approaches (`forEach`, `map`, `filter`, `reduce`) over `for` loops +- Prefer `async/await` over `.then()` chains +- Use explicit type definitions; avoid `any` +- No magic numbers; use named constants + +### Vue.js + +- Use Composition API (not Options API) +- Always use relative paths for imports (not alias paths like `@/`) +- Use `emit` instead of passing functions as props +- Prefer `ref` over `reactive` +- Never use `v-html` (security risk) + +--- + ## Plugin Creation Flow When a user requests "create a XX plugin", follow these steps. @@ -890,6 +938,61 @@ For detailed instructions including npm publishing, see [npm Publishing Guide](. --- +## npm Package Release + +When releasing a new version of a plugin to npm: + +**IMPORTANT**: Confirm with user before each step. + +### Steps + +1. **Sync with remote**: + ```bash + git pull origin main + ``` + +2. **Bump version** in package.json (patch/minor/major) + +3. **Install and validate**: + ```bash + yarn install + yarn typecheck + yarn lint + yarn build + ``` + +4. **Publish to npm**: + ```bash + npm publish --access public + ``` + +5. **Commit changes** (add files individually, NOT `git add -A`): + ```bash + git add package.json yarn.lock + git commit -m "@package-name@version" + git push origin main + ``` + +6. **Create git tag** (NO "v" prefix): + ```bash + git tag "1.0.0" + git push origin "1.0.0" + ``` + +7. **Create GitHub release**: + ```bash + gh release create "1.0.0" --generate-notes --title "1.0.0" + ``` + +### Important Rules + +- Tag format: `1.0.0` (NOT `v1.0.0`) +- Commit message format: `@package-name@version` (e.g., `@gui-chat-plugin/quiz@0.1.1`) +- Use `git pull origin main` for syncing (NEVER `git rebase`) +- Add files individually (NEVER `git add -A` or `git add .`) + +--- + ## Reference Documentation See the `docs/` directory for detailed guides: