diff --git a/README.md b/README.md new file mode 100644 index 00000000..087d1a3c --- /dev/null +++ b/README.md @@ -0,0 +1,643 @@ +# 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 + +``` +(): + + + +