vector-rag-gui
A Qt6 GUI for searching local FAISS vector stores with AI-powered research synthesis. Built as a custom agent using the Claude Code Agent SDK.
Architecture
This application is built on the Claude Code Agent SDK framework, providing an agentic research assistant with access to multiple tools.
Dependencies
Agent Tools
The agent has access to 6 tools using the Claude Agent SDK @tool decorator:
| Tool | Description |
|---|
search_local_knowledge | Search local FAISS vector stores |
search_aws_docs | Search AWS documentation |
search_web | Search the web with Google Search grounding |
glob_files | Find files matching glob patterns |
grep_files | Search for regex patterns in files |
read_file | Read contents of a specific file |
Custom Prompts
The agent supports custom system prompts for specialized use cases:
- Research Prompt: Default prompt for multi-source research synthesis
- Obsidian Knowledge Prompt: Template for querying Obsidian vaults with wiki-link following and daily notes support
The Obsidian prompt instructs the agent to:
- Use RAG to find relevant notes
- Read full files (not just snippets)
- Follow
[[wiki links]] using glob + read
- Search daily notes for date-related queries
Features
- Qt6 desktop GUI with GitHub-flavored markdown rendering
- Research mode with multi-source synthesis (local RAG, AWS docs, web search)
- Read-only file tools (glob, grep, read) for codebase exploration
- Multi-store selection for comprehensive local searches
- Real-time progress with token usage and cost tracking
- Dark/Light mode toggle
- System tray integration
- Built-in REST API server (starts automatically with GUI)
- Persistent settings (window position, selected stores, tools, model)
Installation
Requires Python 3.14+, uv, and vector-rag-tool.
git clone https://github.com/dnvriend/vector-rag-gui.git
cd vector-rag-gui
uv tool install .
Configuration
AWS Bedrock credentials via environment variables:
export AWS_PROFILE="your-profile"
export AWS_REGION="us-east-1"
# Optional: Override model inference profiles
export ANTHROPIC_DEFAULT_SONNET_MODEL="arn:aws:bedrock:..."
export ANTHROPIC_DEFAULT_OPUS_MODEL="arn:aws:bedrock:..."
export ANTHROPIC_DEFAULT_HAIKU_MODEL="arn:aws:bedrock:..."
Usage
# Launch GUI (REST API starts automatically)
vector-rag-gui
# Launch with custom API port
vector-rag-gui --port 9000
# Launch with specific store pre-selected
vector-rag-gui start --store my-knowledge-base
# List available stores
vector-rag-gui stores
vector-rag-gui stores --json
# Show configuration
vector-rag-gui config
# Verbose output
vector-rag-gui -v # INFO
vector-rag-gui -vv # DEBUG
vector-rag-gui -vvv # TRACE
On startup, a banner displays the API endpoints:
╭─────────────────────────────────────────╮
│ Vector RAG GUI v0.1.0 │
├─────────────────────────────────────────┤
│ REST API: http://127.0.0.1:8000 │
│ Swagger: http://127.0.0.1:8000/docs │
╰─────────────────────────────────────────╯
Options
| Option | Description |
|---|
-p, --port | REST API port (default: from settings or 8000) |
-v, --verbose | Increase verbosity (repeatable) |
-h, --help | Show help message |
--version | Show version |
Commands
| Command | Description |
|---|
start | Launch GUI (default) |
serve | Start REST API server |
stores | List available vector stores |
config | Show current configuration |
completion | Generate shell completion script |
REST API
Start the API server for programmatic access:
vector-rag-gui serve # Default: localhost:8000
vector-rag-gui serve --host 0.0.0.0 --port 8080
vector-rag-gui serve --reload # Development mode
Endpoints
