docs: add comprehensive README for Claude Code Web Interface
Add complete README.md with: - Feature overview and highlights - Quick start guide (3-minute setup) - Installation instructions (systemd, PM2) - Configuration guide - Complete usage guide (sessions, projects, terminal, XML tags) - Full API reference with examples - Development guide with project structure - Database schema documentation - Troubleshooting section - Contributing guidelines - License and acknowledgments Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
uroma
643
README.md
Normal file
643
README.md
Normal file
@@ -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.
|
||||
|
||||
[](https://nodejs.org/)
|
||||
[](https://expressjs.com/)
|
||||
[](https://www.sqlite.org/)
|
||||
[](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
|
||||
<!-- 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)
|
||||
Reference in New Issue
Block a user