npm package: @nhatvu148/vexar-cli
Description: Agentic AI coding assistant that plans, executes, and iterates autonomously to complete complex tasks
Author: Vexar Team
Latest version: 0.11.1

# Vexar

> **Agentic AI coding assistant** that plans, executes, and iterates autonomously to complete complex tasks.

[![Version](https://img.shields.io/badge/version-0.11.0-blue.svg)](https://github.com/nhatvu148/vexar/releases/tag/v0.11.0)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.85+-orange.svg)](https://www.rust-lang.org)
[![Edition](https://img.shields.io/badge/edition-2024-blue.svg)](https://doc.rust-lang.org/edition-guide/rust-2024/index.html)

**Not just a chatbot** - Vexar autonomously executes multi-step workflows, understands your entire codebase through semantic search, and takes real actions verified by 4-layer anti-hallucination checks.

**Built with Rust. ~10MB desktop bundle vs 200MB+ Electron apps.**

## Why Vexar? Truly Agentic AI

**Most AI coding tools just suggest** - Vexar **autonomously executes**.

### 🤖 Agentic Multi-Step Execution

Unlike ChatGPT or Copilot that only suggest code, Vexar:

- **Plans** complex tasks across multiple files
- **Executes** each step autonomously (read → analyze → edit → test)
- **Iterates** up to 10+ tool calls per task
- **Adapts** based on results and errors
- **Spawns sub-agents** for parallel complex workflows

**Example:** "Refactor authentication to use JWT"
```
→ Searches codebase for auth patterns (SemanticSearch)
→ Reads current auth implementation (Read)
→ Analyzes dependencies and imports (Grep)
→ Creates JWT utility module (Write)
→ Updates auth middleware (Edit)
→ Modifies login/logout endpoints (Edit)
→ Updates tests (Edit)
→ Runs test suite (Bash)
→ Fixes any failures (Edit + Bash loop)
→ Commits changes (Git)
```

All autonomous. All verified. No fake suggestions.

### 🧠 Semantic Codebase Understanding

- Vector embeddings of your entire codebase (sqlite-vec, 10-100x faster)
- Understands architecture, not just syntax
- Answers "how does X work?" by searching semantically
- Context-aware suggestions based on your patterns

### 🎯 Anti-Hallucination System

4-layer verification ensures **real execution**:
1. ✅ Tool calls are actually executed (not simulated)
2. ✅ File operations are verified to succeed
3. ✅ Command outputs are captured and analyzed
4. ✅ Results are checked before proceeding

**No fake file reads. No imaginary test results. Real actions only.**

### 🔄 vs Other Tools

| Capability | Vexar | ChatGPT | Copilot | Cursor |
|------------|-------|---------|---------|--------|
| **Autonomous multi-step tasks** | ✅ Yes | ❌ No | ❌ No | ⚠️ Limited |
| **Real tool execution** | ✅ Verified | ❌ Suggests only | ❌ Suggests only | ✅ Yes |
| **Sub-agent spawning** | ✅ Yes | ❌ No | ❌ No | ❌ No |
| **Semantic codebase search** | ✅ Yes (fast) | ❌ No | ⚠️ Basic | ⚠️ Basic |
| **Configurable iterations** | ✅ 1-20+ | ❌ N/A | ❌ N/A | ⚠️ Fixed |
| **Shell command execution** | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
| **Vision/image analysis** | ✅ Yes | ✅ Yes | ❌ No | ⚠️ Limited |
| **Local/offline mode** | ✅ Ollama | ❌ No | ❌ No | ❌ No |

**Vexar = Claude Code + Devin + semantic search, but faster and lighter.**

### 🖥️ Desktop GUI + CLI

- Native Tauri desktop app (~10MB vs Electron's 200MB+)
- Powerful terminal interface for scripting
- Both use the same Rust core (90% code reuse)

### 🌐 Multi-Provider

OpenAI, Ollama (100% offline), Moonshot, ZhipuAI

### 🔧 Extensible

MCP & LSP integration for unlimited tool capabilities

## Features

### Core Capabilities

- **Semantic Indexing** - Vector search over your codebase with sqlite-vec (10-100x faster)
- **Agentic Tool Loop** - Multi-step task execution with configurable iterations
- **Session Persistence** - Save and resume conversations with full context
- **Streaming Responses** - Real-time token streaming with visual feedback
- **Vision/Multimodal** - Analyze images, screenshots, and diagrams
- **File Attachments** - Drag & drop or click to attach files (CLI & Desktop)
- **Code Execution** - Run JavaScript/TypeScript directly in desktop app

### Desktop App Features

- 🎨 **Modern UI** - Svelte 5 + TailwindCSS, VS Code-inspired dark theme
- 📁 **Session Management** - Sidebar with search, pagination, auto-titles
- 🔍 **In-Chat Search** - Cmd+F with highlighting and navigation
- 📤 **Export** - Save conversations as Markdown or JSON
- ⚡ **Streaming** - ChatGPT-style gradient streaming effect
- 🗂️ **Project Selector** - Switch working directories from UI
- 📊 **Index Management** - Build/search/stats with progress UI
- ⌨️ **Keyboard Shortcuts** - Cmd+N (new), Cmd+K (search), Cmd+, (settings)
- 🔄 **Resizable Sidebar** - Drag to customize layout
- 📱 **Native Feel** - macOS overlay title bar, toast notifications

### CLI Features

- 📝 **Native Text Selection** - Copy/paste works naturally (no special modes)
- 🎨 **Markdown Rendering** - Syntax highlighting, code blocks, links
- 💬 **Interactive Mode** - Tab autocomplete, command history
- 📋 **Clipboard** - Ctrl+Y to copy last AI response
- 🔄 **Slash Commands** - `/new`, `/clear`, `/help`, `/index`
- ⚡ **Shell Commands** - Execute shell commands with `!` prefix (e.g., `!ls`, `!git status`)
- 📊 **Session Management** - Save, resume, list, and search sessions
- 🎯 **Clean UI** - Responsive banner, improved scroll, no artifacts

### Tool System

| Tool | Description |
|------|-------------|
| **Read** | Read file contents with syntax awareness |
| **Write** | Create new files with proper formatting |
| **Edit** | Modify files with intelligent find/replace |
| **Bash** | Execute shell commands safely |
| **Glob** | Find files by pattern (fast) |
| **Grep** | Search file contents with regex |
| **Git** | Git operations (status, diff, commit, etc.) |
| **WebFetch** | Fetch and analyze web content |
| **Task** | Spawn sub-agents for complex tasks |
| **SemanticSearch** | Search codebase semantically with embeddings |

**Plus MCP tools** (if configured): web search, browser automation, etc.

## Quick Start

### Desktop App

```bash
cd vexar-desktop
bun install
bun run tauri dev
```

**First run:**
1. Click Settings (⚙️) to configure API key
2. Select provider (OpenAI, Ollama, etc.)
3. Click "Build Index" to enable semantic search
4. Start chatting!

### CLI

```bash
# Interactive mode
cargo run -p vexar-cli

# Single-shot mode
cargo run -p vexar-cli -- chat "analyze this codebase"

# Execute shell commands with ! prefix
# In interactive mode, type: !ls, !git status, !pwd, etc.

# Build semantic index
cargo run -p vexar-cli -- index build

# Search code semantically
cargo run -p vexar-cli -- index search "authentication logic"
```

## Installation

### From Source

```bash
git clone https://github.com/nhatvu148/vexar.git
cd vexar

# Build CLI
cargo build --release -p vexar-cli
./target/release/vexar --help

# Build Desktop
cd vexar-desktop
bun install
bun run tauri build
```

### Binary Releases

Download pre-built binaries from [Releases](https://github.com/nhatvu148/vexar/releases).

## Configuration

### OpenAI (Default)

```bash
export OPENAI_API_KEY=sk-...
```

Or configure in Desktop settings (⚙️).

### Ollama (Local/Offline)

```bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Start server
ollama serve

# Pull a model
ollama pull llama3.2

# Configure Vexar
# Desktop: Settings → Provider → Ollama
# CLI: Set provider to "ollama" in config
```

### Semantic Indexing

```bash
# Build index (CLI)
vexar index build

# Desktop: Click "Build Index" banner when prompted
```

The index uses `.gitignore` rules and excludes common directories (node_modules, target, etc.).

### Agentic Behavior (Advanced)

Configure autonomous execution limits in `.vexar/config.toml`:

```toml
[agent]
max_tool_iterations = 10    # Max autonomous steps per task (1-20)
enable_sub_agents = true     # Allow Task tool to spawn sub-agents
auto_commit = false          # Auto-commit successful changes
confirm_destructive = true   # Ask before rm/drop/delete operations
```

**Higher iterations = more autonomous, but higher API costs.**

## Architecture

```
vexar/
├── vexar-core/         # Shared library (~90% code reuse)
│   ├── API clients (OpenAI, Ollama, Moonshot, ZhipuAI)
│   ├── Tool system (Read, Write, Edit, Bash, etc.)
│   ├── MCP & LSP integration
│   ├── Semantic indexing (embeddings + sqlite-vec)
│   └── Session management
├── vexar-cli/          # Terminal interface
│   ├── Markdown rendering (termimad)
│   ├── Syntax highlighting (syntect)
│   └── Interactive mode with history
└── vexar-desktop/      # Desktop app
    ├── src/            # Svelte 5 frontend
    └── src-tauri/      # Rust backend (uses vexar-core)
```

**Key Benefit:** Bug fixes and features in `vexar-core` automatically work in both CLI and Desktop.

## Agentic Workflows in Action

### 1. Autonomous Feature Implementation

**You:** "Add user authentication with JWT tokens"

**Vexar autonomously:**
```
1. SemanticSearch("authentication patterns in codebase")
   → Finds: src/auth/session.rs (old session-based auth)

2. Read(src/auth/session.rs)
   → Analyzes current implementation

3. Write(src/auth/jwt.rs)
   → Creates JWT utility (encode, decode, validate)

4. Edit(src/auth/middleware.rs)
   → Replaces session checks with JWT verification

5. Edit(src/routes/auth.rs)
   → Updates login to return JWT tokens

6. Edit(src/routes/auth.rs)
   → Updates logout to invalidate tokens

7. Write(tests/auth_jwt_test.rs)
   → Creates comprehensive test suite

8. Bash("cargo test auth")
   → Runs tests, finds 2 failures

9. Edit(src/auth/jwt.rs)
   → Fixes expiration logic

10. Bash("cargo test auth")
    → All tests pass ✓

11. Git("commit -m 'feat: migrate to JWT authentication'")
    → Commits the changes
```

**Total time:** 30 seconds. **Your input:** One sentence.

### 2. Multi-File Refactoring

**You:** "Extract the database logic into a repository pattern"

**Vexar autonomously:**
- Searches for all database queries (SemanticSearch + Grep)
- Creates repository interfaces (Write)
- Implements repositories for each model (Write)
- Updates all existing code to use repositories (Edit × 15 files)
- Runs tests after each change (Bash)
- Fixes broken imports and tests (Edit)
- Commits the refactoring (Git)

### 3. Bug Investigation & Fix

**You:** "Users are reporting timeout errors on the /api/search endpoint"

**Vexar autonomously:**
```
1. Grep("timeout", path="src/routes/search.rs")
   → Finds endpoint implementation

2. Read(src/routes/search.rs)
   → Analyzes query logic

3. SemanticSearch("database query optimization")
   → Finds: indexes are missing on search columns

4. Read(migrations/)
   → Checks current schema

5. Write(migrations/add_search_indexes.sql)
   → Creates index migration

6. Bash("sqlx migrate run")
   → Applies migration

7. Bash("cargo test search_performance")
   → Verifies query speed improved (30s → 200ms)

8. Git("commit -m 'perf: add database indexes for search queries'")
```

### 4. Visual-to-Code (Screenshot → Implementation)

**You:** [Attaches screenshot of UI mockup]
      "Implement this design"

**Vexar autonomously:**
- Analyzes image with Vision API
- Identifies components (navbar, sidebar, cards)
- Searches codebase for similar components (SemanticSearch)
- Creates Svelte components matching the design (Write)
- Adds Tailwind styles based on screenshot (Edit)
- Creates responsive breakpoints (Edit)
- Adds to routing (Edit)
- Shows preview in browser

### 5. Codebase Understanding

**You:** "How does the payment processing work?"

**Vexar autonomously:**
```
1. SemanticSearch("payment processing workflow")
   → Finds: src/payments/stripe.rs, src/webhooks/stripe.rs

2. Read(src/payments/stripe.rs)
   → Reads main payment logic

3. Grep("webhook", type="rs")
   → Finds webhook handlers

4. Read(src/webhooks/stripe.rs)
   → Reads webhook processing

5. Synthesizes architectural explanation with code references
```

**Response includes:** Flow diagram, security notes, error handling analysis, and links to specific files/lines.

### 6. Parallel Task Execution

**You:** "Optimize the entire application for production"

**Vexar spawns sub-agents:**
```
Agent 1: Frontend optimization
  → Minifies assets
  → Enables code splitting
  → Optimizes images

Agent 2: Backend optimization
  → Adds database indexes
  → Enables query caching
  → Optimizes N+1 queries

Agent 3: DevOps
  → Updates Docker config
  → Adds health checks
  → Configures CDN

All running in parallel, coordinated by main agent.
```

## Documentation

- [`CHANGELOG.md`](CHANGELOG.md) - Version history
- [`docs/roadmap.md`](docs/roadmap.md) - Project status and future plans
- [`docs/mcp.md`](docs/mcp.md) - MCP server configuration
- [`docs/architecture/desktop.md`](docs/architecture/desktop.md) - Desktop architecture
- [`CLAUDE.md`](CLAUDE.md) - Quick reference for contributors

## Development

### Build & Test

```bash
# Build everything
cargo build --workspace

# Run tests
cargo test --workspace

# Format & lint
cargo fmt
cargo clippy
```

### Desktop Development

```bash
cd vexar-desktop

# Install dependencies
bun install

# Dev mode (hot reload)
bun run tauri dev

# Production build
bun run tauri build
```

### CLI Development

```bash
# Run CLI in dev mode
cargo run -p vexar-cli -- -i

# Run with logging
RUST_LOG=debug cargo run -p vexar-cli
```

## Tech Stack

**Backend:**
- Rust 1.70+ (tokio, serde, anyhow)
- sqlite-vec for vector search
- syntect for syntax highlighting

**Desktop Frontend:**
- Tauri 2.0 (Rust + System Webview)
- Svelte 5 with runes
- TailwindCSS + shadcn-svelte
- highlight.js, marked (markdown)

**AI/ML:**
- OpenAI API (GPT-4, Vision)
- Ollama (local LLMs)
- Embeddings (text-embedding-3-small)

**Protocols:**
- MCP (Model Context Protocol)
- LSP (Language Server Protocol)

## Roadmap: Towards Fully Autonomous Development

See [`docs/roadmap.md`](docs/roadmap.md) for detailed plans.

**Next: Enhanced Agentic Capabilities**
- **Multi-model routing** - Route simple tasks to cheap models, complex to GPT-4 (save 80% on API costs)
- **Long-running agents** - Background tasks that continue even after closing the app
- **Agent memory** - Learn from past executions to improve future performance
- **Multi-agent collaboration** - Specialized agents (frontend, backend, testing) work together

**Future: Intelligent Code Review**
- **PR/branch review** - Autonomous review with context-aware suggestions
- **Commit analysis** - Detect bugs, security issues, performance problems
- **Pre-commit hooks** - Auto-fix formatting, linting, test failures

**Vision: Screenshot → Fix**
- Attach bug screenshot → Vexar autonomously debugs and fixes
- Diagram → Implementation (flowchart to working code)
- Video walkthrough → Integration tests

**Advanced Refactoring**
- Architecture extraction and visualization
- Automated dependency upgrades
- Performance profiling and optimization
- Security vulnerability patching

## Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Run tests (`cargo test`)
5. Submit a pull request

See [`CLAUDE.md`](CLAUDE.md) for development guidelines.

## License

MIT License - see [LICENSE](LICENSE) file.

## Credits

Built with:
- [Rust](https://www.rust-lang.org/)
- [Tauri](https://tauri.app/)
- [Svelte](https://svelte.dev/)
- [OpenAI](https://openai.com/)
- [Ollama](https://ollama.com/)

---

## Join the Agentic AI Revolution

**Vexar is pioneering the next generation of autonomous coding assistants.** We're building towards a future where AI doesn't just suggest - it plans, executes, and iterates to completion.

**Star ⭐ this repo** if you believe in truly agentic AI!

**Want to contribute?** We're especially interested in:
- Agentic workflow patterns and examples
- Multi-agent coordination strategies
- Performance optimizations for large codebases
- New tool integrations

**Questions? Ideas?** Open an [issue](https://github.com/nhatvu148/vexar/issues) or start a [discussion](https://github.com/nhatvu148/vexar/discussions).

**Follow development:** Watch this repo for updates on autonomous capabilities.