<div align="center">

# {{FULL_PRODUCT_NAME}}

**{{TAGLINE}}**

[![npm version](https://img.shields.io/npm/v/{{NPM_PACKAGE}}.svg?style=flat-square)](https://www.npmjs.com/package/{{NPM_PACKAGE}})
[![Node.js Version](https://img.shields.io/node/v/{{NPM_PACKAGE}}.svg?style=flat-square)](https://nodejs.org)
[![License: Commercial](https://img.shields.io/badge/License-Commercial-blue.svg?style=flat-square)](./LICENSE)

**[Quick Start](#-quick-start)** | **[Features](#-features)** | **[Documentation](#-documentation)** | **[Tools](#-ai-powered-tools)** | **[Web UI](#-web-interface)**

</div>

---

## What is {{FULL_PRODUCT_NAME}}?

{{FULL_PRODUCT_NAME}} is a **production-ready autonomous AI agent system** that empowers developers with intelligent coding assistance. It combines the power of multiple AI models with a comprehensive toolkit for software development, code analysis, and automation.

### Why {{PRODUCT_NAME}}?

- **Multi-Agent Orchestration** - Run multiple AI agents simultaneously with isolated workspaces
- **Rich Tool Ecosystem** - 18+ specialized tools for development, analysis, and automation
- **Dual Interface** - Modern Web UI + powerful CLI for any workflow
- **Real-Time Monitoring** - Track agent activity, costs, and performance
- **Persistent State** - Resume conversations and continue work across sessions
- **Secure by Design** - Agent isolation, resource limits, and security scanning

---

## Features

### Core Capabilities

<table>
<tr>
<td width="50%">

#### Intelligent Agent System
- Multi-agent conversation orchestration
- Automatic model selection and routing
- Task-based agent specialization
- Inter-agent communication
- Background task management

</td>
<td width="50%">

#### Professional Tooling
- Terminal command execution
- File system operations
- Web browsing and scraping
- Image generation (DALL-E, Flux)
- Code analysis and refactoring

</td>
</tr>
<tr>
<td width="50%">

#### Development Features
- Import/export analysis
- Dependency resolution
- Static code analysis
- Clone detection
- Security scanning

</td>
<td width="50%">

#### Smart Assistance
- Context-aware responses
- File attachments in chat
- Conversation compaction
- Task management
- Progress tracking

</td>
</tr>
</table>

---

## Quick Start

### 1. Create an Account

Register at **[{{DOMAIN}}](https://{{DOMAIN}})** to get started.

### 2. Install the Package

```bash
{{INSTALL_COMMAND}}
```

### 3. Verify Installation

```bash
{{CLI_COMMAND}} --version
```

### 4. Create an API Key

1. Sign in at [{{DOMAIN}}](https://{{DOMAIN}})
2. Navigate to [API Keys](https://{{DOMAIN}}/api-keys)
3. Create a new API key and copy it

### 5. Launch & Configure

#### Option A: Web UI
```bash
{{CLI_COMMAND}} web
```
This starts the server and opens the Web UI in your browser. Go to **Settings** and paste your API key.

#### Option B: Terminal UI
```bash
{{CLI_COMMAND}} plus-terminal
```
This starts the server + Terminal UI. Press `Ctrl+,` to open Settings, paste your API key. Press `Alt+H` for help.

### 6. Start Using {{PRODUCT_NAME}}

1. **Create an agent** using the interface
2. **Send a message** to start interacting
3. **Enjoy** autonomous AI assistance!

### CLI Reference

```bash
{{CLI_COMMAND}} web             # Start server + open Web UI in browser
{{CLI_COMMAND}} terminal        # Start Terminal UI (server must be running)
{{CLI_COMMAND}} plus-terminal   # Start server + Terminal UI together
{{CLI_COMMAND}} plus-web        # Alias for 'web'
{{CLI_COMMAND}} --port 3000     # Use custom port (works with any command)
{{CLI_COMMAND}} --version       # Show version
{{CLI_COMMAND}} --help          # Show all options
```

---

## Web Interface

The modern Web UI provides an intuitive interface for managing agents and conversations:

### Key Features

- **Chat Interface** - Clean, responsive chat with markdown support
- **File Attachments** - Drag and drop files into conversations
- **Agent Management** - Create, switch, and manage multiple agents
- **Real-Time Updates** - Live agent status and output streaming
- **Model Selection** - Switch between AI models on the fly
- **Task Tracking** - Visual task lists with progress indicators
- **Search & Filter** - Find conversations and messages quickly
- **Modern UI** - Built with React, TailwindCSS, and WebSockets

---

## AI-Powered Tools

{{PRODUCT_NAME}} comes with 18+ specialized tools that agents can use autonomously:

### Development Tools

| Tool | Description | Key Features |
|------|-------------|--------------|
| **Terminal** | Execute shell commands | Background processes, stdin input, prompt detection |
| **File System** | File operations | Create, read, update, delete files and directories |
| **Browser** | Web automation | Headless browsing, screenshots, scraping with Puppeteer |
| **Seek** | Code search | Pattern matching, multi-directory support |
| **File Tree** | Directory visualization | Tree structure generation, filtering |

### Analysis Tools

| Tool | Description | Key Features |
|------|-------------|--------------|
| **Import Analyzer** | Import/export analysis | ES6, CommonJS, circular dependencies, unused exports |
| **Dependency Resolver** | Dependency management | Semantic versioning, conflict detection, upgrade paths |
| **Static Analysis** | Code quality | ESLint, Prettier, TypeScript, Stylelint integration |
| **Clone Detection** | Code duplication | AST-based analysis, similarity scoring |
| **Security Scanner** | Security audits | npm audit, dependency vulnerabilities, deployment checks |

### AI & Automation Tools

| Tool | Description | Key Features |
|------|-------------|--------------|
| **Image Generator** | AI image creation | Flux Pro support, high-quality outputs |
| **Video Generator** | AI video creation | Azure OpenAI Sora integration, async processing |
| **Task Manager** | Task tracking | Todo lists, progress tracking, agent synchronization |
| **Web Tool** | HTTP requests | GET, POST, API testing, webhook debugging |
| **File Content Replace** | Bulk replacements | Pattern-based, multi-file, preview changes |
| **Agent Communication** | Inter-agent messaging | Task delegation, collaborative workflows |

### System Tools

| Tool | Description | Key Features |
|------|-------------|--------------|
| **Agent Delay** | Pause agent execution | Timed delays, background operation support |
| **Job Done** | Task completion | Mark autonomous work complete, exit to chat mode |
| **Async Tool Manager** | Background task handling | Long-running operations, status tracking |
| **Loop Detection** | Repetition prevention | Sliding window analysis, automatic termination |

---

## System Requirements

- **Node.js**: >= 20.0.0 (20.x LTS recommended)
- **npm**: >= 7.0.0
- **Operating System**: Windows, macOS (Intel & Apple Silicon), Linux
- **Memory**: 2GB minimum, 4GB+ recommended
- **Disk Space**: 500MB for package and dependencies
- **Shell**: bash, zsh (macOS default), PowerShell, cmd

---

## Architecture

### High-Level Overview

```
+--------------------------------------------------+
|               Client Interfaces                  |
|  +-------------+  +-------------------------+   |
|  |   Web UI    |  |     CLI Interface       |   |
|  |  (React)    |  |  (Interactive Shell)    |   |
|  +-------------+  +-------------------------+   |
+------------------------+-------------------------+
                         | WebSocket / IPC
           +-------------v--------------+
           |   Orchestrator Service     |
           |  (Request Coordination)    |
           +---------+--------+--------+
                     |        |
          +----------v--+  +--v--------------+
          | Agent Pool  |  |  AI Service     |
          | - Lifecycle |  |  - Model Router |
          | - Scheduling|  |  - Backend API  |
          +------+------+  +-----------------+
                 |
          +------v--------------------------+
          |   Message Processor             |
          |   - Tool Registry               |
          |   - Command Extraction          |
          |   - Execution Engine            |
          +----------------------------------+
```

---

## Security & Privacy

### Built-In Security Features

- **Agent Isolation** - Each agent has isolated workspace and permissions
- **Resource Limits** - Prevents resource exhaustion (CPU, memory, commands)
- **Path Validation** - Prevents directory traversal attacks
- **Command Sanitization** - Protects against command injection
- **Security Scanning** - Built-in vulnerability detection
- **Audit Logging** - Comprehensive activity logs

### Privacy

- **Authentication Only** - Only credential verification communicates with servers
- **Local-First** - All work data stays on your machine
- **No Usage Telemetry** - No tracking or analytics of your work
- **State Control** - Full control over conversation history
- **Easy Cleanup** - Delete state directory to remove all local data

---

## License

**Commercial License** - see [LICENSE](./LICENSE) file for complete terms.

- **Authentication Required** - Valid subscription or license needed to use
- **Commercial Use** - Use in your own projects and services (with active subscription)
- **No Free Use** - Requires active subscription or valid license
- **No Redistribution** - Cannot resell, redistribute, or sublicense

**Copyright (c) 2025-2026 {{LEGAL_COMPANY}}. All rights reserved.**

---

## Support

- **Documentation**: Check the [docs](./docs/) directory
- **Email**: {{CONTACT_EMAIL}}

### Troubleshooting

**Web UI won't start?**
```bash
# Check if port is in use
lsof -i :8080

# Use a different port
{{CLI_COMMAND}} --port 3000
```

**Agent not responding?**
```bash
# Check logs
cat .loxia-state/logs/system.log

# Restart with debug logging
LOXIA_LOG_LEVEL=debug {{CLI_COMMAND}}
```

**Installation issues?**
```bash
# Clear npm cache
npm cache clean --force

# Reinstall
{{INSTALL_COMMAND}} --force
```

**macOS Installation**

On macOS, configure npm to use a user-writable directory:
```bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
{{INSTALL_COMMAND}}
```

---

<div align="center">

**Made with care by the {{LEGAL_COMPANY}} team**

[Website](https://{{WEBSITE}})

</div>
