LOQ-J — Local-Only Java CLI for RAG

Fast, private, citation-backed answers grounded in your current directory.

• Java 21, Lucene 10.x, JLine REPL, Jackson
• Local LLMs via Ollama (e.g., qwen3:8b)
• Embeddings via bge-m3 (vectors default off in config)
• Modes: ask | rag | rag+memory | dev | web | auto

---

Installation

Option 1: Easy Install (Recommended)

Windows:

# Build the distribution
./gradlew clean installDist

# Install to PATH
pwsh tools/install-windows.ps1

# Open new terminal and verify
loqj --version

Linux/macOS:

# Build the distribution
./gradlew clean installDist

# Install to PATH (user-local)
bash tools/install-unix.sh

# Or install system-wide (requires sudo)
bash tools/install-unix.sh --sudo

# Open new terminal and verify
loqj --version

Option 2: Manual Usage

# Build & run from project directory
./gradlew clean installDist

# Windows PowerShell
./build/install/loqj/bin/loqj.bat --version

# Linux/macOS
./build/install/loqj/bin/loqj --version

---

Quick Start

# Start interactive REPL (shows logo and workspace info)
loqj

# Start without banner (for scripts)
loqj run --no-logo

# Check version and system info
loqj --version
loqj version

# Check current workspace status
loqj status
loqj status --verbose

# Index your current project
loqj rag-index

# Ask questions about your code
loqj rag-ask "How does the authentication system work?"

# Work with specific directories
loqj rag-index --root /path/to/project
loqj rag-ask --root /path/to/project "What are the main components?"

---

Interactive Mode

When you run loqj (or loqj run), you enter an interactive REPL with:

• Dynamic prompt: loqj@rag_ > (updates when you change modes)
• ASCII banner: Shows on startup (skip with --no-logo)
• Mode switching: :mode ask|rag|dev|auto with live prompt updates
• Workspace awareness: Each directory maintains separate indices

REPL Commands

:help                 show available commands
:version              show version information  
:mode rag             switch to RAG mode (project-aware)
:mode ask             switch to general Q&A mode
:mode auto            smart mode selection
:status               show workspace and configuration
:status --verbose     detailed system information
:k 10                 set retrieval top-K
:debug on             show retrieved chunks
:models               list available LLM models
:set model qwen3:8b   switch active model
:reindex              rebuild current workspace index
:memory clear         clear conversation history
:q                    quit

---

Multi-Workspace Usage

LOQ-J keeps each project's data completely separate:

# Work with web project
loqj rag-index --root ~/projects/webapp
loqj rag-ask --root ~/projects/webapp "What APIs are exposed?"

# Switch to mobile project (separate context)
loqj rag-index --root ~/projects/mobile-app  
loqj rag-ask --root ~/projects/mobile-app "How is data stored locally?"

# Set default workspace via environment
export LOQJ_WORKSPACE=~/projects/webapp
loqj status    # Now uses webapp by default

See docs/multi-workspace.md for detailed examples.

---

Configuration

LOQ-J uses these settings in priority order:

1. Command-line flags (--root, --k, etc.)
2. Environment variables
3. Config files
4. Built-in defaults

Environment Variables

# Default workspace (avoids typing --root every time)
export LOQJ_WORKSPACE=/path/to/your/project

# Ollama connection
export LOQJ_OLLAMA_HOST=http://127.0.0.1:11434
export LOQJ_OLLAMA_MODEL=qwen2.5:7b

# Then just run:
loqj status
loqj rag-ask "What does this project do?"

---

Requirements

• Java 21+ (for Vector API support)
• Ollama running locally with a model (e.g., ollama pull qwen2.5:7b)
• 4GB+ RAM recommended for indexing large codebases

---

Features

✅ First-class CLI experience - loqj from anywhere after install
✅ Interactive REPL - Dynamic prompts that show current mode
✅ Multi-workspace - Each project gets isolated indices and context
✅ Version management - loqj -v, --version, version subcommand
✅ Offline-first - No cloud dependencies or data sharing
✅ Fast indexing - Lucene 10 with optional vector embeddings
✅ Citation-backed - Every answer includes relevant file references
✅ Mode flexibility - Ask, RAG, dev, web, and auto modes

---

Troubleshooting

"Command not found" errors:

• Windows PowerShell: Use .\loqj.bat (dot-slash prefix required)
• After installation: Open new terminal window to reload PATH

Ollama connection issues:

# Check if Ollama is running
curl http://127.0.0.1:11434/api/version

# Test with LOQ-J
loqj status --verbose

Empty or slow indices:

# See what files were found
loqj status --verbose

# Force complete reindex
loqj rag-index --full

# Use faster BM25-only mode
loqj run --bm25-only

See docs/multi-workspace.md for more detailed troubleshooting.