SuperCharged-Claude-Code-Upgrade/README.md

# Claude Code Web Interface

> A powerful web-based IDE for Claude Code CLI with session management, project organization, real-time chat, and AI-powered development tools.

[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
[![Express](https://img.shields.io/badge/Express-4.22-blue)](https://expressjs.com/)
[![SQLite](https://img.shields.io/badge/SQLite-3.0-orange)](https://www.sqlite.org/)
[![License](https://img.shields.io/badge/License-ISC-blue)](LICENSE)
[![Version](https://img.shields.io/badge/Version-1.2.0-brightgreen)](https://github.rommark.dev/admin/ClaudeCLI-Web)

---

## Version History

### v1.2.0 (2026-01-20)

**🚀 Major Feature: CLI Session-Based Full Stack Mode**

This release introduces a simplified Full Stack mode using Claude Code CLI sessions instead of WebContainers, eliminating complex COOP/COEP header requirements and reducing bundle size by ~350KB.

#### Changes

**✨ New Features**
- **CLI Session-Based Terminal Mode** - Execute shell commands directly in Claude Code CLI sessions
  - Spawns bash process for command execution
  - Captures stdout, stderr, and exit codes
  - Real-time output streaming via events
  - No SharedArrayBuffer or special headers required
- **Shell Command API** - `POST /claude/api/shell-command` endpoint for executing commands
- **Smart Command Detection** - Automatically detects shell commands vs conversational messages
  - Warns when conversational messages are sent in Terminal mode
  - Auto-switches to Chat mode for non-shell commands

**🔧 Improvements**
- **Simplified Architecture** - Removes WebContainer dependency
  - Faster startup (no 350KB bundle download)
  - Better error handling
  - Uses existing Claude Code infrastructure
- **Terminal Mode Reliability** - Fixed terminal creation failures
  - Removed terminalManager reference errors
  - Added fallback to native command execution
- **Project-Based Session Filtering** - Improved session filtering logic
  - Path-based matching for accurate project assignment
  - Better handling of nested directories

**🐛 Bug Fixes**
- Fixed terminal creation failure in Full Stack mode ("Failed to create terminal" error)
- Fixed WebContainer SharedArrayBuffer serialization errors
- Fixed session filtering showing unrelated sessions
- Fixed memory leaks from setInterval() calls
- Fixed XSS vulnerability in autocomplete (file names now escaped)
- Fixed sendMessage() undefined errors

**📝 Technical Details**

- `services/claude-service.js`:
  - Added `executeShellCommand()` method for spawning bash processes
  - Captures stdout/stderr with real-time event emission
  - Returns Promise with exitCode, stdout, stderr

- `server.js`:
  - Added `POST /claude/api/shell-command` endpoint
  - Requires authentication via `requireAuth` middleware
  - Validates sessionId and command parameters

- `public/claude-ide/chat-functions.js`:
  - Rewrote `handleWebContainerCommand()` to use CLI sessions
  - Added `sendShellCommand()` helper for API calls
  - Smart command detection for shell vs conversational
  - Auto-mode switching suggestions

**🔒 Security**
- All shell command endpoints require authentication
- Command injection protection via bash shell spawning
- Proper error handling for failed commands

**⚙️ Compatibility**
- Requires Claude Code CLI to be installed and accessible
- No special HTTP headers needed (removes COOP/COEP requirement)
- Maintains backward compatibility with Chat mode

---

### v1.1.0 (2026-01-19)

**🚀 Major Feature: HTTP Polling for Terminal Output**

This release addresses critical WebSocket connectivity issues in nginx reverse proxy configurations by implementing a robust HTTP polling mechanism for terminal output.

#### Changes

**✨ New Features**
- **HTTP Polling System** - Terminal output now uses HTTP polling instead of WebSocket for reliable data delivery
  - Server buffers PTY output in memory with automatic cleanup
  - Frontend polls every 100ms for new output entries
  - Monotonically increasing index for efficient data retrieval
  - Automatic cleanup of old output (5 minutes retention)

**🔧 Improvements**
- **Terminal Type Selection** - Added dropdown to choose between:
  - Standard Shell (bash/zsh)
  - Claude Code CLI (auto-launches with `--dangerously-skip-permissions`)
- **Debug Panel** - Always-visible debug panel for troubleshooting terminal issues
- **HTTP POST Input** - Commands sent via HTTP POST to bypass WebSocket send failures
- **Terminal Resize** - HTTP-based resize endpoint for terminal dimensions

**🐛 Bug Fixes**
- Fixed WebSocket closure with code 1006 (abnormal closure) in nginx configurations
- Fixed terminal command execution failing silently
- Fixed race condition in `switchToTerminal()` method
- Removed stabilization delays that caused WebSocket issues
- Fixed terminal type selector not appearing in modal

**📝 Technical Details**
- `services/terminal-service.js`:
  - Added `bufferOutput()` method for capturing PTY data
  - Added `getTerminalOutput()` for HTTP polling endpoint
  - Added `resizeTerminal()` for HTTP resize handling
  - Maintains WebSocket compatibility for legacy support

- `server.js`:
  - `GET /claude/api/terminals/:id/output` - Poll for new output
  - `POST /claude/api/terminals/:id/input` - Send command input
  - `POST /claude/api/terminals/:id/resize` - Resize terminal

- `public/claude-ide/terminal.js`:
  - Added `startPolling()` - 100ms interval polling
  - Added `stopPolling()` - Clean polling termination
  - Added `sendTerminalInput()` - HTTP POST for commands
  - Added `sendTerminalResize()` - HTTP POST for resize
  - Removed dependency on WebSocket for output display

**🔒 Security**
- All polling endpoints require authentication
- Output buffer size limited to 10,000 entries per terminal
- Automatic cleanup prevents memory exhaustion

**⚙️ Compatibility**
- Maintains backward compatibility with WebSocket connections
- Works seamlessly with nginx reverse proxy
- No configuration changes required

---

### v1.0.0 (Initial Release)

- Session management with real-time status tracking
- Project organization with smart suggestions
- WebSocket-based terminal integration
- XML tag system for file operations
- Obsidian vault integration

---

## Table of Contents

- [Features](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage Guide](#usage-guide)
- [API Reference](#api-reference)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)

---

## Features

### 🎯 Core Capabilities

- **Session Management** - Create, monitor, and control Claude Code sessions with real-time status tracking
- **Project Organization** - Group sessions into projects with smart suggestions and auto-assignment
- **Real-Time Chat** - WebSocket-powered communication with live command execution
- **File Browser** - Navigate, view, and edit files in your Obsidian vault
- **Terminal Integration** - Full terminal emulation with xterm.js and session picker
- **XML Tag System** - Structured AI operations for writing files, editing, and running commands

### 📦 What's New

#### Project Organization (Latest)
- ✨ Persistent projects as first-class entities
- ✨ Smart session assignment based on directory, recency, and name similarity
- ✨ Drag-and-drop session reassignment via context menu
- ✨ Soft delete with recycle bin (restore or permanent delete)
- ✨ Auto-assign new sessions to selected project

---

## Quick Start

### Prerequisites

- Node.js 18+ and npm
- Claude Code CLI installed
- Obsidian vault (optional, for session storage)

### 3-Minute Setup

```bash
# 1. Clone the repository
git clone https://github.rommark.dev/admin/ClaudeCLI-Web.git
cd ClaudeCLI-Web

# 2. Install dependencies
npm install

# 3. Start the server
npm start

# 4. Open your browser
# Navigate to http://localhost:3010/claude
# Login with: admin / !@#$q1w2e3r4!A
```

That's it! You're ready to use Claude Code through the web interface.

---

## Installation

### Production Deployment

#### Using Systemd (Recommended)

1. Copy the service file:
```bash
cp obsidian-web.service /etc/systemd/system/
```

2. Reload systemd and start:
```bash
sudo systemctl daemon-reload
sudo systemctl enable obsidian-web
sudo systemctl start obsidian-web
```

3. Configure Nginx reverse proxy (optional):
```bash
cp obsidian-nginx.conf /etc/nginx/sites-available/claude-web
sudo ln -s /etc/nginx/sites-available/claude-web /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

#### Using PM2

```bash
npm install -g pm2
pm2 start server.js --name claude-web
pm2 save
pm2 startup
```

### Environment Variables

Create a `.env` file in the project root:

```bash
# Server Configuration
PORT=3010
SESSION_SECRET=your-secret-key-here

# Database
DB_PATH=./database.sqlite

# Claude Code
VAULT_PATH=/home/uroma/obsidian-vault
CLAUDE_CLI_PATH=claude  # Path to claude command
```

---

## Configuration

### Server Settings

Edit `server.js` to customize:

- **PORT** (default: 3010) - Server port
- **VAULT_PATH** - Path to your Obsidian vault
- **SESSION_SECRET** - Session encryption key

### Authentication

Default credentials:
- Username: `admin`
- Password: `!@#$q1w2e3r4!A`

**⚠️ Change these in production!** Edit the `users` object in `server.js`:

```javascript
const users = {
  admin: {
    passwordHash: bcrypt.hashSync('your-secure-password', 10)
  }
};
```

---

## Usage Guide

### Managing Sessions

#### Creating a Session

1. Click **"+ New Session"** on the landing page
2. Enter a working directory
3. (Optional) Select a project to auto-assign
4. Click **Create Session**

The session will start automatically and you can begin chatting with Claude.

#### Session Controls

- **Send Commands** - Type in the chat input and press Enter
- **View Output** - Real-time terminal output in the session panel
- **Terminate** - Click the stop button to end the session
- **Duplicate** - Clone a session with the same working directory

### Organizing Projects

#### Creating a Project

1. Navigate to **/projects** or click "Projects" in the header
2. Click **"+ New Project"**
3. Fill in the details:
   - **Name** (required) - Project identifier
   - **Path** (required) - Working directory
   - **Description** - What this project is about
   - **Icon** - Emoji for visual identification (📁, 🚀, etc.)
   - **Color** - Theme color for the project card
4. Click **Save Project**

#### Assigning Sessions to Projects

**Automatic Assignment:**
- When creating a session, select a project from the dropdown
- The session will be automatically assigned to that project

**Manual Assignment:**
1. Go to the sessions landing page
2. Right-click on any session card
3. Select **"Move to Project"**
4. Choose from:
   - 🎯 **Suggestions** - Smart recommendations based on directory, recency, and name
   - 📂 **Show All Projects** - Full project list
   - 📄 **Move to Unassigned** - Remove project association

#### Smart Suggestions

The system suggests projects based on:
- **Same directory** (90 points) - Exact path match
- **Subdirectory** (50 points) - Session path under project path
- **Used today** (20 points) - Active within last 24 hours
- **Used this week** (10 points) - Active within last 7 days
- **Similar name** (15 points) - Name overlap

Suggestions with 90+ points show 🎯, 50-89 show 📂, lower show 💡

#### Managing Projects

**Edit Project:**
- Right-click project card → Edit
- Modify description, icon, color, or path
- Save changes

**Delete Project:**
- Right-click project card → Move to Recycle Bin
- Project and all sessions are soft-deleted
- Can restore from recycle bin within 30 days

**Recycle Bin:**
- Click **"🗑️ Recycle Bin"** button on projects page
- Restore deleted projects (restores all sessions too)
- Permanently delete (cannot be undone)

### Using the Terminal

#### Opening a Terminal

1. Click **"+ New Terminal"** in the IDE
2. Select a working directory
3. The terminal will open with the Claude CLI ready

#### Session Picker

When creating a new terminal:
- Select from your last 10 sessions (web and local CLI sessions)
- Sessions are grouped by type:
  - **Web Sessions** 💬 - Created through this interface
  - **Local CLI Sessions** 💻 - Created using Claude Code CLI directly
- Click **"Create New Session"** to start fresh

#### Terminal Features

- **Tabbed Interface** - Multiple terminals open simultaneously
- **Status Indicators** - Running, Stopped, Error states
- **Session Attachment** - Click "🔗 Attach" to link terminal to a session
- **Auto-Focus** - Clicking a terminal automatically focuses it for keyboard input

### XML Tag System

Claude can use special XML tags to perform actions:

```xml
<!-- Write a new file -->
<claude-write path="src/components/Header.tsx">
import React from 'react';
export default function Header() {
  return <h1>My App</h1>;
}
</claude-write>

<!-- Edit existing file -->
<claude-edit path="src/App.tsx" mode="replace">
<search>
export default function App() {
  return <div>Old Content</div>;
}
</search>
<replace>
export default function App() {
  return <div>New Content</div>;
}
</replace>
</claude-edit>

<!-- Execute command -->
<claude-command working-dir="/path/to/project">
npm run dev
</claude-command>

<!-- Add dependency -->
<claude-dependency package="react-query">
npm install @tanstack/react-query
</claude-dependency>
```

These tags are automatically parsed and executed when Claude includes them in responses.

---

## API Reference

### Session Endpoints

#### Create Session
```http
POST /claude/api/claude/sessions
Content-Type: application/json

{
  "workingDir": "/path/to/project",
  "projectId": 1
}
```

#### List Sessions
```http
GET /claude/api/claude/sessions
```

#### Get Session Details
```http
GET /claude/api/claude/sessions/:id
```

#### Duplicate Session
```http
POST /claude/api/claude/sessions/:id/duplicate
```

#### Terminate Session
```http
DELETE /claude/api/claude/sessions/:id
```

### Project Endpoints

#### List Projects
```http
GET /api/projects
```

#### Create Project
```http
POST /api/projects
Content-Type: application/json

{
  "name": "My API Project",
  "path": "/home/uroma/my-api",
  "description": "REST API development",
  "icon": "🚀",
  "color": "#4a9eff"
}
```

#### Update Project
```http
PUT /api/projects/:id
Content-Type: application/json

{
  "description": "Updated description",
  "icon": "⚡"
}
```

#### Delete Project (Soft Delete)
```http
DELETE /api/projects/:id
```

#### Restore Project
```http
POST /api/projects/:id/restore
```

#### Permanently Delete Project
```http
DELETE /api/projects/:id/permanent
```

#### Get Recycle Bin
```http
GET /api/recycle-bin
```

### Session Reassignment

#### Move Session to Project
```http
POST /claude/api/claude/sessions/:id/move
Content-Type: application/json

{
  "projectId": 1
}
```

#### Get Project Suggestions for Session
```http
GET /api/projects/suggestions?sessionId=session-123
```

### WebSocket

#### Connect to Session
```javascript
const ws = new WebSocket('ws://localhost:3010/claude/api/claude/chat');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    sessionId: 'session-123',
    token: 'your-session-token'
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === 'response') {
    console.log(message.content);
  }
};
```

---

## Development

### Project Structure

```
obsidian-web-interface/
├── services/
│   ├── claude-service.js       # Claude Code CLI manager
│   ├── claude-workflow-service.js  # Workflow orchestration
│   ├── terminal-service.js      # Terminal (pty) management
│   ├── xml-parser.js            # Custom XML tag processor
│   ├── response-processor.js    # Response streaming
│   ├── tag-parser.js            # Tag extraction
│   └── system-prompt.js         # AI rules configuration
├── public/
│   ├── claude-ide/
│   │   ├── index.html          # Main IDE interface
│   │   ├── ide.css             # IDE styles
│   │   ├── ide.js              # IDE JavaScript
│   │   ├── terminal.js         # Terminal management
│   │   ├── terminal.css        # Terminal styles
│   │   ├── chat-enhanced.js    # Chat functionality
│   │   ├── preview-manager.js  # Preview panel
│   │   └── sessions-landing.js # Sessions landing page
│   ├── css/                    # Global styles
│   └── projects.html           # Projects page
├── scripts/
│   └── migrate-to-projects.js  # Database migration
├── server.js                   # Express + WebSocket server
├── package.json                # Dependencies
└── database.sqlite             # SQLite database (generated)
```

### Running in Development

```bash
# Install dependencies
npm install

# Start with hot-reload (if using nodemon)
npm run dev

# Or standard start
npm start

# Run database migration
npm run migrate:projects
```

### Database Schema

#### Projects Table
```sql
CREATE TABLE projects (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  description TEXT,
  icon TEXT DEFAULT '📁',
  color TEXT DEFAULT '#4a9eff',
  path TEXT NOT NULL,
  createdAt TEXT NOT NULL,
  lastActivity TEXT NOT NULL,
  deletedAt TEXT NULL
);
```

#### Sessions Table
```sql
CREATE TABLE sessions (
  id TEXT PRIMARY KEY,
  projectId INTEGER NULL,
  deletedAt TEXT NULL,
  FOREIGN KEY (projectId) REFERENCES projects(id) ON DELETE SET NULL
);
```

### Adding New Features

1. **Backend** - Add endpoints to `server.js`
2. **Frontend** - Create components in `public/claude-ide/`
3. **Styles** - Add CSS to component-specific stylesheets
4. **Database** - Update schema in `services/database.js`
5. **Test** - Verify functionality and document API changes

---

## Troubleshooting

### Common Issues

#### Server won't start
```bash
# Check if port is in use
lsof -i :3010

# Kill existing process
kill -9 <PID>

# Or change PORT in server.js
```

#### Claude CLI not found
```bash
# Verify claude is in PATH
which claude

# If not found, install Claude Code CLI
npm install -g @anthropic-ai/claude-code
```

#### Database errors
```bash
# Recreate database
rm database.sqlite
npm start  # Will recreate automatically
```

#### WebSocket connection failed
- Check browser console for errors
- Verify server is running on correct port
- Ensure no firewall is blocking WebSocket connections
- Check CORS settings if using custom domain

#### Sessions not showing
- Verify `VAULT_PATH` points to correct directory
- Check file permissions on vault directory
- Ensure `Claude Sessions` folder exists

### Getting Help

- **Documentation** - Check `docs/` folder for detailed guides
- **Issues** - Report bugs on Gitea: https://github.rommark.dev/admin/ClaudeCLI-Web/issues
- **Logs** - Check server logs: `journalctl -u obsidian-web -f` (systemd) or console output

---

## Contributing

We welcome contributions! Here's how to get started:

### Development Workflow

1. **Fork** the repository on Gitea
2. **Clone** your fork: `git clone https://github.rommark.dev/<your-username>/ClaudeCLI-Web.git`
3. **Create a branch**: `git checkout -b feature/your-feature-name`
4. **Make changes** following the coding standards
5. **Test** thoroughly (manual and automated)
6. **Commit** with clear messages: `git commit -m "feat: add your feature"`
7. **Push** to your fork: `git push origin feature/your-feature-name`
8. **Create Pull Request** on Gitea

### Coding Standards

- Use ES6+ JavaScript features
- Follow existing code style and formatting
- Add comments for complex logic
- Update documentation for new features
- Test across browsers (Chrome, Firefox, Safari)

### Commit Message Format

```
<type>(<scope>): <subject>

<body>

<footer>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
```

**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`

**Example:**
```
feat(terminal): add session picker for new terminals

Implement modal with last 10 sessions grouped by type (web/local).
Shows visual indicators for session status and working directory.

- Add session picker modal
- Group sessions by web/local
- Add visual status indicators

Closes #42

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
```

---

## License

ISC

---

## Acknowledgments

- **Claude (Anthropic)** - AI assistant powering the IDE
- **Claude Code** - Official CLI tool
- **Obsidian** - Knowledge base and note-taking platform
- **xterm.js** - Terminal emulation
- **Express.js** - Web framework
- **SQLite** - Embedded database

---

## Links

- **Documentation:** [docs/](docs/)
- **Gitea Repository:** [https://github.rommark.dev/admin/ClaudeCLI-Web](https://github.rommark.dev/admin/ClaudeCLI-Web)
- **Issue Tracker:** [https://github.rommark.dev/admin/ClaudeCLI-Web/issues](https://github.rommark.dev/admin/ClaudeCLI-Web/issues)
- **Claude Code Docs:** [https://docs.anthropic.com/claude-code](https://docs.anthropic.com/claude-code)