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
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
# 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
# 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?"
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|autowith live prompt updates - Workspace awareness: Each directory maintains separate indices
: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
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.
LOQ-J uses these settings in priority order:
- Command-line flags (
--root,--k, etc.) - Environment variables
- Config files
- Built-in defaults
# 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?"
- 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
✅ 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
"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.