tui-canvas

TUI Canvas

Framework-agnostic interactive terminal canvases for AI coding assistants.

Works with OpenCode, Claude Code, Cursor, Gemini CLI, Grok CLI, and any MCP-compatible AI harness.

Supports multiple TUI frameworks: OpenTUI (primary), Ink, and more.

Features

• Protocol-first design - Any TUI framework can implement canvases
• Multiple implementations - Same canvas in OpenTUI, Ink, Bubbletea, etc.
• MCP integration - Works with any AI coding assistant via MCP
• tmux integration - Canvases spawn in split panes

Built-in Canvases

• Calendar - Weekly view with events, meeting time picker
• Document - Markdown viewer/editor with text selection
• Flight - Cyberpunk-themed flight booking with seatmaps

Quick Start

Install

# Run without installing globally
bunx tui-canvas list

MCP Configuration

OpenCode (opencode.json in this repo):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tui-canvas": {
      "type": "local",
      "command": ["bun", "run", "packages/mcp/src/index.ts"],
      "enabled": true
    }
  }
}

Other MCP clients:

{
  "mcpServers": {
    "tui-canvas": {
      "command": "bunx",
      "args": ["tui-canvas"]
    }
  }
}

CLI Usage

# List available canvases
bunx tui-canvas list

# Spawn a canvas (must be in tmux)
bunx tui-canvas spawn calendar --scenario display
bunx tui-canvas spawn document --scenario edit --config '{"content": "# Hello"}'

# Use specific implementation
bunx tui-canvas spawn calendar --implementation ink
bunx tui-canvas spawn calendar --implementation opentui

Project Structure

tui-canvas/
├── packages/
│   ├── protocol/         # Protocol specification & types
│   ├── cli/              # Unified CLI
│   ├── mcp/              # MCP server
│   └── runtime/          # Framework adapters
│       ├── opentui/      # OpenTUI runtime (primary)
│       └── ink/          # Ink runtime
│
├── canvases/             # Canvas implementations
│   ├── calendar/
│   │   ├── manifest.json # Canvas manifest
│   │   ├── opentui/      # OpenTUI implementation
│   │   └── ink/          # Ink implementation
│   ├── document/
│   └── flight/

Supported Frameworks

| Framework | Status | Description | |-----------|--------|-------------| | OpenTUI | Primary | TypeScript TUI framework (anomalyco/opentui) | | Ink | Secondary | React for terminals | | Bubbletea | Planned | Go TUI framework | | Textual | Planned | Python TUI framework |

Supported AI Harnesses

| Harness | Detection | |---------|-----------| | OpenCode | OPENCODE env | | Claude Code | CLAUDE_CODE env | | Cursor | CURSOR_SESSION env | | Gemini CLI | GEMINI_CLI / GEMINI_API_KEY env | | Grok CLI | GROK_CLI / XAI_API_KEY env | | Generic | Fallback for any MCP client |

Creating Canvases

Canvas Manifest

Each canvas has a manifest.json:

{
  "id": "my-canvas",
  "name": "My Canvas",
  "description": "A custom canvas",
  "version": "1.0.0",
  
  "scenarios": {
    "default": {
      "description": "Default scenario",
      "configSchema": { ... },
      "resultSchema": { ... }
    }
  },
  
  "implementations": {
    "opentui": {
      "framework": "opentui",
      "reconciler": "solid",
      "entrypoint": "./opentui/index.ts"
    },
    "ink": {
      "framework": "ink",
      "entrypoint": "./ink/index.tsx"
    }
  },
  
  "defaultImplementation": "opentui"
}

Protocol

Canvases communicate via Unix sockets using the TUI Canvas Protocol:

Canvas → Controller: ``typescript { type: "ready", scenario: string } { type: "selected", data: unknown } { type: "cancelled", reason?: string } ``

Controller → Canvas: ``typescript { type: "update", config: unknown } { type: "close" } ``

Development

# Clone and install
git clone https://github.com/anomalyco/tui-canvas.git
cd tui-canvas
bun install

# Test CLI
bun run packages/cli/src/index.ts list
bun run packages/cli/src/index.ts spawn calendar

# Start MCP server
bun run packages/mcp/src/index.ts

Requirements

• Bun runtime
• tmux for pane spawning
• Terminal with mouse support (recommended)

License

MIT

Credits

Originally based on Claude Canvas. OpenTUI framework: github.com/anomalyco/opentui