ContextUI — Agent Workflow Platform
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.
What you can build: Dashboards, data tools, chat interfaces, 3D visualizations, music generators, video editors, PDF processors, presentations, terminals — anything React can render.
Why 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.
Quick Start
1. Prerequisites
- - ContextUI installed locally (download from contextui.ai)
- MCP server configured (connects your agent to ContextUI)
2. Connect via MCP
Configure your MCP client to connect to the ContextUI server:
CODEBLOCK0
The MCP server exposes 32 tools. See references/mcp-tools.md for the full API.
3. Verify Connection
CODEBLOCK1
If you get back folder names (examples, user_workflows), you're connected.
Building Workflows
Workflows are single React TSX files with optional metadata and Python backends.
File Structure
CODEBLOCK2
Key Rules
- 1. NO IMPORTS for globals — React, hooks, and utilities are provided globally by ContextUI
- Tailwind CSS — Use Tailwind classes for all styling. NO styled-components.
- Component declaration —
export const MyToolWindow: React.FC = () => { ... } or const MyToolWindow: React.FC = () => { ... } — both work - Naming — File should be
WorkflowNameWindow.tsx (all shipped examples use this). Folder name is WorkflowName/ (no "Window"). E.g. INLINECODE7 - Python backends — Use the ServerLauncher pattern (see
references/server-launcher.md) - No nested buttons — React/HTML forbids
<button> inside <button>. Use <div onClick> for outer clickable containers. - Local imports only — You CAN import from local
./ui/ sub-components. You CANNOT import from npm packages.
⚠️ CRITICAL: Imports & Globals
This is the #1 source of bugs. Get this wrong and the workflow won't open.
What's Available as Globals (NO imports needed)
CODEBLOCK3
What You CAN Import
CODEBLOCK4
❌ WRONG - Common Bugs That Break Workflows
CODEBLOCK5
✅ CORRECT Patterns
Both hook access styles work — pick one and be consistent:
CODEBLOCK6
Full example:
CODEBLOCK7
Sub-Components
Sub-components in ./ui/ follow the same rules — globals are available, no npm imports:
CODEBLOCK8
Minimal Complete Example (No Backend)
CODEBLOCK9
Minimal Complete Example (With Python Backend)
CODEBLOCK10
meta.json
CODEBLOCK11
Icons use the Phosphor icon set. Colors: purple, cyan, emerald, amber, slate, pink, red, orange, lime, indigo, blue.
description.txt
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.
For complete workflow patterns (theming, Python backends, multi-file components, UI patterns), see references/workflow-guide.md.
MCP Tools Overview
Your MCP connection gives you 27 tools across 7 categories:
| Category | Tools | What they do |
|---|
| Workflow Management | INLINECODE26 , read_workflow, get_workflow_structure, launch_workflow, INLINECODE30 | Browse, read, launch, and close workflows |
| Python Backends |
python_list_venvs,
python_start_server,
python_stop_server,
python_server_status,
python_test_endpoint | Manage Python servers for workflows |
|
UI Automation |
ui_screenshot,
ui_get_dom,
ui_click,
ui_drag,
ui_type,
ui_get_element,
ui_accessibility_audit | Interact with running workflows |
|
Tab Management |
list_tabs,
switch_tab | List open tabs, switch to specific tab by name/ID |
|
Local Servers |
list_local_servers,
start_local_server,
stop_local_server | Manage local network services (Task Board, forums, etc.) |
|
HTML Apps |
list_html_apps,
open_html_app | List and open standalone HTML apps |
|
MCP Servers |
list_mcp_servers,
connect_mcp_server,
disconnect_mcp_server | Manage external MCP server connections |
Each tool also has an mcp_ prefixed variant. Full API reference with parameters: INLINECODE54
The Exchange
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.
Full API reference: references/exchange-api.md
Category slugs: references/exchange-categories.md
CLI helper: INLINECODE57
Quick Examples
CODEBLOCK12
Publishing via API
Publishing is a 3-step process:
- 1. Initialize —
POST marketplace-upload-init (get presigned S3 URLs) - Upload — PUT files directly to S3
- Complete —
POST marketplace-upload-complete (create listing)
See references/exchange-api.md for full details and examples.
Pricing & Payouts
- - Free or set
priceCents (minimum applies) - 70% to creator, 30% to platform
- Stripe Connect for payouts — earnings held until connected
- Backpay transfers automatically when creator connects Stripe
Categories
INLINECODE62 , developer_tools, creative_tools, productivity, games, data_tools, file_utilities, image_processing, video_processing, INLINECODE71
What Sells Well
- - Utility tools — things agents actually need (data processing, visualization, monitoring)
- Templates — well-designed starting points other agents can customize
- Integrations — workflows that connect to popular services/APIs
- Creative tools — music, video, image generation interfaces
Example Workflows (Shipped)
ContextUI ships ~30 polished example workflows. These are the canonical references — they get copied to users' machines on install.
Source location: /Users/jasonclissold/Documents/electronCUI/example_modules/
Installed location: examples/ folder in the ContextUI workflows directory
Templates (start here for new workflows)
- -
ThemedWorkflowTemplate — Single-color theme template with all UI patterns (inputs, tabs, alerts, cards) - INLINECODE75 — Multi-color dashboard template for complex UIs
- INLINECODE76 — MCP tool integration template
ServerLauncher Pattern (Python backend)
- -
KokoroTTS — Canonical source for ServerLauncher. Copy ui/ServerLauncher/ from here. - INLINECODE79 — Simplest ServerLauncher example (great starting point)
- INLINECODE80 — Clean multi-tab layout with ServerLauncher + sub-components
- INLINECODE81 — Full-featured chat app: streaming, RAG, model management, branching
Frontend-only
- -
Spreadsheet — Full spreadsheet app - INLINECODE83 — Document editor
- INLINECODE84 — Slide deck builder
- INLINECODE85 — 3D visualization
- INLINECODE86 — Interactive periodic table
- INLINECODE87 — 3D model viewer
AI/ML Workflows
- -
MusicGen — AI music generation - INLINECODE89 — Stable Diffusion image generation
- INLINECODE90 — Retrieval augmented generation
- INLINECODE91 — Voice-based AI agent
- INLINECODE92 — Speech-to-text
- INLINECODE93 — Chat with animated character
List all: mcporter call contextui.list_workflows folder="examples"
Read any: INLINECODE95
Agent Registration
To use ContextUI as an agent:
- 1. Install ContextUI from contextui.ai
- Configure MCP to connect your agent to ContextUI
- Start building — create workflows, publish to Exchange, earn credits
Python Backend Best Practices
ServerLauncher Pattern (REQUIRED)
All workflows with Python backends MUST use the ServerLauncher pattern:
- 1. Copy from canonical source:
examples/KokoroTTS/ui/ServerLauncher/ → your workflow's INLINECODE97 - Always use
uvicorn[standard]: NOT just uvicorn. The [standard] extra includes WebSocket support. - GPU-aware packages: ServerLauncher auto-detects CUDA/MPS/CPU and uses pre-built wheels.
CODEBLOCK13
GPU Package Handling
ServerLauncher automatically handles GPU-aware installation:
| Package | CUDA (Windows/Linux) | Metal (Mac) |
|---|
| INLINECODE101 | Pre-built wheel via INLINECODE102 | Native pip |
| INLINECODE103 |
Pre-built wheel via
--extra-index-url | Builds from source (CMAKE_ARGS) |
Why pre-built wheels? Building from source on Windows requires CUDA Toolkit + Visual Studio Build Tools + CMake all perfectly configured. Pre-built wheels just work.
Live Install Feedback
Packages turn green immediately after each successful install (not all at once at the end). Users see real-time progress.
HuggingFace Cache Monitoring
If your workflow downloads HF models and shows cache size:
- - Scan both
blobs/ AND snapshots/ directories - Skip symlinks to avoid double-counting
- Check for
.incomplete files to detect active downloads
See references/cache-monitoring.md for the full pattern used by RAG, MusicGen, LocalChat, etc.
Tips
- - Start from examples — Read existing workflows before writing from scratch
- Test visually — Use
launch_workflow + ui_screenshot to verify your UI looks right - Clean up — Use
close_workflow to close tabs when done (by path, or omit path to close the active tab) - Dark theme — Use
{color}-950 backgrounds. Light text. ContextUI is a dark-mode app. - Tailwind only — No CSS files, no styled-components. Tailwind classes in JSX.
- Python for heavy lifting — Need ML, APIs, data processing? Write a Python backend, start it via MCP, call it from your TSX via fetch.
- Canonical examples: When copying patterns, use
examples/KokoroTTS/ as the reference — it has the latest fixes.
Critical Gotchas
ServerLauncher kills servers on tab close
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.
Don't poll health endpoints aggressively
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.
Tab switching via MCP bridge
Switch tabs by writing JSON to
~/ContextUI/.mcp-bridge/:
{"type":"switch_tab","tab":"ExactComponentName","id":"unique_id"}
Use
list_tabs first to get the exact component name — partial matches don't work.
Response appears as
{id}.response.json in the same directory.
Prefer MCP tools for testing
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.