clawport-ui 0.5.2 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +124 -206
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,84 +1,114 @@
1
+ <div align="center">
2
+
1
3
  # ClawPort
2
4
 
3
- A visual command centre for your AI agent team.
5
+ **A visual command centre for your AI agent team.**
6
+
7
+ [![npm version](https://img.shields.io/npm/v/clawport-ui.svg)](https://www.npmjs.com/package/clawport-ui)
8
+ [![license](https://img.shields.io/npm/l/clawport-ui.svg)](LICENSE)
9
+ [![tests](https://img.shields.io/badge/tests-442%20passed-brightgreen)](#testing)
10
+
11
+ [Website](https://clawport.dev) | [Setup Guide](SETUP.md) | [API Docs](docs/API.md) | [npm](https://www.npmjs.com/package/clawport-ui)
4
12
 
5
- ClawPort is an open-source dashboard for managing, monitoring, and talking directly to your [OpenClaw](https://openclaw.ai) AI agents. Built with Next.js 16, React 19, and a dark command-centre aesthetic with five themes.
13
+ </div>
6
14
 
7
15
  ---
8
16
 
9
- ## Getting Started
17
+ ClawPort is an open-source dashboard for managing, monitoring, and talking directly to your [OpenClaw](https://openclaw.ai) AI agents. It connects to your local OpenClaw gateway and gives you an org chart, direct agent chat with vision and voice, a kanban board, cron monitoring, and a memory browser -- all in one place.
10
18
 
11
- ### Prerequisites
19
+ No separate AI API keys needed. Everything routes through your OpenClaw gateway.
20
+
21
+ ---
12
22
 
13
- - [Node.js 22+](https://nodejs.org) (LTS recommended)
14
- - [OpenClaw](https://openclaw.ai) installed and running
15
- - OpenClaw gateway started (`openclaw gateway run`)
23
+ ## Quick Start
16
24
 
17
- ### Quick Start (npm)
25
+ ### 1. Install OpenClaw
26
+
27
+ ClawPort requires a running [OpenClaw](https://openclaw.ai) instance. If you don't have one yet:
28
+
29
+ ```bash
30
+ # Install OpenClaw
31
+ curl -fsSL https://openclaw.ai/install.sh | bash
32
+
33
+ # Run the onboarding wizard (sets up workspace, gateway, and daemon)
34
+ openclaw onboard --install-daemon
35
+ ```
36
+
37
+ After onboarding, verify the gateway is running:
38
+
39
+ ```bash
40
+ openclaw gateway status
41
+ ```
42
+
43
+ You should see your gateway URL (`localhost:18789`) and auth token. See the [OpenClaw docs](https://docs.openclaw.ai/getting-started) for more detail.
44
+
45
+ ### 2. Install ClawPort
18
46
 
19
47
  > **Note:** The npm package is `clawport-ui`. The CLI command is `clawport`.
20
48
  > Do not install the unrelated `clawport` package.
21
49
 
22
50
  ```bash
23
- # Install globally (package: clawport-ui, command: clawport)
24
51
  npm install -g clawport-ui
52
+ ```
25
53
 
26
- # Auto-detect your OpenClaw config
54
+ ### 3. Connect and Launch
55
+
56
+ ```bash
57
+ # Auto-detect your OpenClaw config and write .env.local
27
58
  clawport setup
28
59
 
29
- # Start the dev server
60
+ # Start the dashboard
30
61
  clawport dev
31
62
  ```
32
63
 
33
- ### Quick Start (from source)
64
+ Open [http://localhost:3000](http://localhost:3000). The onboarding wizard walks you through naming your portal, picking a theme, and setting up your operator identity.
65
+
66
+ <details>
67
+ <summary><strong>Install from source instead</strong></summary>
34
68
 
35
69
  ```bash
36
70
  git clone https://github.com/JohnRiceML/clawport-ui.git
37
71
  cd clawport-ui
38
72
  npm install
39
-
40
- # Auto-detect your OpenClaw config and write .env.local
41
73
  npm run setup
42
-
43
- # Start the dev server
44
74
  npm run dev
45
75
  ```
46
76
 
47
- Open [http://localhost:3000](http://localhost:3000). On first launch you'll see the **onboarding wizard**, which walks you through naming your portal, choosing a theme, and personalizing agent avatars.
48
-
49
- See [SETUP.md](SETUP.md) for detailed environment configuration and troubleshooting.
77
+ </details>
50
78
 
51
79
  ---
52
80
 
53
81
  ## Features
54
82
 
55
- ### Org Map
56
- Interactive org chart of your entire agent team. Nodes show hierarchy, cron status, voice capabilities, and relationships at a glance. Powered by React Flow with BFS-based auto-layout.
83
+ - **Org Map** -- Interactive org chart of your entire agent team. Hierarchy, cron status, and relationships at a glance. Powered by React Flow with auto-layout.
84
+ - **Chat** -- Streaming text chat, image attachments with vision, voice messages with waveform playback, file attachments, clipboard paste and drag-and-drop. Conversations persist locally.
85
+ - **Kanban** -- Task board for managing work across agents. Drag-and-drop cards with agent assignment and chat context.
86
+ - **Cron Monitor** -- Live status of all scheduled jobs. Filter by status, sort errors to top, expand for details. Auto-refreshes every 60 seconds.
87
+ - **Memory Browser** -- Read team memory, long-term memory, and daily logs. Markdown rendering, JSON syntax highlighting, search, and download.
88
+ - **Agent Detail** -- Full profile per agent: SOUL.md viewer, tools, hierarchy, crons, voice ID, and direct chat link.
89
+ - **Five Themes** -- Dark, Glass, Color, Light, and System. All CSS custom properties -- switch instantly.
90
+ - **Auto-Discovery** -- Automatically finds agents from your OpenClaw workspace. No config file needed.
57
91
 
58
- ### Chat (Call Box)
59
- Full-featured messenger for direct agent conversations:
60
- - **Streaming text chat** via Claude (through the OpenClaw gateway)
61
- - **Image attachments** with vision -- agents can see and describe images
62
- - **Voice messages** -- hold-to-record with waveform playback
63
- - **File attachments** -- PDFs, docs, text files with type-aware rendering
64
- - **Clipboard paste and drag-and-drop** for images
65
- - **Clear chat** per agent
66
- - Conversations persist to localStorage
67
-
68
- ### Agent Detail
69
- Full profile: SOUL.md viewer, tool list, hierarchy, associated crons, voice ID, and direct chat link.
92
+ ---
70
93
 
71
- ### Kanban
72
- Task board for managing work across your agent team. Drag-and-drop cards with agent assignment and chat context.
94
+ ## How It Works
73
95
 
74
- ### Cron Monitor
75
- Live status of all scheduled jobs. Filter by status (all/ok/error/idle), sort errors to top, expand for error details. Auto-refreshes every 60 seconds.
96
+ ClawPort reads your OpenClaw workspace to discover agents, then connects to the gateway for all AI operations:
76
97
 
77
- ### Memory Browser
78
- Read team memory, long-term memory, and daily logs. Markdown rendering and JSON syntax highlighting built-in. Search, copy, and download support.
98
+ ```
99
+ Browser --> ClawPort (Next.js) --> OpenClaw Gateway (localhost:18789) --> Claude
100
+ | |
101
+ | Text: /v1/chat/completions (streaming SSE)
102
+ | Vision: openclaw gateway call chat.send (CLI)
103
+ | Audio: /v1/audio/transcriptions (Whisper)
104
+ |
105
+ Reads from:
106
+ $WORKSPACE_PATH/agents/ (agent SOUL.md files)
107
+ $WORKSPACE_PATH/memory/ (team memory)
108
+ openclaw cron list (scheduled jobs)
109
+ ```
79
110
 
80
- ### Settings
81
- Personalize your portal: custom name, subtitle, logo/emoji, accent color, agent avatar overrides, and theme selection. All settings persist in your browser.
111
+ All AI calls -- chat, vision, TTS, transcription -- route through the gateway. One token, no separate API keys.
82
112
 
83
113
  ---
84
114
 
@@ -86,211 +116,99 @@ Personalize your portal: custom name, subtitle, logo/emoji, accent color, agent
86
116
 
87
117
  ### Required Environment Variables
88
118
 
89
- | Variable | Description |
90
- |----------|-------------|
91
- | `WORKSPACE_PATH` | Path to your OpenClaw workspace directory (default: `~/.openclaw/workspace`) |
92
- | `OPENCLAW_BIN` | Path to the `openclaw` CLI binary |
93
- | `OPENCLAW_GATEWAY_TOKEN` | Token that authenticates all API calls to the gateway |
119
+ | Variable | Description | How to find it |
120
+ |----------|-------------|----------------|
121
+ | `WORKSPACE_PATH` | Path to your OpenClaw workspace | Default: `~/.openclaw/workspace` |
122
+ | `OPENCLAW_BIN` | Path to the `openclaw` binary | Run `which openclaw` |
123
+ | `OPENCLAW_GATEWAY_TOKEN` | Gateway auth token | Run `openclaw gateway status` |
94
124
 
95
- ### Optional Environment Variables
125
+ ### Optional
96
126
 
97
127
  | Variable | Description |
98
128
  |----------|-------------|
99
- | `ELEVENLABS_API_KEY` | ElevenLabs API key for voice/TTS indicators on agent profiles |
129
+ | `ELEVENLABS_API_KEY` | ElevenLabs API key for voice indicators on agent profiles |
100
130
 
101
- No separate AI API keys are needed. All AI calls (chat, vision, TTS, transcription) route through the OpenClaw gateway.
102
-
103
- See [SETUP.md](SETUP.md) for how to find each value.
131
+ Running `clawport setup` auto-detects all required values and writes `.env.local`. See [SETUP.md](SETUP.md) for manual configuration, agent customization, and troubleshooting.
104
132
 
105
133
  ---
106
134
 
107
- ## Agent Customization
135
+ ## Agent Discovery
108
136
 
109
- ClawPort ships with a bundled agent registry (`lib/agents.json`) as a working example. To use your own agents, create a file at:
137
+ ClawPort automatically discovers agents from your OpenClaw workspace. No configuration file needed.
110
138
 
111
- ```
112
- $WORKSPACE_PATH/clawport/agents.json
113
- ```
139
+ **What it scans:**
140
+ - `$WORKSPACE_PATH/SOUL.md` -- root orchestrator
141
+ - `$WORKSPACE_PATH/IDENTITY.md` -- root agent name and emoji
142
+ - `agents/<name>/SOUL.md` -- top-level agents
143
+ - `agents/<name>/sub-agents/*.md` -- flat sub-agent files
144
+ - `agents/<name>/members/*.md` -- team member files
145
+ - `agents/<name>/<subdir>/SOUL.md` -- nested subdirectory agents
114
146
 
115
- ClawPort checks for this file on every request. If it exists, it takes priority over the bundled registry. If it's missing or malformed, the bundled default is used as a fallback.
116
-
117
- Each agent entry looks like this:
118
-
119
- ```json
120
- {
121
- "id": "my-agent",
122
- "name": "My Agent",
123
- "title": "What they do",
124
- "reportsTo": "parent-agent-id",
125
- "directReports": [],
126
- "soulPath": "agents/my-agent/SOUL.md",
127
- "voiceId": null,
128
- "color": "#06b6d4",
129
- "emoji": "🤖",
130
- "tools": ["read", "write"],
131
- "memoryPath": null,
132
- "description": "One-liner description of this agent."
133
- }
134
- ```
147
+ **What it ignores:**
148
+ - Directories without `SOUL.md` (e.g., `briefs/`, data files)
149
+ - Non-`.md` files in `sub-agents/` and `members/`
135
150
 
136
- See [SETUP.md](SETUP.md) for the full field reference and examples.
151
+ For full control over names, colors, hierarchy, and tools, create `$WORKSPACE_PATH/clawport/agents.json`. See [SETUP.md](SETUP.md) for the schema and examples.
137
152
 
138
153
  ---
139
154
 
140
- ## Architecture
141
-
142
- ### How Chat Works
143
-
144
- Text messages go through the OpenClaw gateway's OpenAI-compatible endpoint (`/v1/chat/completions`) for streaming responses.
145
-
146
- Image messages use a different pipeline because the gateway's HTTP endpoint strips image data. Instead, ClawPort uses the same path as Discord/Telegram channels:
147
-
148
- ```
149
- User attaches image
150
- → Client resizes to 1200px max (fits within OS arg limits)
151
- → Client converts to base64 data URL
152
- → POST /api/chat/[id] detects image in latest message
153
- → Server calls `openclaw gateway call chat.send` via CLI
154
- → Server polls `openclaw gateway call chat.history` every 2s
155
- → Agent processes image + text through Anthropic vision API
156
- → Response returned to client as SSE
157
- ```
158
-
159
- Voice messages are recorded in-browser using the MediaRecorder API, transcribed server-side via Whisper (through the gateway's `/v1/audio/transcriptions` endpoint), and sent as text with the audio waveform preserved for playback.
155
+ ## CLI
160
156
 
161
- ### Directory Structure
162
-
163
- ```
164
- app/
165
- page.tsx — Org Map (React Flow org chart)
166
- chat/page.tsx — Multi-agent messenger
167
- agents/[id]/page.tsx — Agent detail profile
168
- kanban/page.tsx — Task board
169
- crons/page.tsx — Cron job monitor
170
- memory/page.tsx — Memory file browser
171
- settings/page.tsx — ClawPort personalization
172
- api/
173
- agents/route.ts — GET agents from registry
174
- chat/[id]/route.ts — POST chat (text + vision)
175
- crons/route.ts — GET crons via CLI
176
- memory/route.ts — GET memory files
177
- tts/route.ts — POST text-to-speech
178
- transcribe/route.ts — POST audio transcription
179
-
180
- components/
181
- OrgMap.tsx — React Flow graph with auto-layout
182
- AgentNode.tsx — Custom node for the org chart
183
- Sidebar.tsx — Desktop navigation sidebar
184
- MobileSidebar.tsx — Mobile hamburger menu
185
- ThemeToggle.tsx — Theme switcher (5 themes)
186
- GlobalSearch.tsx — Cmd+K agent search
187
- chat/
188
- ConversationView.tsx — Message history + input with media
189
- AgentList.tsx — Agent sidebar for chat
190
- VoiceMessage.tsx — Waveform playback component
191
- FileAttachment.tsx — File bubble with icon + download
192
- MediaPreview.tsx — Pre-send attachment strip
193
-
194
- lib/
195
- agents.ts — Agent registry + SOUL.md reader
196
- agents-registry.ts — Registry loader (workspace override or bundled)
197
- agents.json — Bundled default agent registry
198
- anthropic.ts — OpenClaw vision pipeline (chat.send + poll)
199
- audio-recorder.ts — MediaRecorder + waveform extraction
200
- conversations.ts — Client-side conversation store (localStorage)
201
- crons.ts — Cron data via openclaw CLI
202
- env.ts — Environment variable helper
203
- memory.ts — Memory file reader
204
- multimodal.ts — Message → API content format converter
205
- sanitize.ts — HTML/markdown sanitization
206
- settings.ts — ClawPort settings (localStorage)
207
- transcribe.ts — Whisper transcription with fallback
208
- validation.ts — Chat message validation
209
- types.ts — Shared TypeScript types
210
- themes.ts — Theme definitions
211
- styles.ts — Semantic style constants
212
- utils.ts — Tailwind merge utility
157
+ ```bash
158
+ clawport dev # Start the development server
159
+ clawport start # Build and start production server
160
+ clawport setup # Auto-detect OpenClaw config, write .env.local
161
+ clawport status # Check gateway reachability and config
162
+ clawport help # Show usage
213
163
  ```
214
164
 
215
- ### Key Design Decisions
216
-
217
- - **No separate API keys** -- All AI calls (chat, vision, TTS, transcription) route through the OpenClaw gateway. One subscription, one token.
218
- - **No external charting/media libraries** -- Voice waveforms use plain div bars (not canvas), images resize via native Canvas API, all CSS uses Tailwind custom properties.
219
- - **Client-side persistence** -- Conversations stored in localStorage with base64 data URLs. Blob URLs don't survive page reload; data URLs do.
220
- - **Image resize before send** -- Images are resized client-side to max 1200px longest side before base64 encoding. This keeps the CLI argument payload under macOS's 1MB `ARG_MAX` limit.
221
- - **Send-then-poll for vision** -- The gateway's `chat.send` is async (returns immediately). We poll `chat.history` every 2 seconds until the assistant response appears, matched by timestamp.
222
-
223
165
  ---
224
166
 
225
- ## Themes
226
-
227
- Five built-in themes, toggled via the sidebar button:
167
+ ## Testing
228
168
 
229
- | Theme | Description |
230
- |-------|-------------|
231
- | **Dark** | Apple Dark Mode with warm blacks, red accent |
232
- | **Glass** | Frosted translucent panels on deep blue-black |
233
- | **Color** | Vibrant purple-indigo gradients |
234
- | **Light** | Apple Light Mode, clean whites |
235
- | **System** | Follows OS preference |
236
-
237
- All themes use CSS custom properties. Components reference semantic tokens (`--bg`, `--text-primary`, `--accent`, etc.) so every theme is automatic.
169
+ ```bash
170
+ npm test # 442 tests across 21 suites (Vitest)
171
+ npx tsc --noEmit # Type-check (zero errors)
172
+ npx next build # Production build
173
+ ```
238
174
 
239
175
  ---
240
176
 
241
177
  ## Stack
242
178
 
243
179
  - [Next.js 16](https://nextjs.org) (App Router, Turbopack)
244
- - [React 19](https://react.dev)
245
- - [TypeScript 5](https://typescriptlang.org)
180
+ - [React 19](https://react.dev) / [TypeScript 5](https://typescriptlang.org)
246
181
  - [Tailwind CSS 4](https://tailwindcss.com)
247
- - [React Flow (@xyflow/react)](https://reactflow.dev) -- Org chart
248
- - [OpenAI SDK](https://github.com/openai/openai-node) -- Gateway client (routed to Claude via OpenClaw)
249
- - [Vitest 4](https://vitest.dev) -- Test runner
250
- - [OpenClaw](https://openclaw.ai) -- AI gateway, agent runtime, vision pipeline
182
+ - [React Flow](https://reactflow.dev) -- org chart
183
+ - [Vitest 4](https://vitest.dev) -- testing
184
+ - [OpenClaw](https://openclaw.ai) -- AI gateway and agent runtime
251
185
 
252
186
  ---
253
187
 
254
- ## Development
188
+ ## Documentation
255
189
 
256
- See [CLAUDE.md](CLAUDE.md) for the full developer guide: architecture deep-dives, test patterns, common tasks, and contribution conventions.
257
-
258
- ```bash
259
- npm run dev # Start dev server (Turbopack, port 3000)
260
- npm test # Run all tests via Vitest
261
- npx tsc --noEmit # Type-check (expect 0 errors)
262
- npx next build # Production build
263
- ```
190
+ | Document | Description |
191
+ |----------|-------------|
192
+ | [SETUP.md](SETUP.md) | Full setup guide, agent customization, troubleshooting |
193
+ | [docs/API.md](docs/API.md) | REST API reference for all endpoints |
194
+ | [docs/COMPONENTS.md](docs/COMPONENTS.md) | UI component catalog (50+ components) |
195
+ | [docs/THEMING.md](docs/THEMING.md) | Theme system, CSS tokens, settings API |
196
+ | [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
197
+ | [CHANGELOG.md](CHANGELOG.md) | Version history |
198
+ | [CLAUDE.md](CLAUDE.md) | Developer architecture guide |
264
199
 
265
200
  ---
266
201
 
267
- ## Built by
202
+ ## Contributing
268
203
 
269
- [John Rice](https://github.com/johnrice) with [Jarvis](https://openclaw.ai) (OpenClaw AI)
204
+ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines.
270
205
 
271
206
  ---
272
207
 
273
- ## npm
274
-
275
- ```bash
276
- npm install -g clawport-ui
277
- clawport help
278
- ```
279
-
280
- Published as [`clawport-ui`](https://www.npmjs.com/package/clawport-ui) on npm. The CLI command is `clawport` (not `clawport-ui`). The separate `clawport` npm package is unrelated and not affiliated with this project.
281
-
282
- ### CLI Commands
208
+ ## License
283
209
 
284
- | Command | Description |
285
- |---------|-------------|
286
- | `clawport dev` | Start the development server |
287
- | `clawport start` | Build and start the production server |
288
- | `clawport setup` | Auto-detect OpenClaw config and write `.env.local` |
289
- | `clawport status` | Check gateway reachability and current config |
290
- | `clawport help` | Show usage |
210
+ [MIT](LICENSE)
291
211
 
292
212
  ---
293
213
 
294
- ## License
295
-
296
- MIT
214
+ Built by [John Rice](https://github.com/JohnRiceML) with [Jarvis](https://openclaw.ai) (OpenClaw AI).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "clawport-ui",
3
- "version": "0.5.2",
3
+ "version": "0.5.4",
4
4
  "description": "Open-source dashboard for managing, monitoring, and chatting with your OpenClaw AI agents.",
5
5
  "homepage": "https://clawport.dev",
6
6
  "repository": {