Platform Requirements for Running Claude-Obsidian Mutations

Claude-Obsidian mutations require a POSIX-compatible host—Linux, macOS, or Windows Subsystem for Linux (WSL)—running Python 3.11 or newer with Bash, and a filesystem that provides stable inode and device identifiers.

Claude-Obsidian is an open-source vault management system developed by AgriciDaniel that enforces strict platform constraints to guarantee safe mutation operations. Commands such as transaction apply, init, adopt, migrate, and capture apply rely on kernel-level directory-confinement primitives to prevent symlink redirection attacks and ensure all writes remain anchored to the vault root.

Operating System and Platform Support

Claude-Obsidian supports Linux, macOS, and Windows Subsystem for Linux (WSL) for mutation operations. Native Windows environments cannot perform vault writes and will abort immediately with the error code UNSUPPORTED_PLATFORM. According to docs/windows-wsl.md, this restriction exists because native Windows lacks the POSIX directory-descriptor capabilities required for secure write confinement.

Software Prerequisites

Python 3.11 or Newer

The codebase requires Python 3.11 or later, as specified in docs/install-guide.md. Earlier Python versions lack the specific os module interfaces and type-hinting support utilized by the transaction engine.

Bash Shell

Bash is mandatory for executing installer scripts and running the test suites. While the core Python library can run within any shell, the automation scripts and development workflows assume a Bash environment.

Filesystem and Security Constraints

To prevent concurrent symlink attacks and directory replacement vulnerabilities, Claude-Obsidian enforces two critical filesystem requirements.

Stable Inode and Device Identity

The vault must reside on a filesystem that supplies stable inode and device IDs. Compatible filesystems include NTFS (on Windows via WSL) and ext4 (on Linux). Filesystems such as FAT, exFAT, or network shares that lack stable identity guarantees are rejected with the error UNSAFE_VAULT_IDENTITY. This validation ensures the transaction engine can reliably track file identity across mutation operations, as documented in docs/windows-wsl.md.

POSIX Directory-Descriptor Confinement

The most stringent requirement is POSIX-style directory-descriptor confinement. The host must expose os.open, os.mkdir, os.stat, os.unlink, os.rmdir, and os.rename with O_DIRECTORY, O_NOFOLLOW, and dir_fd capabilities. These flags enable the library to operate within a directory file descriptor, ensuring that every write stays anchored to the vault root and cannot be redirected by concurrent symlink manipulation.

In claude_obsidian/transaction.py, the function _require_lock_dirfd_support validates these capabilities at runtime, while _require_write_platform enforces the broader platform constraints. If the host kernel lacks these primitives, the library raises TransactionValidationError before any disk mutation occurs.

Runtime Platform Validation

Before executing mutations, invoke the platform checks explicitly or rely on the automatic validation within transaction initialization:

from claude_obsidian.transaction import _require_write_platform, TransactionValidationError

try:
    _require_write_platform()  # Raises if dirfd confinement is unavailable

except TransactionValidationError as e:
    print(f"Cannot mutate vault: {e.code} – {e}")

For WSL environments, execute mutations within the Linux shell:

wsl
python3 scripts/claude-obsidian.py capture apply --vault my_vault \
    --generated-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
    --operation-id capture-reviewed \
    --approved-plan-sha256 <sha256> \
    --apply

Optional Development Dependencies

Git is required only for development workflows, release builds, or explicit checkpoint operations. It is not a runtime dependency for vault mutations themselves, as noted in docs/install-guide.md.

Summary

• Operating System: Linux, macOS, or WSL only; native Windows is unsupported for writes and returns UNSUPPORTED_PLATFORM.
• Python: Version 3.11 or newer is mandatory.
• Shell: Bash is required for installer and test scripts.
• Filesystem: Use NTFS, ext4, or similar with stable inode/device IDs; avoid FAT, exFAT, and unstable network shares to prevent UNSAFE_VAULT_IDENTITY errors.
• Kernel Support: The host must provide directory-descriptor operations with O_DIRECTORY, O_NOFOLLOW, and dir_fd support, validated by _require_lock_dirfd_support in claude_obsidian/transaction.py.
• Version Control: Git is optional and only needed for development or checkpoint features.

Frequently Asked Questions

Can I run Claude-Obsidian mutations on native Windows without WSL?

No. Native Windows lacks the POSIX directory-descriptor primitives required for secure mutation confinement. Attempting to execute write operations on native Windows triggers a TransactionValidationError with code UNSUPPORTED_PLATFORM. You must use Windows Subsystem for Linux (WSL) to perform any vault modifications on Windows hardware.

Why does Claude-Obsidian reject FAT and exFAT filesystems?

These filesystems do not provide stable inode and device identifiers, which the transaction engine requires to verify file identity across operations. Without stable identifiers, the system cannot guarantee that a file has not been replaced by a symlink or alternate directory entry between validation and write. Consequently, vaults on FAT or exFAT raise UNSAFE_VAULT_IDENTITY errors.

Is Git required for running Claude-Obsidian mutations?

No. Git is only necessary for development workflows, building releases, or creating explicit checkpoints. The core mutation engine—transaction apply, capture apply, and related commands—operates independently of Git, as confirmed by the installation documentation in docs/install-guide.md.

What specific kernel capabilities does _require_lock_dirfd_support check?

The function verifies that the Python os module supports open, mkdir, stat, unlink, rmdir, and rename operations using the dir_fd parameter with O_DIRECTORY and O_NOFOLLOW flags. These capabilities enable directory-descriptor confinement, ensuring all filesystem operations remain scoped to the vault root and are immune to path traversal or symlink attacks during concurrent mutations.

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