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.

---

Table of Contents

• Features
• Quick Start
• Installation
• Configuration
• Usage Guide
• API Reference
• Development
• Troubleshooting
• 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

# 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:

cp obsidian-web.service /etc/systemd/system/

2. Reload systemd and start:

sudo systemctl daemon-reload
sudo systemctl enable obsidian-web
sudo systemctl start obsidian-web

3. Configure Nginx reverse proxy (optional):

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

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:

# 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:

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:

<!-- 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

POST /claude/api/claude/sessions
Content-Type: application/json

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

List Sessions

GET /claude/api/claude/sessions

Get Session Details

GET /claude/api/claude/sessions/:id

Duplicate Session

POST /claude/api/claude/sessions/:id/duplicate

Terminate Session

DELETE /claude/api/claude/sessions/:id

Project Endpoints

List Projects

GET /api/projects

Create Project

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

PUT /api/projects/:id
Content-Type: application/json

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

Delete Project (Soft Delete)

DELETE /api/projects/:id

Restore Project

POST /api/projects/:id/restore

Permanently Delete Project

DELETE /api/projects/:id/permanent

Get Recycle Bin

GET /api/recycle-bin

Session Reassignment

Move Session to Project

POST /claude/api/claude/sessions/:id/move
Content-Type: application/json

{
  "projectId": 1
}

Get Project Suggestions for Session

GET /api/projects/suggestions?sessionId=session-123

WebSocket

Connect to Session

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

# 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

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

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

# 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

# Verify claude is in PATH
which claude

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

Database errors

# 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/
• Gitea Repository: https://github.rommark.dev/admin/ClaudeCLI-Web
• Issue Tracker: https://github.rommark.dev/admin/ClaudeCLI-Web/issues
• Claude Code Docs: https://docs.anthropic.com/claude-code