Vizier — Royal Advisor

A 100% local AI agent for computer use, filesystem management, shell access, and general assistance.

Repository: github.com/sonamcgoo-dev/vizier

Vizier runs a GGUF language model on your own machine and gives it hands: it can read and write files, run commands, take screenshots, move the mouse, type on the keyboard, and call tools exposed by Model Context Protocol (MCP) servers. There is no cloud inference, no API key, and no telemetry.

• No cloud / no BYOK / no telemetry — inference is local via llama-cpp-python

• Safe by default — dangerous tools are blocked unless YOLO mode is explicitly enabled

• Hardware-aware — recommends models based on your CPU, RAM, and GPU

• Two front ends — a Qt desktop app and a terminal REPL

• MCP both ways — Vizier can use MCP servers and expose its own tools as an MCP server

• Midnight-palace theme — midnight indigo, antique gold, crimson, and turquoise, with a Rakkas wordmark and intentionally restrained motion

Status: v1.0.0 release candidate (“Royal Advisor”). Core agent, GUI, CLI, MCP client/server, diagnostics, packaging, and a 101-test suite are implemented. Windows builds are unsigned (no code-signing certificate), so SmartScreen may ask for confirmation on first launch. Voice, screen painting, and a plugin marketplace are intentionally out of scope for this release.

Requirements

• Python 3.10+ (tested on 3.13)

• A GGUF model (.gguf) such as Qwen 3, Llama 3.2, Gemma 2, Phi-3, or Mistral

• Optional: Tesseract OCR for ocr_screen / screenshot OCR

• Optional: a GPU with CUDA/Vulkan/Metal support for faster inference

On Windows, install Python from python.org and make sure python is on PATH (or use the full path to python.exe).

Related MCP server: AKIMCP

Install on Windows

The packaged build does not require Python or any developer tools.

1. Download Vizier-Setup-1.0.0-x64.exe from the release page (or build it locally with scripts/build_windows.ps1).

2. Run the installer. It installs per-user by default (no administrator prompt) into %LOCALAPPDATA%\Programs\Vizier, adds Start-menu and optional desktop shortcuts, and includes the GUI, CLI, and MCP server.

3. Launch Vizier, open File → Model Manager…, and download a model sized for your hardware. No account, API key, or internet connection is needed after that first download.

Portable build: extract Vizier-1.0.0-portable-x64.zip anywhere and run Vizier.exe. Settings, models, and sessions still live in %LOCALAPPDATA%\Vizier.

Uninstalling keeps your models and sessions by default and asks before deleting the data directory. The executables are unsigned, so Windows SmartScreen may show “Windows protected your PC”; choose More info → Run anyway if you built or downloaded the release yourself.

Bundled executables:

Quick start from source

# 1. Clone and install from source (full dependency set)
git clone https://github.com/sonamcgoo-dev/vizier.git
cd vizier
python -m pip install -e ".[full]"

# 2. See what your hardware can run
python -m vizier models --recommend

# 3. Download a model (example: Qwen 3 8B, Q4_K_M)
python -m vizier models --download "Qwen/Qwen3-8B-GGUF qwen3-8b-q4_k_m.gguf"

# 4. Launch the desktop app
python -m vizier

# ...or chat in the terminal
python -m vizier chat --model "%LOCALAPPDATA%\Vizier\models\qwen3-8b-q4_k_m.gguf"

If you install the package normally (pip install vizier), the vizier and vizier-mcp-server commands are available directly:

vizier
vizier chat --model path/to/model.gguf
vizier mcp-server --stdio

In the packaged build, use VizierCLI.exe in place of vizier and VizierMCP.exe --stdio for the MCP server. The CLI executable lives next to Vizier.exe in the install directory.

Install only what you need

python -m pip install -e .              # core (requests)
python -m pip install -e ".[gui]"       # + PySide6 desktop app
python -m pip install -e ".[llm]"       # + llama-cpp-python
python -m pip install -e ".[computer]"  # + screenshots, mouse, keyboard, OCR
python -m pip install -e ".[mcp]"       # + MCP client/server (mcp 2.x)
python -m pip install -e ".[dev]"       # + pytest, ruff
python -m pip install -e ".[full]"      # everything above

GPU builds: pip install llama-cpp-python installs a CPU build by default. For CUDA or Vulkan, follow the llama-cpp-python installation guide and set model_n_gpu_layers in your config.

Desktop GUI

Launch with vizier (or python -m vizier). The window has a sidebar with model/tool controls and a chat pane with streamed responses and collapsible-looking tool activity blocks.

• Load a model: File → Load Model… (Ctrl+L) or drag a .gguf file anywhere onto the window

• Model manager: Ctrl+M — hardware recommendations, downloads, and local model list

• Chat: type in the input box and press Enter

• New chat: Ctrl+N — Open session: Ctrl+O — Save session: Ctrl+S — Quit: Ctrl+Q

• Settings: Ctrl+, — context size, GPU layers, sampling, system prompt, YOLO default

• Clear chat: Ctrl+Shift+Delete

• YOLO mode: toggle in the sidebar or View → YOLO Mode

• Tool toggles: uncheck a tool in the sidebar to hide it from the model

• Data folder / logs: View → Open Data Folder; logs are under logs\vizier.log

• Help / About / self-check: F1 opens the docs; Help → About Vizier runs health checks and can copy diagnostics to the clipboard

Model loading and agent turns run on background threads, so the UI stays responsive while the model is working. Sessions are saved automatically after each turn and can be renamed or reloaded from disk. Downloads can be cancelled and clean up their partial files.

CLI reference

usage: vizier [-h] [--version] [--model GLOBAL_MODEL] [--verbose] {gui,chat,mcp-server,models,info,doctor,version} ...

Chat slash commands

MCP integration

Vizier as an MCP server

Vizier exposes 15 tools over stdio, SSE, or streamable HTTP:

vizier-mcp-server --stdio
vizier-mcp-server --sse --host 127.0.0.1 --port 9000
vizier-mcp-server --streamable-http --host 127.0.0.1 --port 9000

Example client configuration (Claude Desktop, Cursor, VS Code, etc.):

{
  "mcpServers": {
    "vizier": {
      "command": "vizier-mcp-server",
      "args": ["--stdio"]
    }
  }
}

Exposed tools: file_read, file_write, file_list, file_info, file_move, file_delete, file_search, shell_run, screenshot, mouse_click, mouse_move, keyboard_type, keyboard_hotkey, screen_size, list_windows. Resources: config://models-directory, config://user-home, config://platform-info.

The MCP server does not apply the agent's YOLO gate: tools are exposed directly. Only register it with clients you trust, and prefer a restricted working directory.

Vizier as an MCP client

Add servers to mcp_servers in your config.json; they are connected on startup when mcp_auto_start is true. Each server's tools become mcp_<server>_<tool> entries in Vizier's registry.

{
  "mcp_auto_start": true,
  "mcp_servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\you\\Documents"],
      "env": {},
      "enabled": true,
      "auto_start": true
    },
    {
      "name": "remote",
      "transport": "sse",
      "url": "http://127.0.0.1:9000/sse",
      "enabled": true,
      "auto_start": false
    }
  ]
}

stdio servers use command, args, and env. Non-stdio servers use url.

Configuration

Vizier stores user data in a platform-specific directory:

• config.json — preferences (written atomically, with config.json.bak recovery)

• models/ — downloaded GGUF files

• sessions/ — saved conversations (JSON)

• cache/ — screenshots and temporary files

• logs/ — rotating vizier.log, plus crash.log for native crashes

Example config.json:

{
  "model_path": "C:\\Users\\you\\AppData\\Local\\Vizier\\models\\qwen3-8b-q4_k_m.gguf",
  "model_n_ctx": 8192,
  "model_n_gpu_layers": 0,
  "model_temperature": 0.7,
  "model_top_p": 0.9,
  "model_repeat_penalty": 1.1,
  "yolo_enabled": false,
  "max_tool_rounds": 10,
  "system_prompt": "You are Vizier, a local AI agent...",
  "mcp_auto_start": true,
  "mcp_servers": []
}

Safety and YOLO mode

Vizier is designed to be useful but not reckless:

• YOLO mode is off by default. When off, the agent may use read-only and UI tools, but write_file, move_file, delete_file, and shell are blocked and the model receives a BLOCKED tool result.

• YOLO mode must be enabled explicitly (checkbox, menu, /yolo, or --yolo). It permits destructive filesystem operations and arbitrary shell commands. Treat it like handing an agent a terminal.

• Filesystem access is root-restricted by default. FilesystemManager only permits paths under the user's home directory and the current working directory (strict=True). Paths outside those roots raise PermissionError rather than silently succeeding.

• Shell commands time out (default 60s at the manager level; per-call timeout is available).

• Tool calls have a timeout (default 60s) and failures are reported back to the model instead of crashing the loop.

The MCP server bypasses the YOLO gate by design — it is a direct tool server for trusted clients.

Hardware-aware model recommendations

vizier models --recommend detects your CPU/RAM/GPU and prints models at or below your tier. Curated entries include:

Recommendations are ordered from largest/most capable to smallest. The list is a starting point, not a hard limit — any compatible GGUF can be loaded manually.

Project structure

vizier/
├── __main__.py            # python -m vizier
├── cli.py                 # Argument parsing + GUI/chat/MCP/models/doctor commands
├── config.py              # Atomic, sanitised config (dataclass + JSON)
├── diagnostics.py         # Health checks for `vizier doctor` and the About box
├── logging_setup.py       # Rotating logs, crash log, exception hook
├── theme.py               # Midnight-palace Qt theme + bundled font loading
├── utils.py               # Data dirs, hardware detection, colors
├── core/
│   ├── agent.py           # Agent loop, tool execution, YOLO gate
│   ├── tool.py            # VizierTool base + FunctionTool schema inference
│   ├── types.py           # Messages, tool calls, results
│   ├── session.py         # Conversation persistence (atomic writes)
│   ├── mcp_client.py      # MCP client + tool adapters
│   ├── skill.py           # Skill discovery (experimental)
│   ├── llm/
│   │   ├── provider.py    # LLMProvider interface
│   │   ├── llama_cpp.py   # GGUF streaming provider
│   │   └── model_manager.py  # Recommend/search/download models (.part safe)
│   ├── fs/file_ops.py     # Root-restricted filesystem manager
│   ├── shell/__init__.py  # Shell execution with timeout
│   └── computer/          # Screen capture, mouse, keyboard, vision
├── tools/                 # Registry + built-in tool wrappers
├── ui/
│   ├── main_window.py     # Qt desktop app
│   └── dialogs.py         # Settings, model manager, sessions, About
└── servers/mcp_server.py  # Vizier as an MCP server

packaging/windows/         # PyInstaller spec, entry points, Inno Setup script
scripts/                   # Asset/version generation + build automation
tests/                     # pytest suite (101 tests)

Development

# Install runtime + dev dependencies
python -m pip install -e ".[full,dev]"

# Syntax check every file
python -m compileall -q vizier tests packaging scripts

# Run the test suite (headless Qt)
$env:QT_QPA_PLATFORM = "offscreen"   # PowerShell
python -m pytest -q

# Lint
ruff check vizier tests packaging scripts

The tests cover config persistence and recovery, filesystem safety, shell execution, tool registry, the agent loop (including YOLO blocking, timeouts, and callbacks), sessions, model recommendations/downloads, MCP configuration/adapters, diagnostics, logging, the CLI, and headless GUI/dialog tests.

Build a Windows release (tests → lint → PyInstaller → smoke tests → installer → checksums):

powershell -ExecutionPolicy Bypass -File scripts\build_windows.ps1

Requirements: Python 3.10+ with the full/dev extras, and Inno Setup 6 for the installer. Add -SkipInstaller for a portable bundle only. Artifacts land in dist\, including SHA256SUMS-<version>.txt.

Headless GUI check:

# PowerShell
$env:QT_QPA_PLATFORM = "offscreen"
python -c "from PySide6.QtWidgets import QApplication; app=QApplication([]); from vizier.ui.main_window import VizierWindow; w=VizierWindow(); print(w.windowTitle()); w.close()"

Build a wheel/sdist:

python -m pip install build
python -m build

Troubleshooting

Windows SmartScreen or antivirus warning Release binaries are unsigned. SmartScreen shows “Windows protected your PC” for new unsigned executables; choose More info → Run anyway only if you downloaded the release from a source you trust. Builds from this repository are reproducible with scripts\build_windows.ps1.

Something went wrong / the app closes immediately Open %LOCALAPPDATA%\Vizier\logs\vizier.log (or Help → About Vizier → Open log folder) and run VizierCLI.exe doctor. The self-check reports missing dependencies, model problems, disk space, and logging issues.

llama-cpp-python fails to install Install a prebuilt wheel or the required C++ toolchain; see the upstream README. On Windows, pip install llama-cpp-python --prefer-binary often helps.

GUI does not start Install PySide6 (pip install -e ".[gui]"). On a headless machine, set QT_QPA_PLATFORM=offscreen for smoke tests.

MCP server/client errors Vizier targets the mcp 2.x API (Client, MCPServer). Install mcp>=2.0; code written for mcp<2 (for example FastMCP) is not compatible.

FileNotFoundError or PermissionError The filesystem manager only allows paths under your home directory and the current working directory. Start Vizier from the directory you want to work in, or construct FilesystemManager(allowed_roots=[...]) in your own code.

OCR does nothing Install Tesseract and make sure tesseract is on PATH (Windows: the UB Mannheim build). Set pytesseract.pytesseract.tesseract_cmd if needed.

Model output is slow Try a smaller quant (Q4_K_M), reduce model_n_ctx, and offload layers with model_n_gpu_layers if you have a compatible GPU.

Roadmap / out of scope

Completed: core agent, tool registry, GGUF streaming, YOLO gate, filesystem/shell/computer tools, MCP client/server, hardware detection, model manager, sessions, CLI, desktop GUI, diagnostics, logging, PyInstaller bundle, Windows installer, and tests.

Not in this release: voice input, screen painting/drawing, clipboard history, plugin/skill marketplace, web dashboard, user authentication, and prebuilt macOS/Linux packages (both run from source). See DEVELOPMENT_CHECKLIST.md for the full status.

License

MIT — see LICENSE.

Vizier is an independent project. “Vizier” refers to the historical royal advisor; the name is not affiliated with any other software product.