Bug Description

OpenViking Windows Build Failure — Bug Report

Date: 2026-03-12
Status: 🏗️ Draft
Reporter: Brad Krause (aiformy.biz)
Environment: Windows 11 Home 25H2, AMD Ryzen 5, 8GB RAM, Developer Mode enabled
OpenViking Version: 0.2.6

Summary

pip install openviking fails on Windows due to a Unix shell assumption in the AGFS binding library Makefile. The build system calls OS as a shell command, which is undefined on Windows. This affects both Python 3.14 (native Windows) and Python 3.12 (MSYS2 UCRT64).

Exact Error

Building AGFS binding library: libagfsbinding.dll
[Error] Failed to build AGFS binding library: Command '['make', 'build-lib']' returned non-zero exit status 2.
Build stdout: "Detecting OS for building binding library..."
Build stderr: 'OS' is not recognized as an internal or external command, operable program or batch file.
make: *** [Makefile:29: build-lib] Error 255
RuntimeError: Failed to build AGFS binding library: Command '['make', 'build-lib']' returned non-zero exit status 2.

Traceback root: setup.py line 230 → _build_agfs_artifacts_impl → subprocess.CalledProcessError

Root Cause

The Makefile at third_party/agfs/ contains a target at approximately line 29 (build-lib) that calls OS as a shell variable or command for platform detection. On Unix/Mac, OS resolves (e.g., via uname). On Windows — even under MSYS2 with make installed — make spawns a Windows subprocess for this target, where OS is not a recognized command.

The agfs-server.exe (Go binary) builds successfully. Only libagfsbinding.dll fails.

Reproduction Steps

Environment 1: Native Windows Python 3.14

# Python 3.14.3 at C:\Python314\python.exe
# MSYS2 UCRT64 tools on PATH (gcc 15.2.0, make 4.4.1, cmake 4.2.1, Rust 1.92.0)
$env:PATH = "C:\msys64\ucrt64\bin;" + $env:PATH
C:\Python314\python.exe -m pip install openviking

Result: All dependencies install successfully via pre-built Windows wheels. Build fails at libagfsbinding.dll with 'OS' is not recognized.

Environment 2: MSYS2 UCRT64 Python 3.12

# Inside MSYS2 UCRT64 terminal
pip install openviking --break-system-packages

Result: Same 'OS' is not recognized error at make build-lib. The subprocess pip spawns to run make does not inherit the MSYS2 shell environment.

Dependency Resolution Notes

On Python 3.14 (Windows), all native dependencies resolved correctly via pre-built wheels:

• tree-sitter and all language parsers: cp314-cp314-win_amd64.whl / cp39-abi3-win_amd64.whl ✅
• cryptography, cffi: pre-built Windows wheels ✅
• fastuuid, pydantic-core, tiktoken, aiohttp: pre-built Windows wheels ✅
• lxml, pyyaml, xxhash, regex: pre-built Windows wheels ✅

The only build failure is openviking itself, caused solely by the libagfsbinding.dll Makefile issue.

Toolchain Installed During Diagnosis

Suggested Fix

In third_party/agfs/Makefile (approximately line 29, build-lib target):

Replace Unix-style OS detection:

OS := $(shell uname -s)  # or similar

With cross-platform detection compatible with make on Windows:

ifeq ($(OS),Windows_NT)
    DETECTED_OS := Windows
else
    UNAME_S := $(shell uname -s)
    ifeq ($(UNAME_S),Linux)
        DETECTED_OS := Linux
    endif
    ifeq ($(UNAME_S),Darwin)
        DETECTED_OS := Darwin
    endif
endif

Note: On Windows, make sets the OS environment variable to Windows_NT automatically. The current code appears to be calling OS as a shell command rather than reading it as an environment variable — the fix is to treat it as a variable ($(OS)) rather than a command invocation.

Alternatively, providing a pre-built libagfsbinding.dll as a release artifact (similar to how PyPI wheels handle platform-specific binaries) would sidestep the issue entirely for Windows users.

Use Case Context

This bug report was generated during an attempt to integrate OpenViking as a persistent context database for a legal investigation workflow (LEXFRAME architecture) connecting Claude Desktop via MCP. The architectural fit is strong — external state persistence independent of Claude Projects solves a real context window management problem for AI-assisted workflows. Windows support is a blocker for this use case.

Session Notes

• Total toolchain installation time: ~3 hours across multiple MSYS2 pacman installs
• The Go binary (agfs-server.exe) builds successfully — only the C binding library fails
• MSYS2 UCRT64 was used (not MINGW64 or base MSYS) for toolchain consistency
• Developer Mode enabled on Windows 11 did not affect the outcome
• Two Python environments tested: native Windows 3.14.3 and MSYS2 3.12
• All third-party Python dependencies resolve correctly — the issue is isolated to the AGFS binding build step

Steps to Reproduce

Environment 1: Native Windows Python 3.14

$env:PATH = "C:\msys64\ucrt64\bin;" + $env:PATH
C:\Python314\python.exe -m pip install openviking

Environment 2: MSYS2 UCRT64 Python 3.12

pip install openviking --break-system-packages

Both environments have a full toolchain on PATH: gcc 15.2.0, make 4.4.1, cmake 4.2.1, Rust 1.92.0, Go 1.26.1 (all via MSYS2 UCRT64 pacman).

Expected Behavior

pip install openviking completes successfully and installs the package, as documented. Windows is listed as a supported OS in the README.

Actual Behavior

All third-party dependencies install correctly via pre-built Windows wheels (tree-sitter, cryptography, cffi, pydantic-core, etc.). The build then fails at the AGFS binding library step:
Building AGFS server: agfs-server.exe ... [OK]
Building AGFS binding library: libagfsbinding.dll
[Error] Failed to build AGFS binding library
Build stderr: 'OS' is not recognized as an internal or external command, operable program or batch file.
make: *** [Makefile:29: build-lib] Error 255

The Go binary (agfs-server.exe) builds successfully. Only libagfsbinding.dll fails.

Minimal Reproducible Example

Error Logs

Building AGFS binding library: libagfsbinding.dll
[Error] Failed to build AGFS binding library: Command '['make', 'build-lib']' returned non-zero exit status 2.
Build stdout: "Detecting OS for building binding library..."
Build stderr: 'OS' is not recognized as an internal or external command, operable program or batch file.
make: *** [Makefile:29: build-lib] Error 255

RuntimeError: Failed to build AGFS binding library
Traceback: setup.py line 230 → _build_agfs_artifacts_impl → subprocess.CalledProcessError

OpenViking Version

0.2.6

Python Version

3.14.3 (native Windows); also reproduced on 3.12 (MSYS2 UCRT64)

Operating System

Windows

Model Backend

None

Additional Context

Windows 11 Home 25H2 (build 26200.8037), AMD Ryzen 5, Developer Mode enabled

Root cause: The build-lib Makefile target (third_party/agfs/Makefile, ~line 29) calls OS as a shell command for platform detection. On Windows, OS is not a shell command — it is an environment variable automatically set to Windows_NT by make. The fix is to read it as $(OS) rather than invoke it as a command.

Suggested Makefile fix:

ifeq ($(OS),Windows_NT)
    DETECTED_OS := Windows
else
    UNAME_S := $(shell uname -s)
    ifeq ($(UNAME_S),Linux)
        DETECTED_OS := Linux
    endif
    ifeq ($(UNAME_S),Darwin)
        DETECTED_OS := Darwin
    endif
endif

Alternatively, shipping a pre-built libagfsbinding.dll as a release artifact (similar to PyPI wheel conventions) would sidestep the issue for Windows users entirely.

Note: all Python dependencies resolve correctly via pre-built wheels on both Python environments tested. The issue is isolated entirely to the AGFS binding compilation step.