Summary

QMD does not work on Windows due to multiple Unix-specific assumptions throughout the codebase. I attempted to install and run QMD on Windows 11 with Bun 1.3.6 and encountered multiple blocking issues.

Environment

• OS: Windows 11 (x64)
• Bun: 1.3.6
• Installation method: bun install -g https://github.com/tobi/qmd

Installation Output

Installation succeeds with a warning:

warn: GET https://registry.npmjs.org/sqlite-vec-win32-x64 - 404
installed qmd@github:tobi/qmd#5fa66fd with binaries: - qmd

Issues Identified

1. Bash Shebang in Binary (Blocking)

File: qmd

The qmd executable uses #!/usr/bin/env bash which doesn't work on Windows:

#!/usr/bin/env bash
# qmd - Quick Markdown Search
set -euo pipefail

Error: /bin/bash: C:\Users\...\node_modules\qmd\qmd: No such file or directory

Workaround: Running directly with bun run src/qmd.ts works partially.

2. Unix mkdir -p Command (Blocking)

File: src/store.ts#L109

try { Bun.spawnSync(["mkdir", "-p", qmdCacheDir]); } catch { }

Fix: Use Node.js fs.mkdirSync(path, { recursive: true }) instead.

3. Path Resolution Assumes Unix Paths (Blocking)

File: src/store.ts#L65-L83

export function resolve(...paths: string[]): string {
  // ...
  let result = paths[0]!.startsWith('/') ? '' : Bun.env.PWD || process.cwd();
  // ...
  return '/' + normalized.join('/');  // Always prefixes with /
}

This causes paths like /C:\Users\... which are invalid on Windows.

Observed Error:

ENOENT: no such file or directory, open '/C:\Users\auste\source\...'

4. HOME Environment Variable Fallback

File: src/store.ts#L43

const HOME = Bun.env.HOME || "/tmp";

On Windows, HOME is not set by default (Windows uses USERPROFILE). The fallback /tmp doesn't exist.

Fix: const HOME = Bun.env.HOME || Bun.env.USERPROFILE || os.homedir();

5. Path Separator Hardcoded as Forward Slash

Throughout the codebase, paths are joined with / and split by /. Windows uses \ natively, though Node.js often handles both.

Examples:

• src/qmd.ts#L209: collectionDir.split('/').pop()
• src/qmd.ts#L213: filepath.startsWith(collectionDir + '/')

6. macOS-Only SQLite Extension Handling

File: src/store.ts#L266-L272

if (process.platform === "darwin") {
  const homebrewSqlitePath = "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib";
  // ...
}

No Windows equivalent is provided.

7. Tests Hardcode Unix Paths

File: src/store.test.ts

Tests use paths like /tmp, /Users/, /home/ which don't exist on Windows.

8. Nix Flake Explicitly Excludes Windows

File: flake.nix#L45

platforms = platforms.unix;

Reproduction Steps

1. Install Bun on Windows: irm bun.sh/install.ps1 | iex
2. Install qmd: bun install -g https://github.com/tobi/qmd
3. Run: qmd --help → Fails with bash error
4. Workaround: bun run $env:USERPROFILE\node_modules\qmd\src\qmd.ts --help → Works
5. Set INDEX_PATH and try: qmd collection add . --name test → Fails with path error

Suggested Fixes

1. Replace bash script with cross-platform launcher - Use a Node.js/Bun script or platform-specific binaries
2. Use path module - Replace hardcoded path operations with path.join, path.resolve, path.sep
3. Use os.homedir() - Instead of relying on HOME environment variable
4. Use fs.mkdirSync - Instead of spawning mkdir -p
5. Add Windows to CI - Test on Windows in GitHub Actions
6. Handle drive letters - Windows paths like C:\ need special handling

Workaround (Partial)

For basic operations, you can use:

$env:INDEX_PATH = "$env:USERPROFILE\.cache\qmd\index.sqlite"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cache\qmd"
bun run $env:USERPROFILE\node_modules\qmd\src\qmd.ts status

However, collection operations still fail due to path handling issues.

Related

• This tool is designed for macOS/Linux per the README which mentions Homebrew SQLite
• No Windows-specific documentation exists

I'd be happy to contribute a PR if there's interest in Windows support! 🪟