WinAlp — Jarvis-Local OS Agent

%100 Offline · Sıfır Kurulum · Taşınabilir · Windows x64 + Linux (AppImage)

WinAlp is a Jarvis-style desktop AI agent that runs entirely on your local machine without any internet connection. It listens to your voice, reads your screen, manages your files, and remembers your context — all powered by a single portable binary (.exe on Windows, .AppImage on Linux).

---

Philosophy

Principle	Detail
Zero Dependency	Only the .gguf model file is needed from the user. Every library (llama.cpp, whisper.cpp, raylib, SQLite, Lua, Dear ImGui) is statically linked into the executable.
Zero Installation	No Python, Node.js, CUDA Toolkit, or package manager required.
Fully Portable	Copy the folder anywhere — it just works.
100% Offline	No data ever leaves your machine.

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         WinAlp.exe                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
│  │  THREAD 1 │  │ THREAD 2 │  │ THREAD 3 │  │   THREAD 4   │   │
│  │  UI/HUD   │  │ Audio+STT│  │  LLM     │  │ Vision/OCR   │   │
│  │ Raylib+   │  │miniaudio │  │llama.cpp │  │ DXGI Dupl.   │   │
│  │ ImGui 60  │  │+whisper  │  │ streaming│  │ pixel-change │   │
│  │   FPS     │  │  .cpp    │  │  tokens  │  │  triggered   │   │
│  └─────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬───────┘   │
│        │             │              │                │           │
│        └─────────────┴──────────────┴────────────────┘          │
│                    Thread-safe message queues                    │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    THREAD 5 — Memory & Plugins           │   │
│  │         memory_store.c (SQLite mutex) + plugin_manager   │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

---

Core Modules

Module	File	Role
Ear	audio_capture.c	miniaudio.h — realtime PCM capture
STT	stt_engine.c	whisper.cpp — speech → text
Brain	ai_engine.c	llama.cpp — LLM inference + streaming
Eye	vision_engine.c	DXGI Duplication + OCR
Hand	system_agent.c	JSON action parser + OS executor
Memory	memory_store.c	SQLite + profile.json persistence
UI	ui_render.c	Raylib + ImGui holographic HUD
Scripts	lua_runtime.c	Embedded Lua + hot-reload
Prompts	prompt_engine.c	Template-based system prompt synthesis
Plugins	plugin_manager.c	Sandboxed Lua plugin loader
PDF	pdf_reader.c	Static C PDF text/image extractor
Context	context_tracker.c	Win32 active window tracker

---

Directory Structure

WinAlp/
├── WinAlp.exe            ← Portable executable (~15-25 MB, statically linked)
├── models/               ← Drop your .gguf model here
│   ├── brain-model.gguf
│   └── whisper-tiny-tr.bin
├── src/                  ← C source files
├── include/              ← Header files
├── lib/                  ← Static library archives
├── scripts/              ← Lua behavior scripts
├── plugins/              ← Extensible plugin packages
├── build/                ← Compiler intermediates (generated)
├── profile/              ← User data (auto-created on first run)
│   ├── conversations.db
│   ├── profile.json
│   ├── tasks/
│   ├── files/
│   └── cache/
└── Makefile

---

Getting Started

Linux (AppImage)

1. Download WinAlp-x86_64.AppImage (or build it — see below).
2. chmod +x WinAlp-x86_64.AppImage && ./WinAlp-x86_64.AppImage
3. On first run, drop a GGUF model into models/ (next to the AppImage) — or let WinAlp auto-download a small one.

Windows

1. Download a GGUF model (e.g. Qwen-2.5-1.5B-Instruct Q4_K_M) and place it in models/.
2. Run WinAlp.exe — the model selector screen will appear automatically.
3. Select your model and start talking or typing. That's it.

No installation. No setup wizard. No internet. Just run.

---

Hardware Recommendations

Tier	Model	RAM Required
Light (CPU only)	Qwen-2.5-1.5B Q4_K_M	~2 GB
Medium	Llama-3.2-3B Q4_K_M	~3 GB
Pro (high VRAM)	DeepSeek-R1-14B Q8_0	~18 GB

Tested reference hardware: ASUS N55JK (i7-4700HQ · GT 850M 2GB · 8GB RAM) — Light tier recommended.

---

Security

• All file operations are sandboxed to the working directory.
• Destructive actions (delete, overwrite) require explicit user confirmation via UI overlay.
• All profile data is stored locally. Nothing is transmitted over the network.
• Optional encryption for profile/ contents: Windows DPAPI on Windows, machine-keyed AES-256-GCM (OpenSSL, key derived from /etc/machine-id) on Linux.

---

Build (for developers)

Linux (incl. AppImage)

# 0. Toolchain + dev headers (Debian/Ubuntu example)
#    sudo apt install gcc g++ make cmake curl libx11-dev libxrandr-dev \
#                     libxi-dev libxinerama-dev libxcursor-dev \
#                     libgl1-mesa-dev libssl-dev

# 1. Pull submodules (llama.cpp, whisper.cpp)
./scripts/submodules.sh

# 2. Build static deps (Lua, raylib, whisper.cpp, llama.cpp)
make submodule-libs

# 3. Build the WinAlp binary
make linux

# 4. Unit tests
make test

# 5. Package as AppImage (linuxdeploy + appimagetool)
make appimage

The build is split into small shell scripts so each dependency can be rebuilt independently: scripts/build_lua.sh, scripts/build_raylib.sh, scripts/build_whisper.sh, scripts/build_llama.sh. All Linux static libraries land in lib/linux/ (gitignored).

Building without a system toolchain (container / Flatpak runtime)

Hosts such as a GNOME Flatpak runtime container ship no gcc, make, cmake or dev headers. WinAlp builds with a self-contained conda toolchain kept in $HOME:

# 1. Bootstrap micromamba
mkdir -p "$HOME/.winalp-build/winalp-tools"
curl -L --fail -o "$HOME/.winalp-build/winalp-tools/micromamba" \
  https://github.com/mamba-org/micromamba-releases/releases/latest/download/micromamba-linux-64
chmod +x "$HOME/.winalp-build/winalp-tools/micromamba"

# 2. Create the build environment
export MAMBA_ROOT_PREFIX="$HOME/.winalp-build/winalp-mamba"
"$HOME/.winalp-build/winalp-tools/micromamba" create -y -p "$HOME/.winalp-build/winalp-env" \
  gcc_linux-64 gxx_linux-64 binutils_linux-64 make cmake pkg-config \
  openssl alsa-lib libglvnd mesalib \
  xorg-libx11 xorg-libxrandr xorg-libxi xorg-libxinerama xorg-libxcursor \
  xorg-libxext xorg-libxrender bzip2 zlib

# 3. Activate the build environment (PATH, sysroot, pkg-config)
source "$HOME/.winalp-build/env.sh"     # see notes below

# 4. Provide link-time GL stubs (system Mesa + libglvnd)
mkdir -p "$HOME/.winalp-build/systemgl"
for n in libGL.so.1 libGLX.so.0 libGLdispatch.so.0 libOpenGL.so.0; do
  ln -sf "/usr/lib/x86_64-linux-gnu/$n" "$HOME/.winalp-build/systemgl/${n%.*}"
done

# 5. Build
./scripts/submodules.sh
make submodule-libs
make linux \
  SYS_CFLAGS="-I$CONDA_PREFIX/include" \
  SYS_LDFLAGS="-L$HOME/.winalp-build/systemgl -L$CONDA_PREFIX/lib \
               -Wl,-rpath-link,$HOME/.winalp-build/systemgl:$CONDA_PREFIX/lib:/usr/lib/x86_64-linux-gnu"

# 6. Package as AppImage (tools cached in WINALP_TOOLS_DIR)
WINALP_TOOLS_DIR="$HOME/.winalp-build/tools" make appimage

env.sh exports MAMBA_ROOT_PREFIX, CONDA_PREFIX, CONDA_BUILD_SYSROOT (pointing at the conda sysroot), PATH, CMAKE_PREFIX_PATH and PKG_CONFIG_PATH.

Notes:

• -rpath-link is required: GNU ld does not search -L directories for transitive DT_NEEDED dependencies (e.g. libGL.so → libGLX.so.0 / libGLdispatch.so.0).
• SYS_CFLAGS / SYS_LDFLAGS are the Makefile's hooks for environment-specific include/library paths. A plain distro build with a system toolchain does not need them.
• The AppImage icon is downscaled to 512×512 automatically with ffmpeg (linuxdeploy rejects larger icons).

Windows

# Requires MinGW-w64 or MSVC toolchain
make all

See Makefile for build flags and static library configuration.

---

License

MIT License — see LICENSE file.

---

WinAlp is an open-source project. Contributions, bug reports and model compatibility notes are welcome.