# 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) --- ## 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 import React from 'react'; export default function Header() { return

My App

; } export default function App() { return
Old Content
; } export default function App() { return
New Content
; } npm run dev npm install @tanstack/react-query ``` 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 # 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//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 ``` ():