claude-ws 0.1.25 → 0.1.27

package/README.md

@@ -1,321 +1,94 @@
-# Claude Workspace
+# ClaudeWS
 
-> ⚠️ **DISCLAIMER:** This software is provided "AS IS" without warranty. The owners and contributors accept **no liability** for any damages or claims arising from its use. [Read full disclaimer](./DISCLAIMER.md).
+> **DISCLAIMER:** This software is provided "AS IS" without warranty. [Read full disclaimer](./DISCLAIMER.md).
 
-**Visual workspace for Claude Code with Kanban board, code editor, and Git integration.**
+**Visual workspace for Claude Code** — Kanban board, code editor, Git integration, local-first SQLite.
 
-Local-first SQLite database. Real-time streaming. Plugin system for custom agents and skills.
-
----
-
-## Why Claude Workspace?
-
-| Feature | Benefit |
-|---------|---------|
-| 🌍 **Work Everywhere** | SQLite-based local storage—no cloud dependency, works offline anywhere |
-| ⚡ **Consistent Performance** | Lightweight footprint, instant startup, responsive UI on any connection |
-| 🎯 **Unique Workflow** | Conversation checkpoints—rewind, branch, and continue at any point |
-| ✨ **Intuitive Management** | Drag-and-drop Kanban, live streaming, file browser with Git status |
-| 🔌 **Flexible Plugins** | Agent Factory—install only the skills and agents your project needs |
-| 🔋 **Claude Code Native** | Full CLI integration with real-time streaming and file attachments |
+![Desktop](./public/desktop-review-0.jpeg)
 
 ---
 
 ## Features
 
-**Task Management**
-- Kanban board: To Do → In Progress → In Review → Done → Cancelled
-- Drag-and-drop task cards with auto-save
-- Full conversation history per task
-
-**AI Interaction**
-- Real-time streaming of Claude responses via Socket.io
-- Checkpoints: Save and rewind to any conversation state
-- File attachments for context
-- Custom commands: `/cook`, `/plan`, `/fix`, `/brainstorm`
-- Detachable chat window
-
-**Code Editor**
-- Tabbed CodeMirror editor with syntax highlighting
-- AI-powered inline code suggestions
-- Go-to-definition navigation
-- Multi-file editing
-
-**File System**
-- Interactive file tree browser
-- Unified search (files + content)
-- File preview
-
-**Git Integration**
-- Full Git workflow: status, stage, commit, diff
-- Visual Git graph
-- Checkpoint Git snapshots for time-travel debugging
-
-**Agent Factory**
-- Plugin system for Claude skills, commands, agents
-- Dependency management
-- Per-project plugin installation
-
-**Developer Tools**
-- Background shell process manager
-- Terminal output streaming
-- Multi-project workspace support
-- Themes: Light, Dark, VS Code variants, Dracula
+- **Kanban Board** — Drag-and-drop task management with full conversation history
+- **Real-time Streaming** — Live Claude responses via Socket.io
+- **Checkpoints** — Save and rewind to any conversation state
+- **Code Editor** — Tabbed CodeMirror with syntax highlighting and AI suggestions
+- **Git Integration** — Status, stage, commit, diff, visual graph
+- **Agent Factory** — Plugin system for custom skills, commands, agents
+- **Themes** — Light, Dark, VS Code variants, Dracula
 
 ---
 
 ## Quick Start
 
-### Option 1: Run with npx
-
-**Prerequisites:** Node.js 20+, pnpm 9+, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+**Prerequisites:** Node.js 20+, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
 
 ```bash
-npx -y claude-ws
-```
+# Option 1: npx (quick try)
+npx -y claudews
 
-The `-y` flag skips the "Ok to proceed?" prompt.
+# Option 2: Global install (recommended)
+npm install -g claudews
+claudews
 
-The first run will:
-- Auto-create SQLite database in `~/.claude-ws/`
-- Install dependencies and build automatically
-- Start the server on http://localhost:8556
-
-### Option 2: Install globally (Recommended)
-
-```bash
-npm install -g claude-ws
-claude-ws
+# Option 3: From source
+git clone https://github.com/Claude-Workspace/claudews.git
+cd claudews
+pnpm install && pnpm dev
 ```
 
-Global installation avoids npx prompts and rebuilding on every run.
+Open http://localhost:8556
 
-### Option 3: Development from source
+---
 
-```bash
-git clone https://github.com/Claude-Workspace/claude-ws.git
-cd claude-ws
-pnpm install
-pnpm db:migrate
-pnpm dev
-```
+## API Documentation
 
-Open [http://localhost:8556](http://localhost:8556)
+See [Swagger API Docs](README-docs-swagger.md)
 
 ---
 
 ## Configuration
 
-### API Authentication (Optional)
-
-For secure deployments, you can enable API authentication by setting an `API_ACCESS_KEY`:
-
-1. Create a `.env` file in your project directory (or use the global one in `~/.claude-ws/.env`)
-2. Add your API access key:
+Create `.env` file (or use `~/.claudews/.env`):
 
 ```bash
-# .env
-API_ACCESS_KEY=your-secret-key-here
-```
-
-3. All API requests must include the key in the `x-api-key` header:
+# Optional: API authentication for remote access
+API_ACCESS_KEY=your-secret-key
 
-```bash
-curl -H "x-api-key: your-secret-key-here" http://localhost:8556/api/conversations
+# Optional: Custom Claude CLI path
+CLAUDE_PATH=/path/to/claude
 ```
 
-**Note:** Leave `API_ACCESS_KEY` empty to disable authentication (default for local development).
-
-### Claude Code CLI Path
-
-Claude Workspace requires the Claude Code CLI to be installed. Set the `CLAUDE_PATH` environment variable to point to your Claude executable:
-
-**Linux/Ubuntu:**
-```bash
-CLAUDE_PATH=/home/$(whoami)/.local/bin/claude
-```
-
-**macOS (Homebrew):**
-```bash
-CLAUDE_PATH=/opt/homebrew/bin/claude
-```
-
-**Windows:**
-```bash
-CLAUDE_PATH=%USERPROFILE%\.local\bin\claude.exe
-```
-
-Add this to your `.env` file in the project directory, or the global `.env` at `~/.claude-ws/.env`.
-
-### Environment Variables
-
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `CLAUDE_PATH` | Path to Claude Code CLI executable | Auto-detected |
-| `PORT` | Server port | `3000` |
-| `NODE_ENV` | Environment mode | `development` |
-| `API_ACCESS_KEY` | API authentication key | (empty, no auth) |
-| `DATABASE_URL` | SQLite database path | `./data.db` |
-| `AGENT_FACTORY_DIR` | Agent Factory plugins directory | `~/.claude/agentfactory` |
+| `PORT` | Server port | `8556` |
+| `API_ACCESS_KEY` | API authentication key | (empty) |
+| `CLAUDE_PATH` | Claude CLI path | Auto-detected |
 
 ---
 
-## Work Everywhere with Cloudflare Tunnel
-
-Access Claude Workspace securely from anywhere using Cloudflare Tunnel + Access.
-
-### 1. Install cloudflared
-
-```bash
-# macOS
-brew install cloudflared
-
-# Linux
-curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
-chmod +x cloudflared && sudo mv cloudflared /usr/local/bin/
-
-# Windows
-winget install Cloudflare.cloudflared
-```
-
-### 2. Authenticate with Cloudflare
-
-```bash
-cloudflared tunnel login
-```
-
-### 3. Create Tunnel
+## Production (PM2)
 
 ```bash
-cloudflared tunnel create claude-workspace
-```
-
-### 4. Configure Tunnel
-
-Create `~/.cloudflared/config.yml`:
-
-```yaml
-tunnel: claude-workspace
-credentials-file: ~/.cloudflared/<TUNNEL_ID>.json
-
-ingress:
-  - hostname: claude-ws.yourdomain.com
-    service: http://localhost:8556
-  - service: http_status:404
-```
-
-### 5. Add DNS Record
-
-```bash
-cloudflared tunnel route dns claude-workspace claude-ws.yourdomain.com
-```
-
-### 6. Run Tunnel
-
-```bash
-# Foreground
-cloudflared tunnel run claude-workspace
-
-# Or as service (recommended)
-sudo cloudflared service install
-sudo systemctl enable cloudflared
-sudo systemctl start cloudflared
+npm install -g pm2
+pnpm pm2:start    # Start server (auto-builds)
+pnpm pm2:logs     # View logs
+pnpm pm2:restart  # Restart
+pnpm pm2:stop     # Stop
 ```
 
-### 7. Setup Cloudflare Access (Authentication)
-
-1. Go to [Cloudflare Zero Trust Dashboard](https://one.dash.cloudflare.com/)
-2. Navigate to **Access** → **Applications** → **Add an application**
-3. Select **Self-hosted**
-4. Configure:
-   - **Application name**: Claude Workspace
-   - **Session duration**: 24 hours (or your preference)
-   - **Application domain**: `claude-ws.yourdomain.com`
-5. Add **Access Policy**:
-   - **Policy name**: Allowed Users
-   - **Action**: Allow
-   - **Include**: Emails ending in `@yourdomain.com` or specific email addresses
-6. Save and deploy
-
-Now access `https://claude-ws.yourdomain.com` from anywhere with Cloudflare authentication.
-
 ---
 
-## Updating
-
-### Check current version
-```bash
-claude-ws --version
-```
-
-### Update to latest version
-```bash
-npm update -g claude-ws
-```
+## Remote Access
 
-### Force reinstall
-```bash
-npm install -g claude-ws@latest
-```
+For secure remote access, see [Cloudflare Tunnel Setup](./docs/cloudflare-tunnel.md).
 
 ---
 
 ## Tech Stack
 
-- **Framework**: Next.js 16 + React 19
-- **Database**: SQLite + Drizzle ORM
-- **Real-time**: Socket.io
-- **Styling**: Tailwind CSS 4
-- **UI**: Radix UI primitives
-- **State**: Zustand
-- **Drag & Drop**: dnd-kit
-
----
-
-## Scripts
-
-| Command | Description |
-|---------|-------------|
-| `pnpm dev` | Start development server |
-| `pnpm build` | Build for production |
-| `pnpm start` | Start production server |
-| `pnpm lint` | Run ESLint |
-| `pnpm db:migrate` | Run database migrations |
-| `pnpm pm2:start` | Start with PM2 process manager |
-| `pnpm pm2:stop` | Stop PM2 process |
-| `pnpm pm2:restart` | Restart PM2 process |
-| `pnpm pm2:logs` | View PM2 logs |
-| `pnpm pm2:monit` | Monitor PM2 process |
-
-### Running with PM2
-
-For production deployments with auto-restart and process management:
-
-```bash
-# Install PM2 globally (if not already installed)
-npm install -g pm2
-
-# Start the server
-pnpm pm2:start
-
-# View logs
-pnpm pm2:logs
-
-# Monitor process
-pnpm pm2:monit
-
-# Restart
-pnpm pm2:restart
-
-# Stop
-pnpm pm2:stop
-```
-
-PM2 Features:
-- Auto-restart on crash (max 10 attempts)
-- Memory limit monitoring (500MB)
-- Log rotation and management
-- Process status tracking
+Next.js 16, React 19, SQLite + Drizzle ORM, Socket.io, Tailwind CSS 4, Radix UI, Zustand
 
 ---
 

package/bin/claudekanban.js

@@ -14,6 +14,9 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
+// Load environment variables
+require('dotenv').config({ path: path.join(__dirname, '..', '.env') });
+
 // Get package root directory
 const packageRoot = path.resolve(__dirname, '..');
 
@@ -43,11 +46,11 @@ For more info: https://github.com/Claude-Workspace/claude-ws
   process.exit(0);
 }
 
-// Database path (in user's home directory for persistence)
-const DB_DIR = path.join(os.homedir(), '.claude-ws');
+// Database path - use DATA_DIR from env if configured, otherwise default to project data dir
+const DB_DIR = process.env.DATA_DIR || path.join(packageRoot, 'data');
 const DB_PATH = path.join(DB_DIR, 'claude-ws.db');
 
-// Ensure .claude-ws directory exists
+// Ensure database directory exists
 if (!fs.existsSync(DB_DIR)) {
   console.log('[Claude Workspace] Creating database directory:', DB_DIR);
   fs.mkdirSync(DB_DIR, { recursive: true });

package/drizzle.config.ts

@@ -1,10 +1,13 @@
 import type { Config } from 'drizzle-kit';
 import path from 'path';
-import os from 'os';
 import fs from 'fs';
+import { config } from 'dotenv';
 
-// Database location in user's home directory for persistence
-const DB_DIR = path.join(os.homedir(), '.claude-ws');
+// Load environment variables
+const env = config();
+
+// Database location - use DATA_DIR from env if configured, otherwise default to project data dir
+const DB_DIR = process.env.DATA_DIR || path.join(process.cwd(), 'data');
 const DB_PATH = path.join(DB_DIR, 'claude-ws.db');
 
 // Ensure directory exists before drizzle-kit tries to connect

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "claude-ws",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "private": false,
   "description": "A beautifully crafted workspace interface for Claude Code with real-time streaming and local SQLite database",
   "keywords": [
     "claude",
+    "claudews",
+    "claude-ws",
     "claude-code",
     "workspace",
     "task-management",
@@ -29,6 +31,7 @@
   "files": [
     "bin",
     "drizzle",
+    "scripts",
     "src",
     "public",
     "server.ts",
@@ -57,24 +60,11 @@
   },
   "scripts": {
     "dev": "tsx server.ts",
-    "dev:next": "next dev",
     "build": "NODE_ENV=production next build",
     "start": "NODE_ENV=production tsx server.ts",
-    "lint": "eslint",
     "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "pm2:start": "pm2 start ecosystem.config.cjs",
-    "pm2:stop": "pm2 stop claude-ws",
-    "pm2:restart": "pm2 restart claude-ws",
-    "pm2:delete": "pm2 delete claude-ws",
-    "pm2:logs": "pm2 logs claude-ws",
-    "pm2:monit": "pm2 monit",
-    "version:patch": "npm version patch --no-git-tag-version",
-    "version:minor": "npm version minor --no-git-tag-version",
-    "version:major": "npm version major --no-git-tag-version",
-    "prepublishOnly": "npm run build",
-    "test:package": "./scripts/test-package.sh",
-    "publish:npm": "npm publish --access public"
+    "db:fix": "tsx scripts/db-fix-columns.ts",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.5",
@@ -110,6 +100,12 @@
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-toast": "^1.2.15",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "@tailwindcss/postcss": "^4",
+    "@types/adm-zip": "^0.5.7",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
     "@uiw/react-codemirror": "^4.25.4",
     "adm-zip": "^0.5.16",
     "better-sqlite3": "^12.5.0",
@@ -119,8 +115,12 @@
     "date-fns": "^4.1.0",
     "diff": "^8.0.3",
     "dotenv": "^17.2.3",
+    "drizzle-kit": "^0.31.8",
     "drizzle-orm": "^0.45.1",
+    "eslint": "^9",
+    "eslint-config-next": "^16.1.3",
     "highlight.js": "^11.11.1",
+    "js-yaml": "^4.1.1",
     "lucide-react": "^0.562.0",
     "nanoid": "^5.1.6",
     "next": "^16.1.3",
@@ -134,22 +134,16 @@
     "socket.io-client": "^4.8.3",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.4.0",
+    "tailwindcss": "^4",
     "tar": "^7.5.2",
     "tsx": "^4.21.0",
+    "tw-animate-css": "^1.4.0",
     "typescript": "^5",
     "vscode-icons-js": "^11.6.1",
-    "zustand": "^5.0.9",
-    "@tailwindcss/postcss": "^4",
-    "tailwindcss": "^4",
-    "tw-animate-css": "^1.4.0",
-    "drizzle-kit": "^0.31.8",
-    "@types/adm-zip": "^0.5.7",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^20",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
-    "eslint": "^9",
-    "eslint-config-next": "^16.1.3"
+    "zustand": "^5.0.9"
   },
-  "packageManager": "pnpm@10.28.0+sha512.05df71d1421f21399e053fde567cea34d446fa02c76571441bfc1c7956e98e363088982d940465fd34480d4d90a0668bc12362f8aa88000a64e83d0b0e47be48"
+  "packageManager": "pnpm@10.28.0+sha512.05df71d1421f21399e053fde567cea34d446fa02c76571441bfc1c7956e98e363088982d940465fd34480d4d90a0668bc12362f8aa88000a64e83d0b0e47be48",
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9"
+  }
 }

package/public/docs/swagger/api-docs.html

@@ -0,0 +1,96 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Claude Workspace API Documentation</title>
+    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui.css">
+    <style>
+        html {
+            box-sizing: border-box;
+            overflow: -moz-scrollbars-vertical;
+            overflow-y: scroll;
+        }
+        *, *:before, *:after {
+            box-sizing: inherit;
+        }
+        body {
+            margin: 0;
+            padding: 0;
+            font-family: 'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+        }
+        .topbar {
+            background-color: #1a1a1a;
+            padding: 15px 0;
+        }
+        .topbar-wrapper {
+            max-width: 1460px;
+            margin: 0 auto;
+            padding: 0 20px;
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+        }
+        .topbar-wrapper .link {
+            display: flex;
+            align-items: center;
+            color: #ffffff;
+            text-decoration: none;
+        }
+        .topbar-wrapper .link img {
+            height: 40px;
+            margin-right: 12px;
+        }
+        .topbar-wrapper .link span {
+            font-size: 1.2em;
+            font-weight: 600;
+        }
+        .info {
+            margin: 40px 0;
+        }
+    </style>
+</head>
+<body>
+    <div class="topbar">
+        <div class="topbar-wrapper">
+            <a href="https://github.com/Claude-Workspace/claude-ws" class="link">
+                <svg height="32" viewBox="0 0 16 16" version="1.1" width="32" aria-hidden="true" fill="white">
+                    <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+                <span>Claude Workspace API</span>
+            </a>
+        </div>
+    </div>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-bundle.js" charset="UTF-8"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-standalone-preset.js" charset="UTF-8"></script>
+    <script>
+    window.onload = function() {
+        const ui = SwaggerUIBundle({
+            url: "/docs/swagger/swagger.yaml",
+            dom_id: '#swagger-ui',
+            deepLinking: true,
+            presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIStandalonePreset
+            ],
+            plugins: [
+                SwaggerUIBundle.plugins.DownloadUrl
+            ],
+            layout: "StandaloneLayout",
+            defaultModelsExpandDepth: 1,
+            defaultModelExpandDepth: 1,
+            docExpansion: "list",
+            filter: true,
+            tryItOutEnabled: true,
+            persistAuthorization: true,
+            syntaxHighlight: {
+                activate: true,
+                theme: "monokai"
+            }
+        });
+        window.ui = ui;
+    };
+    </script>
+</body>
+</html>