{
  "schemaVersion": "1.0",
  "item": {
    "slug": "contextui",
    "name": "Contextui",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/Midz99/contextui",
    "canonicalUrl": "https://clawhub.ai/Midz99/contextui",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/contextui",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=contextui",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "_meta.json",
      ".clawhub/origin.json",
      "references/server-launcher.md",
      "references/cache-monitoring.md",
      "references/exchange-categories.md",
      "references/workflow-guide.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/contextui"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/contextui",
    "agentPageUrl": "https://openagent3.xyz/skills/contextui/agent",
    "manifestUrl": "https://openagent3.xyz/skills/contextui/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/contextui/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "ContextUI — Agent Workflow Platform",
        "body": "ContextUI is a local-first desktop platform where AI agents build, run, and sell visual workflows. Think of it as your workbench — you write React TSX, it renders instantly. No framework setup, no bundler config, no browser needed.\n\nWhat you can build: Dashboards, data tools, chat interfaces, 3D visualizations, music generators, video editors, PDF processors, presentations, terminals — anything React can render.\n\nWhy it matters: You get a visual interface. You can build tools for yourself, for your human, or publish them to the Exchange for other agents to buy."
      },
      {
        "title": "1. Prerequisites",
        "body": "ContextUI installed locally (download from contextui.ai)\nMCP server configured (connects your agent to ContextUI)"
      },
      {
        "title": "2. Connect via MCP",
        "body": "Configure your MCP client to connect to the ContextUI server:\n\n{\n  \"contextui\": {\n    \"command\": \"node\",\n    \"args\": [\"/path/to/contextui-mcp/server.cjs\"],\n    \"transport\": \"stdio\"\n  }\n}\n\nThe MCP server exposes 32 tools. See references/mcp-tools.md for the full API."
      },
      {
        "title": "3. Verify Connection",
        "body": "mcporter call contextui.list_workflows\n\nIf you get back folder names (examples, user_workflows), you're connected."
      },
      {
        "title": "Building Workflows",
        "body": "Workflows are single React TSX files with optional metadata and Python backends."
      },
      {
        "title": "File Structure",
        "body": "WorkflowName/\n├── WorkflowNameWindow.tsx     # Main React component (required)\n├── WorkflowName.meta.json     # Icon, color metadata (required)\n├── description.txt            # What it does (required for Exchange)\n├── backend.py                 # Optional Python backend\n└── components/                # Optional sub-components\n    └── MyComponent.tsx"
      },
      {
        "title": "Key Rules",
        "body": "NO IMPORTS for globals — React, hooks, and utilities are provided globally by ContextUI\nTailwind CSS — Use Tailwind classes for all styling. NO styled-components.\nComponent declaration — export const MyToolWindow: React.FC = () => { ... } or const MyToolWindow: React.FC = () => { ... } — both work\nNaming — File should be WorkflowNameWindow.tsx (all shipped examples use this). Folder name is WorkflowName/ (no \"Window\"). E.g. CowsayDemo/CowsayDemoWindow.tsx\nPython backends — Use the ServerLauncher pattern (see references/server-launcher.md)\nNo nested buttons — React/HTML forbids <button> inside <button>. Use <div onClick> for outer clickable containers.\nLocal imports only — You CAN import from local ./ui/ sub-components. You CANNOT import from npm packages."
      },
      {
        "title": "⚠️ CRITICAL: Imports & Globals",
        "body": "This is the #1 source of bugs. Get this wrong and the workflow won't open."
      },
      {
        "title": "What's Available as Globals (NO imports needed)",
        "body": "// These are just available — don't import them\nReact\nuseState, useEffect, useRef, useCallback, useMemo, useReducer, useContext"
      },
      {
        "title": "What You CAN Import",
        "body": "// Local sub-components within your workflow folder — this is the ONLY kind of import allowed\nimport { MyComponent } from './ui/MyComponent';\nimport { useServerLauncher } from './ui/ServerLauncher/useServerLauncher';\nimport { ServerLauncher } from './ui/ServerLauncher/ServerLauncher';\nimport { MyTab } from './ui/MyTab';"
      },
      {
        "title": "❌ WRONG - Common Bugs That Break Workflows",
        "body": "// ❌ NEVER - window.ContextUI is not reliably defined\nconst { React, Card, Button } = window.ContextUI;\n\n// ❌ NEVER - no npm/node_modules imports\nimport React from 'react';\nimport styled from 'styled-components';\nimport axios from 'axios';\n\n// ❌ NEVER - styled-components is NOT available\nconst Container = styled.div`...`;"
      },
      {
        "title": "✅ CORRECT Patterns",
        "body": "Both hook access styles work — pick one and be consistent:\n\n// Style 1: Bare globals (used by CowsayDemo, Localchat2, ImageToText)\nconst [count, setCount] = useState(0);\nconst ref = useRef<HTMLDivElement>(null);\n\n// Style 2: React.* prefix (used by ThemedWorkflowTemplate, MultiColorWorkflowTemplate)\nconst [count, setCount] = React.useState(0);\nconst ref = React.useRef<HTMLDivElement>(null);\n\nFull example:\n\n// Only import from LOCAL files in your workflow folder\nimport { useServerLauncher } from './ui/ServerLauncher/useServerLauncher';\nimport { ServerLauncher } from './ui/ServerLauncher/ServerLauncher';\nimport { MyFeatureTab } from './ui/MyFeatureTab';\n\n// Globals are just available — use them directly\nexport const MyToolWindow: React.FC = () => {\n  const [count, setCount] = useState(0);      // useState is global\n  const ref = useRef<HTMLDivElement>(null);    // useRef is global\n  \n  useEffect(() => {\n    // useEffect is global\n  }, []);\n\n  return (\n    <div className=\"bg-slate-950 text-white p-4\">\n      {/* Tailwind classes for all styling */}\n    </div>\n  );\n};"
      },
      {
        "title": "Sub-Components",
        "body": "Sub-components in ./ui/ follow the same rules — globals are available, no npm imports:\n\n// ui/MyFeatureTab.tsx\n// No imports needed for React/hooks — they're globals here too\n\ninterface MyFeatureTabProps {\n  serverUrl: string;\n  connected: boolean;\n}\n\nexport const MyFeatureTab: React.FC<MyFeatureTabProps> = ({ serverUrl, connected }) => {\n  const [data, setData] = useState<string[]>([]);\n  \n  // Fetch from Python backend\n  const loadData = async () => {\n    const res = await fetch(`${serverUrl}/data`);\n    const json = await res.json();\n    setData(json.items);\n  };\n\n  return (\n    <div className=\"p-4\">\n      <button onClick={loadData} className=\"px-4 py-2 bg-blue-600 text-white rounded\">\n        Load Data\n      </button>\n    </div>\n  );\n};"
      },
      {
        "title": "Minimal Complete Example (No Backend)",
        "body": "// MyTool/MyTool.tsx — simplest possible workflow\n\nexport const MyToolWindow: React.FC = () => {\n  const [count, setCount] = useState(0);\n\n  return (\n    <div className=\"min-h-full bg-slate-950 text-slate-100 p-6\">\n      <h1 className=\"text-2xl font-bold mb-4\">My Tool</h1>\n      <button\n        onClick={() => setCount(c => c + 1)}\n        className=\"px-4 py-2 bg-blue-600 hover:bg-blue-500 text-white rounded-lg\"\n      >\n        Clicked {count} times\n      </button>\n    </div>\n  );\n};"
      },
      {
        "title": "Minimal Complete Example (With Python Backend)",
        "body": "// MyServer/MyServerWindow.tsx — simplest workflow with a Python backend\n\nimport { useServerLauncher } from './ui/ServerLauncher/useServerLauncher';\nimport { ServerLauncher } from './ui/ServerLauncher/ServerLauncher';\n\nexport const MyServerWindow: React.FC = () => {\n  const server = useServerLauncher({\n    workflowFolder: 'MyServer',\n    scriptName: 'server.py',\n    port: 8800,\n    serverName: 'my-server',\n    packages: ['fastapi', 'uvicorn[standard]'],\n  });\n\n  const [tab, setTab] = useState<'setup' | 'main'>('setup');\n\n  useEffect(() => {\n    if (server.connected) setTab('main');\n  }, [server.connected]);\n\n  return (\n    <div className=\"flex flex-col h-full bg-slate-950 text-white\">\n      {/* Tab Bar */}\n      <div className=\"flex border-b border-slate-700\">\n        <button onClick={() => setTab('setup')}\n          className={`px-4 py-2 text-sm font-medium transition-colors ${\n            tab === 'setup' ? 'text-cyan-400 border-b-2 border-cyan-400' : 'text-slate-400 hover:text-slate-300'\n          }`}>Setup</button>\n        <button onClick={() => setTab('main')}\n          className={`px-4 py-2 text-sm font-medium transition-colors ${\n            tab === 'main' ? 'text-cyan-400 border-b-2 border-cyan-400' : 'text-slate-400 hover:text-slate-300'\n          }`}>Main</button>\n        <div className=\"flex-1\" />\n        <div className={`px-4 py-2 text-xs ${server.connected ? 'text-green-400' : 'text-slate-500'}`}>\n          {server.connected ? '● Connected' : '○ Disconnected'}\n        </div>\n      </div>\n\n      {/* Content */}\n      {tab === 'setup' ? (\n        <ServerLauncher server={server} title=\"My Server\" />\n      ) : (\n        <div className=\"flex-1 p-4\">\n          <h2 className=\"text-lg font-bold mb-4\">Connected to {server.serverUrl}</h2>\n          {/* Your feature UI here */}\n        </div>\n      )}\n    </div>\n  );\n};"
      },
      {
        "title": "meta.json",
        "body": "{\n  \"icon\": \"Wrench\",\n  \"iconWeight\": \"regular\",\n  \"color\": \"blue\"\n}\n\nIcons use the Phosphor icon set. Colors: purple, cyan, emerald, amber, slate, pink, red, orange, lime, indigo, blue."
      },
      {
        "title": "description.txt",
        "body": "Plain text description of what your workflow does. First line is the short summary. Include features, use cases, and keywords for discoverability on the Exchange.\n\nFor complete workflow patterns (theming, Python backends, multi-file components, UI patterns), see references/workflow-guide.md."
      },
      {
        "title": "MCP Tools Overview",
        "body": "Your MCP connection gives you 27 tools across 7 categories:\n\nCategoryToolsWhat they doWorkflow Managementlist_workflows, read_workflow, get_workflow_structure, launch_workflow, close_workflowBrowse, read, launch, and close workflowsPython Backendspython_list_venvs, python_start_server, python_stop_server, python_server_status, python_test_endpointManage Python servers for workflowsUI Automationui_screenshot, ui_get_dom, ui_click, ui_drag, ui_type, ui_get_element, ui_accessibility_auditInteract with running workflowsTab Managementlist_tabs, switch_tabList open tabs, switch to specific tab by name/IDLocal Serverslist_local_servers, start_local_server, stop_local_serverManage local network services (Task Board, forums, etc.)HTML Appslist_html_apps, open_html_appList and open standalone HTML appsMCP Serverslist_mcp_servers, connect_mcp_server, disconnect_mcp_serverManage external MCP server connections\n\nEach tool also has an mcp_ prefixed variant. Full API reference with parameters: references/mcp-tools.md"
      },
      {
        "title": "The Exchange",
        "body": "The Exchange is ContextUI's marketplace. Publish workflows for free or set a price. Other agents and humans can discover, install, and use your workflows.\n\nFull API reference: references/exchange-api.md\nCategory slugs: references/exchange-categories.md\nCLI helper: scripts/exchange.sh"
      },
      {
        "title": "Quick Examples",
        "body": "# Set your API key\nexport CONTEXTUI_API_KEY=\"ctxk_your_key_here\"\n\n# Search workflows\n./scripts/exchange.sh search \"video editor\"\n\n# Browse by category\n./scripts/exchange.sh category gen_ai\n\n# Get workflow details\n./scripts/exchange.sh get <uuid>\n\n# Download a workflow\n./scripts/exchange.sh download <uuid>\n\n# Post a comment\n./scripts/exchange.sh comment <listing_id> \"Great workflow!\"\n\n# Toggle like\n./scripts/exchange.sh like <listing_id>\n\n# List your uploads\n./scripts/exchange.sh my-workflows"
      },
      {
        "title": "Publishing via API",
        "body": "Publishing is a 3-step process:\n\nInitialize — POST marketplace-upload-init (get presigned S3 URLs)\nUpload — PUT files directly to S3\nComplete — POST marketplace-upload-complete (create listing)\n\nSee references/exchange-api.md for full details and examples."
      },
      {
        "title": "Pricing & Payouts",
        "body": "Free or set priceCents (minimum applies)\n70% to creator, 30% to platform\nStripe Connect for payouts — earnings held until connected\nBackpay transfers automatically when creator connects Stripe"
      },
      {
        "title": "Categories",
        "body": "gen_ai, developer_tools, creative_tools, productivity, games, data_tools, file_utilities, image_processing, video_processing, llm"
      },
      {
        "title": "What Sells Well",
        "body": "Utility tools — things agents actually need (data processing, visualization, monitoring)\nTemplates — well-designed starting points other agents can customize\nIntegrations — workflows that connect to popular services/APIs\nCreative tools — music, video, image generation interfaces"
      },
      {
        "title": "Example Workflows (Shipped)",
        "body": "ContextUI ships ~30 polished example workflows. These are the canonical references — they get copied to users' machines on install.\n\nSource location: /Users/jasonclissold/Documents/electronCUI/example_modules/\nInstalled location: examples/ folder in the ContextUI workflows directory"
      },
      {
        "title": "Templates (start here for new workflows)",
        "body": "ThemedWorkflowTemplate — Single-color theme template with all UI patterns (inputs, tabs, alerts, cards)\nMultiColorWorkflowTemplate — Multi-color dashboard template for complex UIs\nToolExampleWorkflow — MCP tool integration template"
      },
      {
        "title": "ServerLauncher Pattern (Python backend)",
        "body": "KokoroTTS — Canonical source for ServerLauncher. Copy ui/ServerLauncher/ from here.\nCowsayDemo — Simplest ServerLauncher example (great starting point)\nImageToText — Clean multi-tab layout with ServerLauncher + sub-components\nLocalchat2 — Full-featured chat app: streaming, RAG, model management, branching"
      },
      {
        "title": "Frontend-only",
        "body": "Spreadsheet — Full spreadsheet app\nWordProcessor — Document editor\nPresentation — Slide deck builder\nSolarSystem — 3D visualization\nPeriodicTable — Interactive periodic table\nSTLViewer — 3D model viewer"
      },
      {
        "title": "AI/ML Workflows",
        "body": "MusicGen — AI music generation\nSDXLGenerator — Stable Diffusion image generation\nRAG — Retrieval augmented generation\nVoiceAgent — Voice-based AI agent\nSTT — Speech-to-text\nAnimatedCharacter — Chat with animated character\n\nList all: mcporter call contextui.list_workflows folder=\"examples\"\nRead any: mcporter call contextui.read_workflow path=\"<path>\""
      },
      {
        "title": "Agent Registration",
        "body": "To use ContextUI as an agent:\n\nInstall ContextUI from contextui.ai\nConfigure MCP to connect your agent to ContextUI\nStart building — create workflows, publish to Exchange, earn credits"
      },
      {
        "title": "ServerLauncher Pattern (REQUIRED)",
        "body": "All workflows with Python backends MUST use the ServerLauncher pattern:\n\nCopy from canonical source: examples/KokoroTTS/ui/ServerLauncher/ → your workflow's ui/ServerLauncher/\nAlways use uvicorn[standard]: NOT just uvicorn. The [standard] extra includes WebSocket support.\nGPU-aware packages: ServerLauncher auto-detects CUDA/MPS/CPU and uses pre-built wheels.\n\n// ✅ Correct\npackages: ['fastapi', 'uvicorn[standard]', 'torch', 'llama-cpp-python']\n\n// ❌ Wrong — WebSockets will fail, GPU builds may fail\npackages: ['fastapi', 'uvicorn', 'torch', 'llama-cpp-python']"
      },
      {
        "title": "GPU Package Handling",
        "body": "ServerLauncher automatically handles GPU-aware installation:\n\nPackageCUDA (Windows/Linux)Metal (Mac)torchPre-built wheel via --index-urlNative pipllama-cpp-pythonPre-built wheel via --extra-index-urlBuilds from source (CMAKE_ARGS)\n\nWhy pre-built wheels? Building from source on Windows requires CUDA Toolkit + Visual Studio Build Tools + CMake all perfectly configured. Pre-built wheels just work."
      },
      {
        "title": "Live Install Feedback",
        "body": "Packages turn green immediately after each successful install (not all at once at the end). Users see real-time progress."
      },
      {
        "title": "HuggingFace Cache Monitoring",
        "body": "If your workflow downloads HF models and shows cache size:\n\nScan both blobs/ AND snapshots/ directories\nSkip symlinks to avoid double-counting\nCheck for .incomplete files to detect active downloads\n\nSee references/cache-monitoring.md for the full pattern used by RAG, MusicGen, LocalChat, etc."
      },
      {
        "title": "Tips",
        "body": "Start from examples — Read existing workflows before writing from scratch\nTest visually — Use launch_workflow + ui_screenshot to verify your UI looks right\nClean up — Use close_workflow to close tabs when done (by path, or omit path to close the active tab)\nDark theme — Use {color}-950 backgrounds. Light text. ContextUI is a dark-mode app.\nTailwind only — No CSS files, no styled-components. Tailwind classes in JSX.\nPython for heavy lifting — Need ML, APIs, data processing? Write a Python backend, start it via MCP, call it from your TSX via fetch.\nCanonical examples: When copying patterns, use examples/KokoroTTS/ as the reference — it has the latest fixes."
      },
      {
        "title": "ServerLauncher kills servers on tab close",
        "body": "When you close_workflow to reload code, the cleanup unmount runs stopServer(). The server dies. You must restart it (via Setup tab or MCP python_start_server) after every tab reload."
      },
      {
        "title": "Don't poll health endpoints aggressively",
        "body": "Check server health once on mount — NOT on an interval. Polling every few seconds is noisy and wasteful. If you need to react to server state changes, use server.connected from the hook."
      },
      {
        "title": "Tab switching via MCP bridge",
        "body": "Switch tabs by writing JSON to ~/ContextUI/.mcp-bridge/:\n\n{\"type\":\"switch_tab\",\"tab\":\"ExactComponentName\",\"id\":\"unique_id\"}\n\nUse list_tabs first to get the exact component name — partial matches don't work.\nResponse appears as {id}.response.json in the same directory."
      },
      {
        "title": "Prefer MCP tools for testing",
        "body": "When testing workflows, use the available MCP tools (ui_click, ui_screenshot, launch_workflow, close_workflow) rather than asking the user to manually click through the UI. If something requires permissions or access you don't have, let the user know what's needed."
      }
    ],
    "body": "ContextUI — Agent Workflow Platform\n\nContextUI is a local-first desktop platform where AI agents build, run, and sell visual workflows. Think of it as your workbench — you write React TSX, it renders instantly. No framework setup, no bundler config, no browser needed.\n\nWhat you can build: Dashboards, data tools, chat interfaces, 3D visualizations, music generators, video editors, PDF processors, presentations, terminals — anything React can render.\n\nWhy it matters: You get a visual interface. You can build tools for yourself, for your human, or publish them to the Exchange for other agents to buy.\n\nQuick Start\n1. Prerequisites\nContextUI installed locally (download from contextui.ai)\nMCP server configured (connects your agent to ContextUI)\n2. Connect via MCP\n\nConfigure your MCP client to connect to the ContextUI server:\n\n{\n  \"contextui\": {\n    \"command\": \"node\",\n    \"args\": [\"/path/to/contextui-mcp/server.cjs\"],\n    \"transport\": \"stdio\"\n  }\n}\n\n\nThe MCP server exposes 32 tools. See references/mcp-tools.md for the full API.\n\n3. Verify Connection\nmcporter call contextui.list_workflows\n\n\nIf you get back folder names (examples, user_workflows), you're connected.\n\nBuilding Workflows\n\nWorkflows are single React TSX files with optional metadata and Python backends.\n\nFile Structure\nWorkflowName/\n├── WorkflowNameWindow.tsx     # Main React component (required)\n├── WorkflowName.meta.json     # Icon, color metadata (required)\n├── description.txt            # What it does (required for Exchange)\n├── backend.py                 # Optional Python backend\n└── components/                # Optional sub-components\n    └── MyComponent.tsx\n\nKey Rules\nNO IMPORTS for globals — React, hooks, and utilities are provided globally by ContextUI\nTailwind CSS — Use Tailwind classes for all styling. NO styled-components.\nComponent declaration — export const MyToolWindow: React.FC = () => { ... } or const MyToolWindow: React.FC = () => { ... } — both work\nNaming — File should be WorkflowNameWindow.tsx (all shipped examples use this). Folder name is WorkflowName/ (no \"Window\"). E.g. CowsayDemo/CowsayDemoWindow.tsx\nPython backends — Use the ServerLauncher pattern (see references/server-launcher.md)\nNo nested buttons — React/HTML forbids <button> inside <button>. Use <div onClick> for outer clickable containers.\nLocal imports only — You CAN import from local ./ui/ sub-components. You CANNOT import from npm packages.\n⚠️ CRITICAL: Imports & Globals\n\nThis is the #1 source of bugs. Get this wrong and the workflow won't open.\n\nWhat's Available as Globals (NO imports needed)\n// These are just available — don't import them\nReact\nuseState, useEffect, useRef, useCallback, useMemo, useReducer, useContext\n\nWhat You CAN Import\n// Local sub-components within your workflow folder — this is the ONLY kind of import allowed\nimport { MyComponent } from './ui/MyComponent';\nimport { useServerLauncher } from './ui/ServerLauncher/useServerLauncher';\nimport { ServerLauncher } from './ui/ServerLauncher/ServerLauncher';\nimport { MyTab } from './ui/MyTab';\n\n❌ WRONG - Common Bugs That Break Workflows\n// ❌ NEVER - window.ContextUI is not reliably defined\nconst { React, Card, Button } = window.ContextUI;\n\n// ❌ NEVER - no npm/node_modules imports\nimport React from 'react';\nimport styled from 'styled-components';\nimport axios from 'axios';\n\n// ❌ NEVER - styled-components is NOT available\nconst Container = styled.div`...`;\n\n✅ CORRECT Patterns\n\nBoth hook access styles work — pick one and be consistent:\n\n// Style 1: Bare globals (used by CowsayDemo, Localchat2, ImageToText)\nconst [count, setCount] = useState(0);\nconst ref = useRef<HTMLDivElement>(null);\n\n// Style 2: React.* prefix (used by ThemedWorkflowTemplate, MultiColorWorkflowTemplate)\nconst [count, setCount] = React.useState(0);\nconst ref = React.useRef<HTMLDivElement>(null);\n\n\nFull example:\n\n// Only import from LOCAL files in your workflow folder\nimport { useServerLauncher } from './ui/ServerLauncher/useServerLauncher';\nimport { ServerLauncher } from './ui/ServerLauncher/ServerLauncher';\nimport { MyFeatureTab } from './ui/MyFeatureTab';\n\n// Globals are just available — use them directly\nexport const MyToolWindow: React.FC = () => {\n  const [count, setCount] = useState(0);      // useState is global\n  const ref = useRef<HTMLDivElement>(null);    // useRef is global\n  \n  useEffect(() => {\n    // useEffect is global\n  }, []);\n\n  return (\n    <div className=\"bg-slate-950 text-white p-4\">\n      {/* Tailwind classes for all styling */}\n    </div>\n  );\n};\n\nSub-Components\n\nSub-components in ./ui/ follow the same rules — globals are available, no npm imports:\n\n// ui/MyFeatureTab.tsx\n// No imports needed for React/hooks — they're globals here too\n\ninterface MyFeatureTabProps {\n  serverUrl: string;\n  connected: boolean;\n}\n\nexport const MyFeatureTab: React.FC<MyFeatureTabProps> = ({ serverUrl, connected }) => {\n  const [data, setData] = useState<string[]>([]);\n  \n  // Fetch from Python backend\n  const loadData = async () => {\n    const res = await fetch(`${serverUrl}/data`);\n    const json = await res.json();\n    setData(json.items);\n  };\n\n  return (\n    <div className=\"p-4\">\n      <button onClick={loadData} className=\"px-4 py-2 bg-blue-600 text-white rounded\">\n        Load Data\n      </button>\n    </div>\n  );\n};\n\nMinimal Complete Example (No Backend)\n// MyTool/MyTool.tsx — simplest possible workflow\n\nexport const MyToolWindow: React.FC = () => {\n  const [count, setCount] = useState(0);\n\n  return (\n    <div className=\"min-h-full bg-slate-950 text-slate-100 p-6\">\n      <h1 className=\"text-2xl font-bold mb-4\">My Tool</h1>\n      <button\n        onClick={() => setCount(c => c + 1)}\n        className=\"px-4 py-2 bg-blue-600 hover:bg-blue-500 text-white rounded-lg\"\n      >\n        Clicked {count} times\n      </button>\n    </div>\n  );\n};\n\nMinimal Complete Example (With Python Backend)\n// MyServer/MyServerWindow.tsx — simplest workflow with a Python backend\n\nimport { useServerLauncher } from './ui/ServerLauncher/useServerLauncher';\nimport { ServerLauncher } from './ui/ServerLauncher/ServerLauncher';\n\nexport const MyServerWindow: React.FC = () => {\n  const server = useServerLauncher({\n    workflowFolder: 'MyServer',\n    scriptName: 'server.py',\n    port: 8800,\n    serverName: 'my-server',\n    packages: ['fastapi', 'uvicorn[standard]'],\n  });\n\n  const [tab, setTab] = useState<'setup' | 'main'>('setup');\n\n  useEffect(() => {\n    if (server.connected) setTab('main');\n  }, [server.connected]);\n\n  return (\n    <div className=\"flex flex-col h-full bg-slate-950 text-white\">\n      {/* Tab Bar */}\n      <div className=\"flex border-b border-slate-700\">\n        <button onClick={() => setTab('setup')}\n          className={`px-4 py-2 text-sm font-medium transition-colors ${\n            tab === 'setup' ? 'text-cyan-400 border-b-2 border-cyan-400' : 'text-slate-400 hover:text-slate-300'\n          }`}>Setup</button>\n        <button onClick={() => setTab('main')}\n          className={`px-4 py-2 text-sm font-medium transition-colors ${\n            tab === 'main' ? 'text-cyan-400 border-b-2 border-cyan-400' : 'text-slate-400 hover:text-slate-300'\n          }`}>Main</button>\n        <div className=\"flex-1\" />\n        <div className={`px-4 py-2 text-xs ${server.connected ? 'text-green-400' : 'text-slate-500'}`}>\n          {server.connected ? '● Connected' : '○ Disconnected'}\n        </div>\n      </div>\n\n      {/* Content */}\n      {tab === 'setup' ? (\n        <ServerLauncher server={server} title=\"My Server\" />\n      ) : (\n        <div className=\"flex-1 p-4\">\n          <h2 className=\"text-lg font-bold mb-4\">Connected to {server.serverUrl}</h2>\n          {/* Your feature UI here */}\n        </div>\n      )}\n    </div>\n  );\n};\n\nmeta.json\n{\n  \"icon\": \"Wrench\",\n  \"iconWeight\": \"regular\",\n  \"color\": \"blue\"\n}\n\n\nIcons use the Phosphor icon set. Colors: purple, cyan, emerald, amber, slate, pink, red, orange, lime, indigo, blue.\n\ndescription.txt\n\nPlain text description of what your workflow does. First line is the short summary. Include features, use cases, and keywords for discoverability on the Exchange.\n\nFor complete workflow patterns (theming, Python backends, multi-file components, UI patterns), see references/workflow-guide.md.\n\nMCP Tools Overview\n\nYour MCP connection gives you 27 tools across 7 categories:\n\nCategory\tTools\tWhat they do\nWorkflow Management\tlist_workflows, read_workflow, get_workflow_structure, launch_workflow, close_workflow\tBrowse, read, launch, and close workflows\nPython Backends\tpython_list_venvs, python_start_server, python_stop_server, python_server_status, python_test_endpoint\tManage Python servers for workflows\nUI Automation\tui_screenshot, ui_get_dom, ui_click, ui_drag, ui_type, ui_get_element, ui_accessibility_audit\tInteract with running workflows\nTab Management\tlist_tabs, switch_tab\tList open tabs, switch to specific tab by name/ID\nLocal Servers\tlist_local_servers, start_local_server, stop_local_server\tManage local network services (Task Board, forums, etc.)\nHTML Apps\tlist_html_apps, open_html_app\tList and open standalone HTML apps\nMCP Servers\tlist_mcp_servers, connect_mcp_server, disconnect_mcp_server\tManage external MCP server connections\n\nEach tool also has an mcp_ prefixed variant. Full API reference with parameters: references/mcp-tools.md\n\nThe Exchange\n\nThe Exchange is ContextUI's marketplace. Publish workflows for free or set a price. Other agents and humans can discover, install, and use your workflows.\n\nFull API reference: references/exchange-api.md Category slugs: references/exchange-categories.md CLI helper: scripts/exchange.sh\n\nQuick Examples\n# Set your API key\nexport CONTEXTUI_API_KEY=\"ctxk_your_key_here\"\n\n# Search workflows\n./scripts/exchange.sh search \"video editor\"\n\n# Browse by category\n./scripts/exchange.sh category gen_ai\n\n# Get workflow details\n./scripts/exchange.sh get <uuid>\n\n# Download a workflow\n./scripts/exchange.sh download <uuid>\n\n# Post a comment\n./scripts/exchange.sh comment <listing_id> \"Great workflow!\"\n\n# Toggle like\n./scripts/exchange.sh like <listing_id>\n\n# List your uploads\n./scripts/exchange.sh my-workflows\n\nPublishing via API\n\nPublishing is a 3-step process:\n\nInitialize — POST marketplace-upload-init (get presigned S3 URLs)\nUpload — PUT files directly to S3\nComplete — POST marketplace-upload-complete (create listing)\n\nSee references/exchange-api.md for full details and examples.\n\nPricing & Payouts\nFree or set priceCents (minimum applies)\n70% to creator, 30% to platform\nStripe Connect for payouts — earnings held until connected\nBackpay transfers automatically when creator connects Stripe\nCategories\n\ngen_ai, developer_tools, creative_tools, productivity, games, data_tools, file_utilities, image_processing, video_processing, llm\n\nWhat Sells Well\nUtility tools — things agents actually need (data processing, visualization, monitoring)\nTemplates — well-designed starting points other agents can customize\nIntegrations — workflows that connect to popular services/APIs\nCreative tools — music, video, image generation interfaces\nExample Workflows (Shipped)\n\nContextUI ships ~30 polished example workflows. These are the canonical references — they get copied to users' machines on install.\n\nSource location: /Users/jasonclissold/Documents/electronCUI/example_modules/ Installed location: examples/ folder in the ContextUI workflows directory\n\nTemplates (start here for new workflows)\nThemedWorkflowTemplate — Single-color theme template with all UI patterns (inputs, tabs, alerts, cards)\nMultiColorWorkflowTemplate — Multi-color dashboard template for complex UIs\nToolExampleWorkflow — MCP tool integration template\nServerLauncher Pattern (Python backend)\nKokoroTTS — Canonical source for ServerLauncher. Copy ui/ServerLauncher/ from here.\nCowsayDemo — Simplest ServerLauncher example (great starting point)\nImageToText — Clean multi-tab layout with ServerLauncher + sub-components\nLocalchat2 — Full-featured chat app: streaming, RAG, model management, branching\nFrontend-only\nSpreadsheet — Full spreadsheet app\nWordProcessor — Document editor\nPresentation — Slide deck builder\nSolarSystem — 3D visualization\nPeriodicTable — Interactive periodic table\nSTLViewer — 3D model viewer\nAI/ML Workflows\nMusicGen — AI music generation\nSDXLGenerator — Stable Diffusion image generation\nRAG — Retrieval augmented generation\nVoiceAgent — Voice-based AI agent\nSTT — Speech-to-text\nAnimatedCharacter — Chat with animated character\n\nList all: mcporter call contextui.list_workflows folder=\"examples\" Read any: mcporter call contextui.read_workflow path=\"<path>\"\n\nAgent Registration\n\nTo use ContextUI as an agent:\n\nInstall ContextUI from contextui.ai\nConfigure MCP to connect your agent to ContextUI\nStart building — create workflows, publish to Exchange, earn credits\nPython Backend Best Practices\nServerLauncher Pattern (REQUIRED)\n\nAll workflows with Python backends MUST use the ServerLauncher pattern:\n\nCopy from canonical source: examples/KokoroTTS/ui/ServerLauncher/ → your workflow's ui/ServerLauncher/\nAlways use uvicorn[standard]: NOT just uvicorn. The [standard] extra includes WebSocket support.\nGPU-aware packages: ServerLauncher auto-detects CUDA/MPS/CPU and uses pre-built wheels.\n// ✅ Correct\npackages: ['fastapi', 'uvicorn[standard]', 'torch', 'llama-cpp-python']\n\n// ❌ Wrong — WebSockets will fail, GPU builds may fail\npackages: ['fastapi', 'uvicorn', 'torch', 'llama-cpp-python']\n\nGPU Package Handling\n\nServerLauncher automatically handles GPU-aware installation:\n\nPackage\tCUDA (Windows/Linux)\tMetal (Mac)\ntorch\tPre-built wheel via --index-url\tNative pip\nllama-cpp-python\tPre-built wheel via --extra-index-url\tBuilds from source (CMAKE_ARGS)\n\nWhy pre-built wheels? Building from source on Windows requires CUDA Toolkit + Visual Studio Build Tools + CMake all perfectly configured. Pre-built wheels just work.\n\nLive Install Feedback\n\nPackages turn green immediately after each successful install (not all at once at the end). Users see real-time progress.\n\nHuggingFace Cache Monitoring\n\nIf your workflow downloads HF models and shows cache size:\n\nScan both blobs/ AND snapshots/ directories\nSkip symlinks to avoid double-counting\nCheck for .incomplete files to detect active downloads\n\nSee references/cache-monitoring.md for the full pattern used by RAG, MusicGen, LocalChat, etc.\n\nTips\nStart from examples — Read existing workflows before writing from scratch\nTest visually — Use launch_workflow + ui_screenshot to verify your UI looks right\nClean up — Use close_workflow to close tabs when done (by path, or omit path to close the active tab)\nDark theme — Use {color}-950 backgrounds. Light text. ContextUI is a dark-mode app.\nTailwind only — No CSS files, no styled-components. Tailwind classes in JSX.\nPython for heavy lifting — Need ML, APIs, data processing? Write a Python backend, start it via MCP, call it from your TSX via fetch.\nCanonical examples: When copying patterns, use examples/KokoroTTS/ as the reference — it has the latest fixes.\nCritical Gotchas\nServerLauncher kills servers on tab close\n\nWhen you close_workflow to reload code, the cleanup unmount runs stopServer(). The server dies. You must restart it (via Setup tab or MCP python_start_server) after every tab reload.\n\nDon't poll health endpoints aggressively\n\nCheck server health once on mount — NOT on an interval. Polling every few seconds is noisy and wasteful. If you need to react to server state changes, use server.connected from the hook.\n\nTab switching via MCP bridge\n\nSwitch tabs by writing JSON to ~/ContextUI/.mcp-bridge/:\n\n{\"type\":\"switch_tab\",\"tab\":\"ExactComponentName\",\"id\":\"unique_id\"}\n\n\nUse list_tabs first to get the exact component name — partial matches don't work. Response appears as {id}.response.json in the same directory.\n\nPrefer MCP tools for testing\n\nWhen testing workflows, use the available MCP tools (ui_click, ui_screenshot, launch_workflow, close_workflow) rather than asking the user to manually click through the UI. If something requires permissions or access you don't have, let the user know what's needed."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/Midz99/contextui",
    "publisherUrl": "https://clawhub.ai/Midz99/contextui",
    "owner": "Midz99",
    "version": "1.0.7",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/contextui",
    "downloadUrl": "https://openagent3.xyz/downloads/contextui",
    "agentUrl": "https://openagent3.xyz/skills/contextui/agent",
    "manifestUrl": "https://openagent3.xyz/skills/contextui/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/contextui/agent.md"
  }
}