AI-Assisted
Code Editor

1.1 What is XteVision Coder?

XteVision Coder is an AI-assisted code editor and web-based IDE designed for developers who want to build, edit, and manage projects with integrated AI support. It provides a professional three-panel workstation layout with file exploration, code editing, AI chat, live preview, and terminal access—all running locally with support for various AI models.

1.2 Key Capabilities

• Multi-root workspace management with drag-and-drop file operations
• Professional code editing powered by Monaco Editor (same engine as VS Code)
• AI-assisted coding with streaming responses and autonomous agent mode
• Persistent authenticated sessions with standalone login/register and PostgreSQL-backed session storage
• Saved AI conversations with titles, rename/search/bookmark controls, and automatic last-session restore
• Workspace state recovery restoring the active workspace root, open tabs, active tab, and unsaved editor buffers
• Live preview for HTML/CSS/JS projects with sandboxed iframe rendering
• Integrated terminal with command allowlist for safe execution
• Multi-model support for MLX, Ollama, LMStudio, GitHub Copilot, and OpenRouter
• Smart code merging with diff-based edit application and visual diff preview

1.3 Target Users

• Developers working with local AI models
• Teams needing a lightweight, self-hosted IDE
• Educators teaching programming with AI assistance
• Anyone wanting a VS Code-like experience in the browser

2.1 High-Level Architecture

┌──────────────────────────────────────────────────────────┐
│                      Browser (Client)                     │
│  ┌────────────────────────────────────────────────────┐  │
│  │               Frontend (Vanilla JS)                 │  │
│  │  ┌────────┐ ┌────────┐ ┌──────┐ ┌────────┐       │  │
│  │  │ File   │ │ Monaco │ │  AI  │ │ Live   │       │  │
│  │  │Explorer│ │ Editor │ │ Chat │ │Preview │       │  │
│  │  └────────┘ └────────┘ └──────┘ └────────┘       │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────┬───────────────────────────────────┘
                       │ HTTP/REST API (localhost:5004)
┌──────────────────────┴───────────────────────────────────┐
│                  Python Backend Server                    │
│  ┌──────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌──────────┐ │
│  │ File I/O │ │ Shell  │ │AI Proxy│ │Workspace │ │Auth/Chat │ │
│  └──────────┘ └────────┘ └────────┘ └──────────┘ └──────────┘ │
└──────────────────────┬───────────────────────────────────┘
         ┌───────────┬───────────┬───────────┐
         │           │           │           │
     ┌─────▼──────┐ ┌──▼────────┐ ┌▼──────────┐
     │  File      │ │PostgreSQL │ │ AI Model  │
     │  System    │ │ users +   │ │  Server   │
     │            │ │ sessions  │ │           │
     └────────────┘ └───────────┘ └───────────┘

2.2 Communication Flow

1. Frontend → Backend: RESTful HTTP requests for file operations, shell commands, and AI proxying
2. Backend → AI Model: OpenAI-compatible API calls to local or remote model servers
3. Backend → Frontend: JSON responses with file contents, execution results, or streaming AI responses via SSE
4. Frontend → User: UI updates, editor changes, chat responses, and terminal output

2.3 Deployment Model

XteVision Coder is designed for local-first development:

• Runs entirely on the user's machine
• No cloud dependencies (except optional AI model proxies)
• Backend serves static frontend files
• All data stays on the local filesystem

4.1 Prerequisites

• Python 3.8+ (for backend server)
• Modern browser (Chrome/Edge recommended)
• AI model server (optional, for AI features)

4.2 Installation Steps

Step 1: Download

cd /path/to/mlx_coder

Step 2: Install Monaco Editor (Optional)

bash download-monaco.sh

Step 3: Configure AI Server (Optional)

mlx_lm.server --model <your-model-path> --port 5010

Step 4: Install Python Dependencies

pip3 install -r requirements.txt

Step 5: Start XteVision Coder

# Default configuration
python3 server.py

# Custom port
PORT=8080 python3 server.py

# With PostgreSQL-backed authentication
XTEVISION_DB_HOST=192.168.1.4 \
XTEVISION_DB_PORT=5432 \
XTEVISION_DB_NAME=codebase \
XTEVISION_DB_USER=postgres \
XTEVISION_DB_PASSWORD=your-db-password \
python3 server.py

Step 6: Access the Application

http://localhost:5004

4.3 First-Time Setup

1. Create Account: Use the login/register overlay to create the first standalone Coder user
2. Open Workspace: Click "Open Folder" to select a project directory
3. Configure AI: Open Settings (gear icon) and save your preferred AI backend
4. Start a Session: Use the Sessions toolbar to create, name, and bookmark persistent AI conversations

4.4 Authentication Setup

XteVision Coder now uses cookie-based standalone authentication backed by PostgreSQL. Each user sees only their own saved chat sessions and workspace restoration data.

• XTEVISION_AUTH_COOKIE_NAME: session cookie name, default xtevision_session
• XTEVISION_AUTH_SESSION_DAYS: cookie lifetime in days, default 14
• XTEVISION_AUTH_ALLOW_REGISTRATION: enable/disable local sign-up
• XTEVISION_PRODIGY_SHARED_SECRET: optional shared secret for future trusted Prodigy launch handoff

4.5 OpenRouter Setup

To use OpenRouter as the AI backend:

1. Open Settings from the right sidebar
2. Select OpenRouter in the AI Server dropdown
3. Set the API URL to https://openrouter.ai/api/v1/chat/completions
4. Choose an OpenRouter model ID such as qwen/qwen3.6-plus-preview
5. Paste your API key into OpenRouter API Key
6. Optionally set HTTP Referer and X-OpenRouter-Title

When OpenRouter is selected, XteVision Coder attaches these headers:

• Authorization: Bearer <OPENROUTER_API_KEY>
• HTTP-Referer: <configured site URL>
• X-OpenRouter-Title: <configured site title>

5.1 Directory Layout

mlx_coder/
├── index.html                      # Main HTML entry point
├── style.css                       # Application styles
├── script.js                       # Bootstrap and module loader
├── server.py                       # Python HTTP backend
├── .mlx.json                       # Project state
├── js/
│   ├── modules/                    # Frontend ES6 modules
│   │   ├── state.js                # Global state management
│   │   ├── config.js               # AI configuration and provider-specific settings
│   │   ├── utils.js                # Utility functions
│   │   ├── filesystem.js           # File I/O and workspace
│   │   ├── editor.js               # Monaco Editor initialization
│   │   ├── chat.js                 # AI chat and streaming
│   │   ├── agent.js                # Agent loop and function calling
│   │   ├── auth.js                 # Login/register/logout bootstrap
│   │   ├── sessionPersistence.js   # Chat session autosave and restore
│   │   ├── tools.js                # Tool definitions
│   │   ├── diff.js                 # Diff-based editing
│   │   ├── preview.js              # Live preview and PDF export
│   │   └── ui.js                   # UI rendering and interactions
│   ├── marked.min.js               # Markdown parser
│   ├── prism.min.js                # Syntax highlighter
│   └── html2pdf.bundle.min.js      # PDF generation
├── fontawesome-free-web/           # FontAwesome icons
├── requirements.txt                # Python auth/database dependencies
├── projects/                       # User project files
└── logs/app.log                    # Application log

5.2 State Management

export const state = {
    editor: null,               // Monaco Editor instance
    files: {},                  // File content cache
    openTabs: [],               // Open editor tabs
    activeTabPath: null,        // Active tab path array
    tabDirty: {},               // Dirty state per tab path
    messageHistory: [],         // Active chat message history
    chatSessionId: null,        // Current saved chat session id
    chatSessions: [],           // Available saved chat sessions
    workspaceFolders: new Map() // Open workspace folders
};

Agent Mode Details

7.1 Core Modules

7.2 Event System

// Custom event for settings changes
window.dispatchEvent(new CustomEvent('xtevision-settings-changed'));

// Listen for events
window.addEventListener('xtevision-settings-changed', () => {
  // React to settings change
});

7.3 Error Handling

// Global error boundaries for async init
try {
  await checkServerAvailability();
  await connectToServerWorkspace();
} catch (error) {
  logToTerminal(`Init error: ${error.message}`, 'error');
}

8.1 Server Configuration

PORT = int(os.environ.get('PORT', 5004))
PROJECTS_DIR = os.path.join(os.getcwd(), 'projects')
AI_PROXY_TIMEOUT_SEC = 3660
AUTH_COOKIE_NAME = os.environ.get('XTEVISION_AUTH_COOKIE_NAME', 'xtevision_session')
AUTH_DB_HOST = os.environ.get('XTEVISION_DB_HOST', '192.168.1.4')
AUTH_DB_NAME = os.environ.get('XTEVISION_DB_NAME', 'codebase')
PRODIGY_JWT_SECRET = os.environ.get('XTEVISION_PRODIGY_SHARED_SECRET', '')

8.2 Thread Safety

_current_dir_lock = threading.Lock()
_current_dir = os.getcwd()

def get_current_dir():
    with _current_dir_lock:
        return _current_dir

8.3 Auth and Session Storage

The backend initializes a coder PostgreSQL schema containing:

• users for local and future Prodigy-linked identities
• auth_sessions for secure session-cookie login state
• auth_launch_tokens for one-time signed launch handoffs
• chat_sessions for saved chats, titles, bookmarks, and UI restore payloads

8.4 Request Handler

class CustomHandler(http.server.SimpleHTTPRequestHandler):
    def do_GET(self): # Handle GET
    def do_POST(self): # Handle POST
    def do_OPTIONS(self): # CORS preflight
    def end_headers(self): # Add CORS headers

8.5 AI Proxy Behavior

The backend exposes two AI-related proxy endpoints:

• /api/proxy for lightweight JSON fetches such as model discovery
• /api/ai-proxy for full request forwarding to OpenAI-compatible chat endpoints

For OpenRouter, both endpoints forward provider headers and permit openrouter.ai in the proxy allowlist so authenticated model discovery and chat completions work through the backend fallback path.

9.1 Supported AI Servers

9.2 OpenAI-Compatible Protocol

Endpoint: /v1/chat/completions

{
  "model": "your-model-name",
  "messages": [
    {"role": "system", "content": "You are a coding assistant..."},
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true,
  "tools": [{"type":"function","function":{"name":"read_file","parameters":{"file_path":"string"}}}]
}

9.3 Streaming Response Format

Server-Sent Events (SSE):

data: {"choices": [{"delta": {"content": "Hello"}}]}
data: {"choices": [{"delta": {"content": "!"}}]}
data: [DONE]

9.4 Function Calling

Tool Call Parsing (3 formats):

1. Gemma-style: call:read_file{"file_path": "test.js"}
2. Structured JSON: {"name": "read_file", "arguments": {...}}
3. Tagged format: