# How to Perform Read-Only Operations on Windows with Claude-Obsidian

> Learn how to perform read-only operations on Windows with Claude-Obsidian. Inspect, preview, and retrieve data safely while avoiding vault mutations on unsupported platforms.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: how-to-guide
- Published: 2026-08-25

---

**Claude-Obsidian supports inspection, dry-run previews, and retrieval commands on native Windows, but blocks all vault mutations with an `UNSUPPORTED_PLATFORM` error because Windows lacks POSIX directory-descriptor confinement.**

Claude-Obsidian, the open-source bridge between Claude and Obsidian vaults maintained by **AgriciDaniel**, offers limited functionality on native Windows systems. While the tool requires a POSIX-compatible environment for write operations, you can safely perform **read-only operations on Windows with Claude-Obsidian** without installing WSL, provided you understand the platform boundaries enforced by the source code.

## Why Write Operations Require POSIX Confinement

The core limitation stems from the library's security model. According to [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py), any mutation operation relies on **POSIX directory-descriptor confinement** (`dirfd`), which Windows does not provide. This mechanism ensures that file operations remain confined to the intended directory, preventing directory traversal attacks during vault modifications.

Because native Windows lacks this capability, the library refuses write commands and raises a `TransactionValidationError` with code `UNSUPPORTED_PLATFORM`. The error message directs users to [`docs/windows-wsl.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/windows-wsl.md) for guidance on running operations inside WSL.

## Read-Only Capabilities Available on Native Windows

Despite the write restrictions, several key features work directly from the Windows command prompt:

- **Transaction inspection and dry-run previews**: Validate transaction bundles without applying changes
- **Vault queries and retrieval**: Search and retrieve Obsidian pages using natural language
- **Capture queue listing**: View pending capture items via read-only enumeration

Operations that remain blocked include `transaction apply`, `init`, `adopt`, Git checkpoints (`checkpoint`), and bash setup scripts.

## How the Platform Guard Enforces the Read-Only Boundary

### The Platform Check Implementation

In [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py), the function `_require_write_platform()` serves as the security gatekeeper. Before any mutation, this function checks for dirfd support through an internal `_require_lock_dirfd_support()` call. When running on native Windows, this check raises `_PlatformConfinementUnavailable`, which the guard converts into a `TransactionValidationError` with the `UNSUPPORTED_PLATFORM` code.

### CLI Integration and Error Handling

The CLI entry points in [`claude_obsidian/cli.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/cli.py) invoke this guard before executing mutating commands. If the platform check fails, the CLI surfaces the error without a Python traceback, providing a clean user experience. The test `test_cli_surfaces_platform_error_without_traceback` in [`tests/test_windows_compat.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_windows_compat.py) verifies that users see a concise error message rather than technical stack traces.

### Side-Effect-Free Guarantee

Crucially, the guard executes before any file system modifications occur. The test `test_apply_refused_before_any_side_effect` in [`tests/test_windows_compat.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_windows_compat.py) confirms that when `transaction apply` fails on Windows, no files are created or modified, maintaining vault integrity. Similarly, `test_inspect_dry_run_succeeds_without_dirfd` verifies that inspection commands bypass the write guard entirely.

## Code Examples for Windows Command Prompt

The following commands assume your vault is located at `C:\my-vault` and can be executed directly in `cmd.exe` or PowerShell without WSL.

### Inspect a Transaction Bundle (Dry-Run)

```bat
claude-obsidian transaction inspect --vault C:\my-vault bundle.json

```

This read-only command analyzes the transaction bundle and outputs a JSON plan containing `valid`, `changed_paths`, and `approval_sha256` fields. Because it performs no writes, it executes successfully on native Windows and returns exit code 0.

### Query Vault Content

```bat
claude-obsidian wiki query --vault C:\my-vault "What supports source-grounded notes?"

```

The `wiki query` command searches your vault and returns matching Obsidian pages. Since this is a retrieval operation, it bypasses the write guard entirely and works natively on Windows.

### List the Capture Queue

```bat
claude-obsidian capture queue list --vault C:\my-vault

```

While capture operations generally require POSIX features, listing the queue is a read-only enumeration that does not trigger the platform guard, making it safe for Windows usage.

### Attempting a Write (Expected Failure)

```bat
claude-obsidian transaction apply --vault C:\my-vault bundle.json --approved-plan-sha256 <hash>

```

On native Windows, this command exits with code 2 and displays:

```

ERR UNSUPPORTED_PLATFORM: vault writes require directory-descriptor confinement (WSL/Linux or supported macOS); on native Windows run this command inside WSL — read-only inspection and dry-runs work natively; if WSL itself misbehaves, see docs/windows-wsl.md

```

As verified by `test_apply_refused_before_any_side_effect`, this failure occurs before any side effects, ensuring your vault remains unchanged.

## Key Implementation Files

- [`docs/windows-wsl.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/windows-wsl.md): User-facing documentation explaining the platform matrix and WSL setup
- [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py): Contains `_require_write_platform()` and the platform detection logic
- [`claude_obsidian/cli.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/cli.py): CLI routing that invokes platform guards before mutating operations
- [`tests/test_windows_compat.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/tests/test_windows_compat.py): Test suite validating Windows read-only behavior and error handling

## Summary

- Claude-Obsidian allows **read-only operations on Windows** including inspection, dry-runs, queries, and queue listing
- All write operations are blocked by `_require_write_platform()` raising `UNSUPPORTED_PLATFORM` 
- The platform guard ensures zero side effects when blocking unsupported operations on Windows
- For full functionality including `transaction apply`, use WSL or another POSIX-compatible environment
- Reference [`docs/windows-wsl.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/windows-wsl.md) for detailed WSL configuration instructions

## Frequently Asked Questions

### Can I use Claude-Obsidian on native Windows at all?

Yes, but only for read-only operations. You can inspect transactions, query vault content, and list capture queues directly from the Windows command prompt. Any command that modifies the vault requires WSL or a Linux environment.

### Why does transaction apply fail with UNSUPPORTED_PLATFORM on Windows?

The `transaction apply` command (and other mutations) rely on POSIX directory-descriptor confinement (`dirfd`) for security. Windows lacks this feature, so [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py) raises a `TransactionValidationError` with code `UNSUPPORTED_PLATFORM` to prevent potentially unsafe file operations.

### What is the difference between transaction inspect and transaction apply on Windows?

`transaction inspect` is a read-only dry-run that analyzes bundles without modifying files, so it works natively on Windows. `transaction apply` writes changes to the vault and is blocked on Windows by the `_require_write_platform()` guard, requiring WSL instead.

### Will attempting a forbidden write operation corrupt my vault?

No. The platform check in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py) runs before any file modifications occur. As tested in `test_apply_refused_before_any_side_effect`, the process exits with code 2 without creating or modifying any files, maintaining complete vault integrity.