clauderun

A premium chat-style web UI for Claude Code — built on the official @anthropic-ai/claude-code SDK.

Drop into any folder, run one command, and get a beautiful conversational interface with conversation history, drag-and-drop attachments, inline diffs, a Cmd+K palette, and MCP/tools/commands inspector.

npx clauderun ui

That's it. A browser tab opens pointed at the current directory. Start chatting.

Why clauderun?

Claude Code ships a terminal experience that power users love, but sometimes you want:

• A real chat UI to share with teammates who aren't TUI-native
• A conversation history you can browse and resume
• Drag-and-drop for screenshots, logs, and source files
• Inline diffs for every Edit and Write
• A Cmd+K palette to jump between sessions, folders, and slash commands
• A sidebar inspector showing live MCP server status, available tools, slash commands, and models

clauderun delivers all of that on top of the same SDK the CLI uses — same permission model, same tools, same everything.

Features

Conversational UI

• Streaming assistant responses (text deltas rendered as they arrive)
• Markdown + syntax-highlighted code blocks
• Stop / cancel at any time with the Cancel button or Esc
• Per-turn cost and duration summary

Conversation history

• Every session is persisted to ~/.clauderun/sessions.json
• Resume any past conversation in one click (title, folder, message count, cost, last active)
• Delete individual sessions

Drag-and-drop attachments

• Drop images anywhere on the window — sent as image blocks
• Drop text/code files — inlined as text blocks with filename headers
• Paste screenshots directly from the clipboard
• Multi-file support with preview chips

Inline diff viewer

• Every Edit tool use shows a unified diff with red/green lines
• MultiEdit shows numbered edit blocks
• Write shows the full new file as added lines
• Auto-expanded so you see changes without extra clicks

Cmd+K command palette

• ⌘K / Ctrl+K from anywhere
• Fuzzy search across slash commands, recent sessions, and recent folders
• ↑↓ to navigate, ↵ to select, Esc to close

Side inspector panel

• MCP server status with live indicators
• Built-in tools vs. MCP tools, grouped
• Slash commands with descriptions
• Available models

Permission modes

Matches the SDK exactly:

| Mode | Behavior | | ------------------- | -------------------------------------------------------- | | default | Ask before every file edit or command (safest) | | acceptEdits | Auto-accept file edits, still ask for commands | | bypassPermissions | Full autopilot — no prompts (use with care) | | plan | Claude thinks out loud without making any changes |

Switchable from the header dropdown or via AskUserQuestion during a chat.

Folder picker

• Browse, create, and switch working folders without restarting
• Recent folders menu
• Full onboarding flow for first-time users

Installation

Quick start (no install)

npx clauderun ui

Global install

npm install -g clauderun
clauderun ui

From a specific directory

clauderun ui --cwd ~/Projects/my-app

Custom port

clauderun ui --port 4000

Requirements

• Node.js 18+
• An Anthropic API key set as ANTHROPIC_API_KEY (or a signed-in Claude subscription via the SDK's auth flow)

export ANTHROPIC_API_KEY=sk-ant-...

Architecture

┌──────────────┐   WebSocket   ┌─────────────────┐   SDK query()   ┌────────┐
│   Browser    │◄─────────────►│   Node server   │◄───────────────►│ Claude │
│  (vanilla    │   /api/...    │  Express + ws   │   streaming     │  Code  │
│   HTML/JS)   │               │                 │   input mode    │        │
└──────────────┘               └─────────────────┘                 └────────┘

• Backend — Express + ws WebSocket bridge to the @anthropic-ai/claude-code SDK. Uses streaming input mode so one long-lived query() handles the whole multi-turn conversation.
• Frontend — Vanilla HTML + ES modules + CSS. No build step. Just open in any browser.
• Persistence — Session metadata in ~/.clauderun/sessions.json.
• Auth — Inherited from however Claude Code is configured on the machine.

Keyboard shortcuts

| Shortcut | Action | | ---------------- | ----------------------------------------- | | Enter | Send message | | Shift+Enter | New line | | Esc | Cancel / stop the assistant | | ⌘K / Ctrl+K | Open command palette | | ⌘V / Ctrl+V | Paste image or text from clipboard |

Development

git clone https://github.com/josharsh/clauderun.git
cd clauderun
npm install
npm start

The project has no build step. Edit files in public/ and refresh.

Project layout

bin/clauderun.js            CLI entry (commander)
src/
  server.js                 Express + WebSocket server
  claude-bridge.js          SDK integration (streaming input mode)
  session-manager.js        Per-connection state
  session-store.js          Persistent history (~/.clauderun)
  message-transformer.js    SDK messages → display format
  port-finder.js            Locate a free port
public/
  index.html                Single-page app shell
  css/styles.css            All styling (no build)
  js/
    app.js                  Wiring + event loop
    websocket-client.js     WS transport layer
    message-renderer.js     Chat bubble rendering
    tool-display.js         Tool use & diff viewer
    approval-dialog.js      Permission approvals + AskUserQuestion
    attachments.js          Drag / drop / paste files
    sessions-panel.js       History dropdown
    command-palette.js      Cmd+K launcher
    side-panel.js           MCP/tools/commands inspector
    folder-picker.js        Working directory UI
    mode-selector.js        Permission mode UI
    onboarding.js           First-run experience

Roadmap

• Export conversation as Markdown / JSON
• File tree sidebar with live watchers
• Multi-pane layout (code preview + chat)
• Theme switcher (light/dark/auto)
• Workspace settings persistence

PRs welcome!

License

MIT © Harsh Joshi

Not affiliated with Anthropic. Built on top of the official @anthropic-ai/claude-code SDK.