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:

{
  "contextui": {
    "command": "node",
    "args": ["/path/to/contextui-mcp/server.cjs"],
    "transport": "stdio"
  }
}

The MCP server exposes 32 tools. See references/mcp-tools.md for the full API.

3. Verify Connection

mcporter call contextui.list_workflows

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

WorkflowName/
├── WorkflowNameWindow.tsx     # Main React component (required)
├── WorkflowName.meta.json     # Icon, color metadata (required)
├── description.txt            # What it does (required for Exchange)
├── backend.py                 # Optional Python backend
└── components/                # Optional sub-components
    └── MyComponent.tsx

Key Rules

1. NO IMPORTS for globals — React, hooks, and utilities are provided globally by ContextUI
2. Tailwind CSS — Use Tailwind classes for all styling. NO styled-components.
3. Component declaration — export const MyToolWindow: React.FC = () => { ... } or const MyToolWindow: React.FC = () => { ... } — both work
4. Naming — File should be WorkflowNameWindow.tsx (all shipped examples use this). Folder name is WorkflowName/ (no "Window"). E.g. CowsayDemo/CowsayDemoWindow.tsx
5. Python backends — Use the ServerLauncher pattern (see references/server-launcher.md)
6. No nested buttons — React/HTML forbids <button> inside <button>. Use <div onClick> for outer clickable containers.
7. 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)

// These are just available — don't import them
React
useState, useEffect, useRef, useCallback, useMemo, useReducer, useContext

What You CAN Import