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

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, 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 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, 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 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 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 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)

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

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

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)

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: User-facing documentation explaining the platform matrix and WSL setup
• claude_obsidian/transaction.py: Contains _require_write_platform() and the platform detection logic
• claude_obsidian/cli.py: CLI routing that invokes platform guards before mutating operations
• 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}