Muyue/MuyueWorkspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 141 Wiki Activity

feat: add Cobra CLI, LSP/MCP registries, workflow engine, and enriched dashboard
All checks were successful
Beta Release / beta (push) Successful in 2m24s
Details

Browse Source 
Major changes:
- Refactor CLI entry point to Cobra commands (root, setup, scan, doctor, install, update, lsp, mcp, skills, config, version)
- Add LSP registry with health checks, auto-install, and editor config generation
- Add MCP registry with editor detection, status tracking, and per-editor configuration
- Add workflow engine with planner and step execution for automated task chains
- Add conversation search, export (Markdown/JSON), and detailed token counting
- Add streaming shell chat handler with tool call/result events
- Add skill validation, dry-run testing, and export endpoints
- Enrich dashboard with Tools/Activity/Status tabs and tool cards grid
- Add PRD documentation
- Complete i18n for both EN and FR

💘 Generated with Crush

Assisted-by: GLM-5.1 via Crush <crush@charm.land>
This commit is contained in:
Augustin
2026-04-22 22:22:05 +02:00
parent 66b773ff86
commit 2e50366cd8
42 changed files with 6779 additions and 319 deletions
Download Patch File Download Diff File Expand all files Collapse all files

914
docs/PRD.md Normal file
View File

@@ -0,0 +1,914 @@
# Muyue PRD v1.0
> **Author**: Product Architect
> **Date**: 2026-04-22
> **Status**: Definitive
---
## 1. Product Vision & Positioning
### What is Muyue?
Muyue is a local-first, single-binary development environment assistant that combines an AI orchestration layer, a tool manager, and a cyberpunk-themed desktop UI into one cohesive experience. It scans your system, installs missing tools, configures AI agent environments (MCP servers, LSPs, skills), and provides a Studio for AI-assisted workflows — all without requiring cloud infrastructure.
### What problem does it solve?
Developers spend significant time setting up and maintaining their dev environments: installing tools, configuring MCP servers for AI agents, managing API keys, and switching between CLI tools. Muyue eliminates this friction by providing a single interface that unifies environment management, AI orchestration, and terminal access. It is the "home base" for developers who use AI coding agents (Crush, Claude Code) daily.
### Who is it for?
- **Primary**: Solo developers and small teams who use AI coding agents (Crush, Claude Code) and want a unified control panel.
- **Secondary**: Developers setting up new machines who want a "one-click" environment bootstrap.
- **Not for**: Enterprise teams needing sandboxed environments (Daytona), container orchestration (DevPod), or MCP server registries (MCPM).
### How is Muyue different?
| Competitor | What they do | What Muyue does differently |
|---|---|---|
| **Daytona** | Cloud sandbox infrastructure for AI agents (sandboxes, snapshots, multi-tenant) | Muyue is local-first, lightweight, no infra required. Daytona is "cloud VMs for AI"; Muyue is "desktop control panel for your local AI agents". |
| **kasetto** | Declarative AI agent environment manager (Rust, CLI-only) | Muyue adds a desktop GUI, interactive workflows, and a terminal. kasetto is "Nix for AI tools"; Muyue is "a cockpit". |
| **OpenCode** | Terminal-based AI coding agent (Go, TUI, LSP+MCP client) | OpenCode is an AI coding agent itself. Muyue orchestrates agents (Crush, Claude) rather than being one. Muyue provides a desktop UI, tool management, and MCP config generation that OpenCode doesn't. |
| **DevPod** | Dev environment manager using devcontainers (Go, CLI+Desktop) | DevPod manages remote/container environments. Muyue manages your local machine's tools and AI agent configs. No container overlap. |
| **MCPM** | MCP server package manager (Python, CLI, registry) | Muyue generates MCP configs for Crush + Claude Code directly. Delegates server discovery to MCPM where needed. |
| **McpMux** | Desktop MCP gateway/router (Rust) | Muyue manages MCP configs per-tool rather than routing through a gateway. Simpler, no encryption layer needed for local use. |
### What Muyue should NOT do (anti-scope)
1. **Not a coding agent** — Muyue orchestrates agents (Crush, Claude Code); it does not edit files, run tests, or write code autonomously. The `crush_run` tool delegates to Crush.
2. **Not a sandbox/container manager** — No Docker orchestration, no VM provisioning. Use DevPod or Daytona for that.
3. **Not an MCP registry** — No server discovery marketplace. Delegate to MCPM for that.
4. **Not a CI/CD tool** — No build pipelines, no deployment workflows.
5. **Not a multi-tenant platform** — Single-user, local machine only. No org management, no billing.
6. **Not an IDE** — No file tree editor, no debugging, no syntax highlighting. Use VS Code, Zed, or Neovim.
7. **Not an LSP client** — Muyue installs and manages LSP servers; it does not connect to them as a client. The IDE handles that.
8. **Not a proxy/gateway** — No AI proxy agents, no request routing. The orchestrator talks directly to providers.
---
## 2. Feature Matrix
### P0 — Must Have for Launch
| # | Feature | Priority | Status | Decision | Description |
|---|---------|----------|--------|----------|-------------|
| 1 | System scanning (tools, runtimes, editors, shell, git) | P0 | **EXISTS** | KEEP | Scanner checks 14 tools, 8 runtimes, 8 editors, shell setup, git config. Has 5-min cache, JSON output. |
| 2 | Tool installation (crush, claude, bmad, starship, go, node, python, git, pnpm, uv, docker, gh) | P0 | **EXISTS** | KEEP | Installer handles 12 tools with platform-specific install methods (apt/brew/winget). API endpoint wired. |
| 3 | CLI subcommands (scan, install, update, setup, config, doctor, version, lsp, mcp, skills) | P0 | **EXISTS** | KEEP | Cobra-based CLI with all documented subcommands. Each has appropriate flags and output. |
| 4 | Desktop mode (HTTP server + embedded SPA) | P0 | **EXISTS** | KEEP | `desktop.go` serves frontend via `go:embed`, auto-opens browser, handles `--port` and `--no-open`. |
| 5 | AI orchestration (OpenAI-compatible, multi-provider) | P0 | **EXISTS** | KEEP | Orchestrator supports MiniMax, ZAI, Anthropic, OpenAI, Ollama. History management, tool calling loop. |
| 6 | Agent tools (10 tools: terminal, crush_run, read_file, list_files, search_files, grep_content, get_config, set_provider, manage_ssh, web_fetch) | P0 | **EXISTS** | KEEP | All 10 tools implemented with proper parameter validation, timeouts, and output truncation. |
| 7 | Tool execution endpoint | P0 | **EXISTS** | KEEP | `/api/tool/call` dispatches to agent registry for any registered tool. `/api/tools/list` returns all tools. |
| 8 | MCP server management (scan, configure, generate configs) | P0 | **EXISTS** | KEEP | Scans 12 known MCP servers, generates configs for Crush (`crush.json`) and Claude Code (`.claude.json`). |
| 9 | LSP server management (scan, install) | P0 | **EXISTS** | KEEP | 16 known LSP servers with install commands. `InstallForLanguages()` for batch installs. |
| 10 | Skills management (CRUD, deploy, built-in skills) | P0 | **EXISTS** | KEEP | 5 built-in skills (env-setup, git-workflow, api-design, debug-assist, code-review). YAML frontmatter format. Deploy to Crush + Claude Code. |
| 11 | Conversation persistence (JSON file store) | P0 | **EXISTS** | KEEP | `ConversationStore` with JSON persistence, auto-summarization at 80K tokens. |
| 12 | API key encryption (AES-256-GCM) | P0 | **EXISTS** | KEEP | `internal/secret/` with encrypt/decrypt. Keys encrypted at rest in config.yaml. |
| 13 | Config management (YAML, XDG paths, defaults) | P0 | **EXISTS** | KEEP | Full config schema with profile, AI providers, terminal, tools, SSH. Legacy migration from `~/.muyue`. |
| 14 | Studio tab (AI chat, SSE streaming, tool calls) | P0 | **EXISTS** | KEEP | Full chat UI with SSE streaming, tool call visualization, thinking blocks, markdown rendering. |
| 15 | Shell tab (PTY terminal, tabs, SSH connections) | P0 | **EXISTS** | KEEP | xterm.js with WebSocket PTY, tab management (max 7), SSH connection support, 6 terminal themes. |
| 16 | Config tab (profile, providers, theme, language, skills) | P0 | **EXISTS** | KEEP | Two-column layout with profile editing, provider management, key validation, terminal settings. |
| 17 | First-run profiling wizard (TUI) | P0 | **EXISTS** | KEEP | Charmbracelet/huh TUI wizard: name, pseudo, email, languages, editor, AI provider. Scored suggestions. |
| 18 | Onboarding wizard (web) | P0 | **EXISTS** | KEEP | React-based web wizard for desktop mode. |
| 19 | i18n (FR/EN, keyboard layout awareness) | P0 | **EXISTS** | KEEP | Full FR/EN translations, AZERTY/QWERTY/QWERTZ layouts affecting shortcut display. |
| 20 | Theming (4 cyberpunk themes, CSS custom properties) | P0 | **EXISTS** | KEEP | 4 themes (Red, Pink, Blue, Green) with 30+ CSS variables. Runtime injection. |
| 21 | Workflow engine (Plan→Execute) | P0 | **EXISTS** | KEEP | State machine with steps (tool_call, condition, approval). JSON persistence. SSE streaming execution. |
### P0 — Needs Implementation/Completion
| # | Feature | Priority | Status | Decision | Description |
|---|---------|----------|--------|----------|-------------|
| 22 | Dashboard tab (tools grid, notifications, quick actions) | P0 | **PARTIAL** | KEEP, BUILD | Currently shows empty workflow/activity placeholders. Needs: tools grid with status badges, update notifications, quick actions (install missing, check updates, rescan, configure MCP). |
| 23 | Shell AI panel (real AI backend) | P0 | **EXISTS** | KEEP | Was fake, now uses `/api/shell/chat` with real AI backend + tool calling. Functional. |
| 24 | Tool updates (check + auto-update) | P0 | **EXISTS** | KEEP | `internal/updater/` checks versions and runs auto-updates. API + CLI endpoints wired. |
### P1 — Post-Launch
| # | Feature | Priority | Status | Decision | Description |
|---|---------|----------|--------|----------|-------------|
| 25 | AI-generated skills (via Studio chat) | P1 | **STUBBED** | KEEP | `BuildAIGeneratePrompt()` exists but CLI `skills generate` is a stub. Need to wire to orchestrator. |
| 26 | SSH test connectivity | P1 | **STUBBED** | KEEP | `handleSSHTest()` returns "not implemented". Add `net.DialTimeout` check. |
| 27 | Conversation list/switch (multiple conversations) | P1 | **PARTIAL** | KEEP | `/api/conversations` list + delete exist. No create/switch/load. Need multi-conversation support in Studio. |
| 28 | Dashboard activity log with real events | P1 | **MISSING** | KEEP | Wire install/scan/update events to a notification system that Dashboard renders. |
| 29 | Starship prompt integration (multi-theme) | P1 | **EXISTS** | KEEP | 3 theme configs (charm, zerotwo, default). `handleApplyStarshipTheme` writes TOML + patches RC files. |
| 30 | Terminal settings persistence (font, theme) | P1 | **EXISTS** | KEEP | Settings saved to config, loaded on startup. |
### P2 — Nice-to-Have
| # | Feature | Priority | Status | Decision | Description |
|---|---------|----------|--------|----------|-------------|
| 31 | Background daemon (`internal/daemon/`) | P2 | **MISSING** | DEFER | README mentions it. Not needed for launch. Tools can run on-demand. |
| 32 | HTML preview server (`internal/preview/`) | P2 | **MISSING** | DROP | Use browser or IDE instead. Not Muyue's job. |
| 33 | AI proxy agents (`internal/proxy/`) | P2 | **MISSING** | DROP | Direct provider communication is sufficient. No proxy layer needed. |
### DROPPED
| # | Feature | Reason | Replacement |
|---|---------|--------|-------------|
| 34 | HTML preview server | Not core value. IDEs handle this. | Browser / VS Code Live Preview |
| 35 | AI proxy agents | Adds complexity without benefit for local-first tool. | Direct provider API calls |
| 36 | MCP server registry / marketplace | Out of scope. | MCPM (`mcpm install <server>`) |
| 37 | Sandboxed code execution | Out of scope. Requires infra. | Daytona sandboxes |
| 38 | Dev container management | Out of scope. | DevPod |
| 39 | Full IDE features (file tree, debugger) | Out of scope. | VS Code / Zed / Neovim |
| 40 | LSP client mode (connecting to LSPs) | Out of scope. Muyue installs LSPs, doesn't consume them. | IDE handles LSP client |
---
## 3. User Flows
### 3.1 First-Time User Opens `muyue`
```
1. User runs `muyue` (or downloaded binary)
2. No config exists → loadOrSetupConfig() detects first run
3. Profiler TUI wizard launches:
a. Asks: name, pseudo, email
b. Scans system → detects languages → shows scored language options
c. Detects editors → shows scored editor options
d. Shows AI provider options → user picks one
4. If selected provider has no API key → asks for key (masked input)
5. Config saved to ~/.config/muyue/config.yaml (API key encrypted)
6. Built-in skills installed to ~/.muyue/skills/
7. MCP configs generated for Crush + Claude Code
8. Desktop server starts on port 8080
9. Browser opens to http://127.0.0.1:8080
10. Onboarding wizard checks if profile is empty → shows web wizard as fallback
11. Dashboard tab loads → shows tools grid (some installed, some missing)
```
**Edge cases:**
- Config file exists but is corrupted → show error, offer `muyue setup` to recreate
- No internet → profiler still works (local scan only), AI features unavailable
- API key invalid → doctor command detects, Config tab shows "Invalid key" badge
### 3.2 Returning User Opens `muyue`
```
1. User runs `muyue`
2. Config exists → loads from ~/.config/muyue/config.yaml
3. Desktop server starts → browser opens (or reconnects)
4. Previous conversation loaded from conversation.json
5. Dashboard shows current tool status (cached, 5-min TTL)
6. If checkOnStart=true → background update check runs
7. User picks up where they left off
```
### 3.3 User Installs a Missing Tool from Dashboard
```
1. Dashboard shows tools grid with status badges:
- Green ✓ = installed
- Red ✗ = missing
- Yellow ⟳ = update available
2. User clicks "Install" on a missing tool (e.g., "pnpm")
3. Frontend calls POST /api/install {"tools": ["pnpm"]}
4. Backend spawns installer.InstallTool("pnpm") in goroutine
5. Installer checks if already installed → if yes, returns success
6. Installer runs `npm install -g pnpm`
7. Result returned: {"status": "done", "tools": ["pnpm"], "results": [{...}]}
8. Frontend updates tool status badge to green ✓
9. Activity log entry added: "Installed pnpm"
10. System scan cache invalidated
```
**Edge cases:**
- Install fails (permission denied) → show error in results, suggest `sudo` or manual install
- Tool requires Node.js but Node isn't installed → installer returns "npx not found, install node first"
- Multiple tools installed in parallel → `sync.WaitGroup` handles concurrent installs
### 3.4 User Starts a Chat in Studio
```
1. User clicks Studio tab (Ctrl+2)
2. Chat history loaded from /api/chat/history
3. If no history → welcome message shown
4. User types message in textarea, presses Enter
5. Frontend calls POST /api/chat {"message": "...", "stream": true}
6. SSE connection opens
7. Backend:
a. Adds message to conversation store
b. Checks if summarization needed (>80K tokens)
c. Creates orchestrator with active provider
d. Sets system prompt (Studio prompt with agent context)
e. Sets tools (all 10 agent tools as OpenAI function specs)
f. Sends to AI provider API
8. Streaming begins:
a. Content chunks → SSE {"content": "char"} events
b. Tool calls → SSE {"tool_call": {...}} events
c. Tool results → SSE {"tool_result": {...}} events
d. Max 15 tool iterations
9. Frontend renders:
a. Text content streamed character-by-character
b. Tool calls shown as expandable blocks with icon + status
c. Thinking blocks (if any) shown with spinner
10. Final response stored in conversation
11. SSE {"done": "true"} closes stream
```
**Edge cases:**
- AI provider returns error → SSE error event, shown as red message
- Tool execution times out → error result returned to AI, may retry
- No active provider configured → 503 error, redirect to Config tab
- API key invalid → 401 error, show "Configure your API key" prompt
### 3.5 User Runs a Plan→Execute Workflow
```
1. User types `/plan Set up a Go project with Docker` in Studio
2. Frontend calls POST /api/workflow/plan {"goal": "Set up a Go project..."}
3. Backend:
a. Creates Planner with AI orchestrator
b. Sends goal to AI with planning prompt
c. AI generates JSON array of steps
d. Planner parses response into []Step
e. Workflow Engine creates workflow with steps
4. Workflow returned to frontend with ID and steps
5. Frontend shows workflow panel:
- Step 1: "Check Go installation" → tool: terminal, args: {command: "go version"}
- Step 2: "Create project directory" → tool: terminal, args: {command: "mkdir -p ..."}
- Step 3: "Initialize Go module" → tool: terminal, args: {command: "go mod init ..."}
- etc.
6. User clicks "Execute"
7. Frontend calls POST /api/workflow/execute/{id}?stream=true
8. SSE stream:
a. Each step: {"event": "started", "step": {...}}
b. On completion: {"event": "done", "step": {...}}
c. On failure: {"event": "failed", "step": {...}}
d. If approval step: {"event": "awaiting_approval", "step": {...}}
9. User can approve/skip steps via POST /api/workflow/approve/{id}
10. Final event: {"event": "workflow_done", "status": "done|failed"}
```
**Edge cases:**
- AI generates invalid JSON → planner returns error, shown in chat
- Step fails mid-workflow → remaining steps skipped, workflow marked "failed"
- Approval step → execution pauses until user approves
- Workflow exceeds 10 steps → planner prompt limits to 10
### 3.6 User Opens Shell, Connects via SSH
```
1. User clicks Shell tab (Ctrl+3)
2. Default "Local Shell" tab created with xterm.js terminal
3. WebSocket connects to /api/ws/terminal with {type: "shell", data: ""}
4. Backend creates PTY via creack/pty, pipes I/O through WebSocket
5. User sees their shell prompt (starship if configured)
6. To add SSH tab:
a. User clicks "+" → dropdown shows:
- System terminals (zsh, bash, fish)
- Saved SSH connections (from config)
- "Add SSH connection" button
b. User selects saved connection or adds new one
c. New tab created with {type: "ssh", data: JSON.stringify({host, port, user, key_path})}
d. Backend establishes SSH connection, creates PTY
e. Tab shows connected indicator (green dot)
7. User can rename tabs (double-click), close tabs (×), switch with Alt+1-7
8. AI assistant panel on right:
a. User types question
b. Frontend calls POST /api/shell/chat with message + terminal context
c. AI responds with shell-aware answers (commands, explanations)
d. Can execute tools (terminal, read_file, etc.) to help user
```
**Edge cases:**
- SSH connection fails → tab shows "Connection error" in terminal
- WebSocket disconnects → terminal shows "Connection closed" message
- Tab limit (7) reached → "+" button disabled
- SSH key not found → connection fails, suggest key path
### 3.7 User Changes AI Provider
```
1. User clicks Config tab (Ctrl+4)
2. "AI Providers" panel shows list of providers:
- MiniMax (active) — Key configured ✓
- Z.AI — No key
- Anthropic — No key
- OpenAI — No key
- Ollama — No key (local)
3. User clicks "Configure" on Anthropic
4. Modal opens with fields: API Key, Model, Base URL
5. User enters API key
6. User clicks "Validate" → POST /api/providers/validate
7. Backend sends test request to Anthropic API with key
8. Response: {"status": "valid"} or error
9. User clicks "Activate" → provider set active, others deactivated
10. Config saved → new orchestrator instances use Anthropic
```
**Edge cases:**
- Key validation fails → show "Invalid key" badge, don't save
- No internet → validation times out, show "Connection failed"
- Ollama selected but not running → user sees local URL, no validation needed
- Switching provider mid-conversation → new messages use new provider, old messages preserved
### 3.8 User Manages MCP Servers
```
1. User opens Config tab → MCP section
OR: User runs `muyue mcp scan` from CLI
2. System scans 12 known MCP servers (filesystem, github, git, fetch, memory, etc.)
3. Each server shows: name, category, installed status (npx available)
4. User clicks "Configure MCP" → POST /api/mcp/configure
5. Backend:
a. Generates MCP config for Crush: ~/.config/crush/crush.json → {"mcps": {...}}
b. Generates MCP config for Claude Code: ~/.claude.json → {"mcpServers": {...}}
c. Core servers: filesystem, fetch, memory
d. Provider-specific: minimax-web-search, minimax-image (if API key set)
e. Claude-specific: sequential-thinking
6. Configs written with 0600 permissions
```
**Edge cases:**
- Existing configs not overwritten (merged) — `writeMCPConfig` merges into existing JSON
- No API key for provider-specific servers → those servers omitted
- Crush or Claude Code not installed → configs still generated (for when they are installed)
### 3.9 User Manages LSP Servers
```
1. User runs `muyue lsp scan` from CLI
OR: views LSP section in Config tab
2. System checks 16 known LSP servers
3. Each shows: name, language, command path, installed status
4. User installs specific LSP:
- CLI: `muyue lsp install gopls`
- API: POST /api/lsp/install {"name": "gopls"}
5. Backend runs install command (e.g., `go install golang.org/x/tools/gopls@latest`)
6. Result: success or error
```
**Edge cases:**
- LSP has no auto-install command (e.g., clangd) → return "install manually" message
- Install fails (network error) → show error, suggest retry
- Language mapping: TypeScript installs 4 servers (TS, JSON, HTML, CSS)
### 3.10 User Creates/Deploys a Skill
```
1. User runs `muyue skills init` → installs 5 built-in skills to ~/.muyue/skills/
2. User creates custom skill:
- Manually: create ~/.muyue/skills/my-skill/SKILL.md with YAML frontmatter
- CLI: `muyue skills generate my-skill "Does X for Y" crush`
- API: POST /api/skills (via Config tab or Studio chat)
3. SKILL.md format:
```yaml
---
name: my-skill
description: What it does
author: username
version: 1.0.0
target: crush|claude|both
tags: [tag1, tag2]
---
# Skill instructions in markdown
```
4. Deploy: `muyue skills deploy`
5. Skill copied to:
- Crush: ~/.config/crush/skills/my-skill/SKILL.md
- Claude Code: ~/.claude/skills/my-skill/SKILL.md
```
**Edge cases:**
- Skill already exists at target → overwritten
- Target is "both" → deployed to both Crush and Claude
- Delete removes from all locations (source + targets)
### 3.11 User Runs `muyue scan` from CLI
```
1. User runs `muyue scan`
2. Scanner runs full system scan (tools, runtimes, shell, git)
3. Output: formatted table with columns: Tool, Version, Status, Path
4. Summary line: "Installed: 8/14"
5. With --json flag: full JSON output
```
### 3.12 User Runs `muyue doctor` from CLI
```
1. User runs `muyue doctor`
2. Three checks run:
a. System scan → shows installed/missing tools
b. Config check → loads config, validates profile
c. Connectivity check → HEAD requests to AI provider endpoints
3. Output: diagnostic report with ✓/✗ indicators
4. User sees what's broken and can take action
```
---
## 4. API Contract
### Existing Endpoints (37 routes)
| Method | Path | Request Body | Response Body | Status |
|--------|------|-------------|---------------|--------|
| GET | `/api/info` | — | `{name, version, author}` | EXISTS |
| GET | `/api/system` | — | `{system: {os, arch, platform, shell, ...}}` | EXISTS |
| GET | `/api/tools` | — | `{tools: [{name, installed, version, path}], total}` | EXISTS |
| GET | `/api/config` | — | `{profile, terminal, bmad}` | EXISTS |
| GET | `/api/providers` | — | `{providers: [{name, model, active, ...}]}` | EXISTS |
| GET | `/api/skills` | — | `{skills: [...], count}` | EXISTS |
| GET | `/api/lsp` | — | `{servers: [{name, language, command, installed}]}` | EXISTS |
| GET | `/api/mcp` | — | `{servers: [...], configured}` | EXISTS |
| GET | `/api/updates` | — | `{updates: [{tool, current, latest, needsUpdate}]}` | EXISTS |
| GET | `/api/editors` | — | `{editors: [{name, installed, version, path}]}` | EXISTS |
| GET | `/api/terminal/sessions` | — | `{ssh: [...], system: [...]}` | EXISTS |
| GET | `/api/terminal/themes` | — | `{themes: [{id, name}]}` | EXISTS |
| GET | `/api/chat/history` | — | `{messages: [...], tokens}` | EXISTS |
| GET | `/api/tools/list` | — | `{tools: [...], count}` | EXISTS |
| GET | `/api/workflow/list` | — | `{workflows: [...], count}` | EXISTS |
| GET | `/api/workflow/{id}` | — | `{id, name, steps, status, ...}` | EXISTS |
| GET | `/api/conversations` | — | `{conversations: [...]}` | EXISTS |
| GET | `/api/ssh/connections` | — | `{connections: [...]}` | EXISTS |
| POST | `/api/scan` | — | `{status: "ok"}` | EXISTS |
| POST | `/api/install` | `{tools: [string]}` | `{status, tools, results: [{tool, success, message}]}` | EXISTS |
| POST | `/api/mcp/configure` | — | `{status: "ok"}` | EXISTS |
| POST | `/api/terminal` | `{command, cwd}` | `{output, error}` | EXISTS |
| POST | `/api/chat` | `{message, stream}` | SSE stream or `{content}` | EXISTS |
| POST | `/api/chat/clear` | — | `{status: "ok"}` | EXISTS |
| POST | `/api/tool/call` | `{tool, args}` | `{success, tool, result, error}` | EXISTS |
| POST | `/api/shell/chat` | `{message, context, history, cwd, platform, stream}` | SSE stream or `{content, tool_calls}` | EXISTS |
| POST | `/api/workflow` | `{name, description, type}` | `{id, name, steps, status, ...}` | EXISTS |
| POST | `/api/workflow/plan` | `{goal}` | `{id, name, steps, status, ...}` | EXISTS |
| POST | `/api/workflow/execute/{id}` | `?stream=true` optional | SSE stream or workflow object | EXISTS |
| POST | `/api/workflow/approve/{id}` | `{step_id}` | `{status: "approved"}` | EXISTS |
| POST | `/api/lsp/install` | `{name}` | `{success, server}` or `{success, error}` | EXISTS |
| POST | `/api/skills/deploy` | `{name}` optional | `{status, skill}` | EXISTS |
| POST | `/api/config/reset` | — | `{status: "ok"}` | EXISTS |
| POST | `/api/providers/validate` | `{name, api_key, model, base_url}` | `{status: "valid"}` or error | EXISTS |
| POST | `/api/update/run` | `{tool}` optional | `{status, updated}` or `{status, tool}` | EXISTS |
| POST | `/api/ssh/test` | `{host, port, user}` | `{success, message}` (stubbed) | PARTIAL |
| POST | `/api/starship/apply-theme` | `{theme}` | `{status, config}` | EXISTS |
| PUT | `/api/preferences` | `{language, keyboard_layout}` | `{status: "ok"}` | EXISTS |
| PUT | `/api/config/profile` | `{name, pseudo, email, editor, shell}` | `{status: "ok"}` | EXISTS |
| PUT | `/api/config/provider` | `{name, api_key, model, base_url, active}` | `{status: "ok"}` | EXISTS |
| PUT | `/api/terminal/settings` | `{font_size, font_family, theme}` | `{status, theme}` | EXISTS |
| DELETE | `/api/conversations/{id}` | — | `{status: "deleted"}` | EXISTS |
| DELETE | `/api/terminal/sessions/{name}` | — | (removes SSH connection) | EXISTS |
| WS | `/api/ws/terminal` | `{type, data}` | `{type, data}` | EXISTS |
### Error Response Format (all endpoints)
```json
{"error": "Human-readable error message"}
```
HTTP status codes: 400 (bad request), 401 (unauthorized), 404 (not found), 405 (method not allowed), 500 (internal), 503 (service unavailable — AI provider not configured).
### SSE Event Format
```
data: {"content": "character"}
data: {"tool_call": {"tool_call_id": "...", "name": "...", "args": "..."}}
data: {"tool_result": {"tool_call_id": "...", "content": "...", "is_error": false}}
data: {"done": "true"}
```
---
## 5. CLI Contract
### Root Command
```
muyue Launch desktop app (opens browser)
muyue --port=8080 Launch on specific port
muyue --no-open Launch without opening browser
```
### Subcommands
| Command | Flags | Output | Status |
|---------|-------|--------|--------|
| `muyue scan` | `--json` | Table or JSON of tools/runtimes | EXISTS |
| `muyue install [tool]` | `--yes` | Install progress per tool | EXISTS |
| `muyue update [tool]` | `--check` | Table of versions + status | EXISTS |
| `muyue setup` | — | Interactive TUI wizard | EXISTS |
| `muyue config` | — | (subcommand stub) | PARTIAL |
| `muyue doctor` | — | Diagnostic report | EXISTS |
| `muyue version` | — | `Muyue version X.Y.Z` | EXISTS |
| `muyue lsp scan` | — | Table of LSP servers | EXISTS |
| `muyue lsp install <name>` | — | Install progress | EXISTS |
| `muyue mcp config` | — | Confirmation message | EXISTS |
| `muyue mcp scan` | — | Table of MCP servers | EXISTS |
| `muyue skills list` | — | Table of skills | EXISTS |
| `muyue skills init` | — | Confirmation | STUBBED |
| `muyue skills show <name>` | — | Skill details | EXISTS |
| `muyue skills generate <name> <desc>` | — | (stub) | STUBBED |
| `muyue skills deploy` | — | Confirmation | EXISTS |
| `muyue skills delete <name>` | — | Confirmation | EXISTS |
### CLI Commands Needing Work
| Command | Issue | Fix |
|---------|-------|-----|
| `muyue config` | No subcommands (get/set are defined but not registered) | Register `config get <key>` and `config set <key> <value>` as subcommands |
| `muyue skills init` | Just prints message, doesn't call `skills.InstallBuiltinSkills()` | Wire to actual function |
| `muyue skills generate` | Just prints message, doesn't call AI | Wire to orchestrator |
| `muyue install` | Passes `nil` config to installer | Pass loaded config |
---
## 6. Data Model
### 6.1 Config YAML Schema (`~/.config/muyue/config.yaml`)
```yaml
version: "0.2.1"
profile:
name: "Augustin"
pseudo: "muyue"
email: "augustin@example.com"
languages: ["go", "typescript", "python"]
preferences:
editor: "nvim"
shell: "zsh"
theme: "cyberpunk-red" # cyberpunk-red | cyberpunk-pink | midnight-blue | matrix-green
default_ai: "minimax"
auto_update: true
check_on_start: true
language: "fr" # fr | en
keyboard_layout: "azerty" # azerty | qwerty | qwertz
ai:
providers:
- name: "minimax"
api_key: "enc:AES256GCM..." # encrypted at rest
base_url: "https://api.minimax.io/v1"
model: "MiniMax-M2.7"
active: true
- name: "zai"
model: "glm"
active: false
- name: "anthropic"
api_key: "enc:AES256GCM..."
model: "claude-sonnet-4-20250514"
active: false
- name: "openai"
api_key: "enc:AES256GCM..."
base_url: "https://api.openai.com/v1"
model: "gpt-4o"
active: false
- name: "ollama"
model: "llama3"
base_url: "http://localhost:11434/api"
active: false
tools:
- name: "crush"
installed: true
version: "v1.2.3"
auto_update: true
bmad:
installed: true
version: "latest"
global: true
terminal:
custom_prompt: true
prompt_theme: "zerotwo" # charm | zerotwo | default
ssh:
- name: "prod-server"
host: "192.168.1.100"
port: 22
user: "deploy"
key_path: "~/.ssh/id_rsa"
font_size: 14
font_family: "'JetBrains Mono', monospace"
theme: "default" # default | monokai | gruvbox | nord | solarized-dark | dracula
```
### 6.2 Conversation JSON Schema (`~/.config/muyue/conversation.json`)
```json
{
"messages": [
{
"id": "20260422150000.000-1234567890",
"role": "user|assistant|system",
"content": "message text or JSON-encoded {content, tool_calls}",
"time": "2026-04-22T15:00:00Z"
}
],
"summary": "Auto-generated conversation summary when >80K tokens",
"created_at": "2026-04-22T15:00:00Z",
"updated_at": "2026-04-22T15:30:00Z"
}
```
### 6.3 Skill SKILL.md Format
```markdown
---
name: skill-name
description: What this skill does
author: muyue
version: 1.0.0
target: both # crush | claude | both
tags: [tag1, tag2]
---
# Skill Title
Instructions for the AI agent in markdown.
Includes: when to activate, step-by-step instructions, examples, error handling.
```
### 6.4 MCP Config JSON Format
**For Crush** (`~/.config/crush/crush.json`):
```json
{
"mcps": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
},
"fetch": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-fetch"]
}
}
}
```
**For Claude Code** (`~/.claude.json`):
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
},
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}
}
}
```
### 6.5 Workflow JSON Schema (`~/.config/muyue/workflows.json`)
```json
[
{
"id": "wf-1234567890",
"name": "Plan: Set up Go project",
"description": "Full goal description",
"type": "plan_execute",
"steps": [
{
"id": "step-0",
"name": "Check Go installation",
"type": "tool_call",
"tool": "terminal",
"args": {"command": "go version"},
"status": "pending|running|done|failed|awaiting_approval|skipped",
"result": "",
"error": "",
"depends_on": [],
"started_at": null,
"ended_at": null
}
],
"status": "pending|running|done|failed",
"created_at": "2026-04-22T15:00:00Z",
"updated_at": "2026-04-22T15:00:00Z"
}
]
```
---
## 7. Technical Decisions
### 7.1 CLI Framework: **Keep Cobra** ✓
**Decision**: Keep `spf13/cobra` (already in `go.mod`, already used for all 11 subcommands).
**Rationale**: Cobra is the de-facto standard for Go CLIs. All commands are already implemented. No benefit to switching to `urfave/cli`.
### 7.2 HTTP Router: **Keep stdlib `http.ServeMux`** ✓
**Decision**: Keep `net/http.ServeMux`. Do NOT add chi, echo, or gin.
**Rationale**:
- 37 routes registered. Stdlib handles this fine.
- Go 1.22+ `ServeMux` supports method-based routing (`GET /api/foo`).
- Adding a framework adds a dependency and learning curve for no benefit.
- Performance is irrelevant at localhost scale.
**One improvement**: Use Go 1.22 method-based patterns to clean up manual method checks:
```go
mux.HandleFunc("GET /api/tools", s.handleTools)
mux.HandleFunc("POST /api/install", s.handleInstall)
```
### 7.3 WebSocket: **Keep gorilla/websocket** ✓
**Decision**: Keep `gorilla/websocket` for terminal PTY.
**Rationale**: Already working for terminal WebSocket. Only used for one endpoint (`/api/ws/terminal`). No need for a framework.
### 7.4 Frontend Framework: **Keep vanilla React** ✓
**Decision**: Keep React 19 + vanilla state management. Do NOT add zustand or react-query.
**Rationale**:
- 4 components, ~1200 lines total. State is simple (tab switching, form inputs, chat messages).
- Adding zustand/redux would be over-engineering for this scale.
- `useState` + `useCallback` + `useRef` is sufficient.
- SSE handling is custom and wouldn't benefit from react-query.
**One consideration**: If Dashboard grows complex (many sub-components), extract a `useApi` custom hook pattern for data fetching.
### 7.5 Async Operations: **SSE for everything** ✓
**Decision**: Use SSE (Server-Sent Events) for all streaming operations (chat, workflow execution). Use synchronous JSON for non-streaming operations (install, scan).
**Rationale**:
- SSE is already implemented for chat and workflow execution.
- Install operations are fast enough to be synchronous (wait for all goroutines, return results).
- No polling needed.
- WebSocket only for terminal PTY (bidirectional needed).
### 7.6 Workflow Engine: **State machine** ✓
**Decision**: Keep the current state machine approach. Do NOT convert to a DAG.
**Rationale**:
- Plans are linear sequences (step 1 → step 2 → step 3).
- Dependencies are simple (wait for previous step).
- DAG adds complexity (topological sort, parallel execution) for no benefit.
- The current `depends_on` field supports basic ordering. Parallel execution can be added later if needed via `TypeParallel` step type (already defined but not implemented).
### 7.7 Styling: **Keep CSS custom properties** ✓
**Decision**: Keep CSS custom properties + 4 theme objects. Do NOT add Tailwind or CSS-in-JS.
**Rationale**:
- 30+ CSS variables already define the full theme system.
- Theme switching works by setting `document.documentElement.style.setProperty()`.
- Adding Tailwind would conflict with the existing CSS architecture.
- Current CSS is ~1000 lines and well-structured.
---
## 8. Delegation Strategy
### What Muyue delegates to existing tools
| Feature | Delegated To | Integration Method | UI |
|---------|-------------|-------------------|-----|
| **Code editing / AI coding** | Crush (`crush run`) | `crush_run` agent tool → spawns `crush run <task>` | Studio chat invokes tool, Shell AI panel invokes tool |
| **Code editing / AI coding** | Claude Code | Skills deployed to `~/.claude/skills/` | Config tab shows deployment status |
| **MCP server discovery** | MCPM (`mcpm`) | CLI passthrough suggestion | Doctor command suggests `mcpm install <server>` if server missing |
| **MCP server routing** | McpMux | Not needed | Muyue generates per-tool configs directly |
| **Dev environments / containers** | DevPod | CLI passthrough suggestion | Doctor suggests DevPod if container needed |
| **IDE features** | VS Code / Zed / Neovim | Config integration (editor preference) | Config tab sets editor, LSPs installed for editor |
| **Terminal prompt** | Starship | Config generation (`starship.toml` + RC file patching) | Config tab applies themes |
| **Git operations** | `git` CLI | Agent `terminal` tool runs git commands | Studio / Shell AI can execute git commands |
### Integration Patterns
1. **Config Generation** (primary pattern): Muyue generates config files for external tools (Crush `crush.json`, Claude `.claude.json`, Starship `starship.toml`). This is the cleanest integration — no API coupling, no version lock-in.
2. **CLI Wrapping**: Muyue invokes external CLIs (`crush run`, `git`, `go install`) through the agent `terminal` tool. Stdout/stderr captured and returned to AI.
3. **Suggestion**: Muyue suggests tools the user should install separately (MCPM, DevPod) but doesn't wrap them. `muyue doctor` output includes recommendations.
4. **Skills Deployment**: Muyue's skills system deploys SKILL.md files to both Crush and Claude Code directories. Both tools natively understand this format.
---
## 9. Implementation Priority
### Phase 1: Dashboard Completion (P0 gap)
The only significant P0 gap is the Dashboard. Current state: empty placeholders.
**Dashboard must have:**
1. **Tools Grid** — Cards for each scanned tool showing name, status badge (installed/missing/update), version, install button
2. **Quick Actions** — Buttons: "Install missing tools", "Check for updates", "Rescan system", "Configure MCP"
3. **Update Notifications** — List of tools with available updates, with "Update" buttons
4. **Activity Log** — Scrollable list of recent events (installs, scans, config changes) with timestamps
**Implementation approach:**
- Fetch from `/api/tools`, `/api/updates`, `/api/editors` on mount
- Quick actions call existing API endpoints (`POST /api/install`, `POST /api/scan`, `POST /api/mcp/configure`)
- Activity log: client-side event accumulation (no backend change needed for MVP)
### Phase 2: CLI Polish (P0 gaps)
1. Wire `muyue skills init` to `skills.InstallBuiltinSkills()`
2. Wire `muyue skills generate` to orchestrator
3. Register `muyue config get` and `muyue config set` subcommands
4. Pass loaded config to installer in `muyue install`
### Phase 3: P1 Features
1. AI-generated skills via Studio chat
2. SSH connectivity test
3. Multi-conversation support in Studio
4. Real event-based activity log
---
## 10. Architecture Summary
```
┌─────────────────────────────────────────────────────────┐
│ Browser (React SPA) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Dashboard │ │ Studio │ │ Shell │ │ Config │ │
│ │(tools, │ │(AI chat, │ │(xterm.js,│ │(profile, │ │
│ │ updates, │ │ tool │ │ WS PTY, │ │provider, │ │
│ │ actions) │ │ calls) │ │ AI panel)│ │ theme) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────┬──────────────────────────────────┘
│ HTTP/SSE/WS
┌──────────────────────┴──────────────────────────────────┐
│ Go HTTP Server │
│ ┌────────────────────────────────────────────────────┐ │
│ │ api.Server (37 routes) │ │
│ │ /api/chat → SSE stream + tool calling loop │ │
│ │ /api/shell/chat → SSE stream + tool calling loop │ │
│ │ /api/ws/terminal → WebSocket PTY │ │
│ │ /api/install → parallel tool installation │ │
│ │ /api/workflow/* → CRUD + plan + execute │ │
│ └────────────────────────────────────────────────────┘ │
│ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ │
│ │Scanner │ │ Installer │ │ Updater │ │ MCP │ │
│ │(14 tools,│ │(12 tools, │ │(version │ │(12 known │ │
│ │ 8 runts, │ │ platform- │ │ check + │ │ servers, │ │
│ │ 8 edtrs) │ │ specific) │ │ auto-upd)│ │ config │ │
│ └──────────┘ └────────────┘ └──────────┘ │ gen) │ │
│ ┌──────────┐ ┌────────────┐ ┌──────────┐ └──────────┘ │
│ │ LSP │ │ Skills │ │ Workflow │ │
│ │(16 known │ │(CRUD + │ │(Plan→ │ │
│ │ servers) │ │ deploy + │ │ Execute │ │
│ │ │ │ builtins) │ │ engine) │ │
│ └──────────┘ └────────────┘ └──────────┘ │
│ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ │
│ │Orchestrtr│ │ Agent │ │ Secret │ │ Config │ │
│ │(OpenAI- │ │ Registry │ │(AES-256- │ │(YAML, │ │
│ │ compat, │ │(10 tools: │ │ GCM key │ │ XDG, │ │
│ │ multi- │ │ terminal, │ │ encrypt) │ │ encrypted│ │
│ │ provider)│ │ files, │ │ │ │ API keys)│ │
│ │ │ │ grep, etc)│ │ │ │ │ │
│ └──────────┘ └────────────┘ └──────────┘ └──────────┘ │
└──────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────┐
│ External Tools/Agents │
│ Crush, Claude Code, │
│ Starship, MCP servers │
└─────────────────────────┘
```
### Key Dependencies
| Dependency | Version | Purpose |
|-----------|---------|---------|
| `spf13/cobra` | v1.10.2 | CLI framework |
| `charmbracelet/huh` | v1.0.0 | TUI forms (profiler, API key input) |
| `charmbracelet/bubbletea` | v1.3.10 | TUI framework (indirect) |
| `gorilla/websocket` | v1.5.3 | Terminal WebSocket |
| `creack/pty/v2` | v2.0.1 | PTY for terminal |
| `gopkg.in/yaml.v3` | v3.0.1 | Config serialization |
| React 19 | — | Frontend UI |
| Vite 8 | — | Frontend build |
| xterm.js | — | Terminal emulator component |
### File Count Summary
| Layer | Files | Lines (approx) |
|-------|-------|---------------|
| Go backend (`internal/`) | 41 `.go` files | ~8,000 |
| CLI commands (`cmd/`) | 12 `.go` files | ~600 |
| Frontend (`web/src/`) | ~20 files | ~3,500 |
| CSS (`web/src/styles/`) | 1 file | ~1,500 |
| **Total** | ~75 files | ~13,600 |
---
## 11. Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|-----------|
| AI provider API changes break orchestrator | Studio/Shell chat stops working | Orchestrator uses OpenAI-compatible format (widely supported). Fallback: user switches provider. |
| Tool install commands change (brew, apt) | Installer fails | Installer returns clear error messages. Doctor command diagnoses. User can install manually. |
| Frontend grows beyond vanilla React manageability | Hard to maintain | At current scale (4 components), this is not a risk. Re-evaluate if components exceed 20. |
| Security: API keys in config file | Key exposure | AES-256-GCM encryption at rest. Config file permissions 0600. |
| Terminal WebSocket security | Remote command execution | Server binds to 127.0.0.1 only. No remote access possible. |
---
*End of Muyue PRD v1.0*