Supported Operation Types in Claude-Obsidian Transactions: Complete Reference

Claude-Obsidian defines 13 distinct operation types in claude_obsidian/transaction.py that enforce strict authority boundaries over vault mutations, ranging from save and ingest to lint-fix and migration.

The claude-obsidian repository by AgriciDaniel implements a transactional vault system where every mutation is modeled as a typed operation. Understanding these supported operation types in claude-obsidian transactions is essential for extending the system or debugging permission errors. Each type is enumerated in the OPERATION_TYPES constant and determines whether a transaction can modify raw payloads, wiki content, or configuration metadata.

Understanding the Transaction Architecture

In claude_obsidian/transaction.py, the transaction system wraps every vault change in a bundle that carries an operation type. This design enforces authority boundaries—specifically, which parts of the vault a given transaction may touch. The core constant OPERATION_TYPES (lines 44-58) defines the valid enumeration, while safe_operation_id() validates operation strings before bundle construction.

The 13 Operation Types Defined in claude-obsidian

The following table documents all supported operation types as implemented in the source code:

Core and Administrative Operations

• base: Core low-level operation used internally for generic changes.
• setup: Initial vault setup or re-initialization (bootstrap files).
• migration: Structural or format migrations across vault versions.
• configuration: Adjusts .claude-obsidian.json and other config files.
• generic: Catch-all wiki-only operation that cannot modify managed metadata.

Content Creation and Ingestion

• save: Primary wiki-write action for creating or updating pages.
• ingest: Imports raw source payloads (e.g., .raw/ files) into the vault.
• capture: Handles incoming notes such as inbox entries.
• autoresearch: Automatic research extensions pulling external data into vault.

Transformation and UI Operations

• markdown: Pure markdown transformations that avoid touching raw payloads.
• lint-fix: Applies automatic linting corrections to wiki pages.
• fold: Collapses or folds wiki structures like page sections.
• canvas: Manipulates canvas-type artifacts for graphical UI elements.

Authority Boundaries: Wiki vs. Raw Payload Access

The transaction system enforces strict separation between wiki content and raw payloads. According to claude_obsidian/transaction.py, only two operation types may touch both domains:

• ingest: Imports external raw files into the vault structure.
• autoresearch: Pulls external data that may include raw sources.

The following are restricted to wiki-only modifications:

• save, lint-fix, markdown, generic

Attempting to use a wiki-only operation to modify raw payloads results in validation rejection during the bundle planning phase.

Validating and Using Operation Types in Code

When building transaction bundles programmatically, always validate against OPERATION_TYPES before construction.

Validating Operation Strings

Use the built-in enumeration to reject unsupported types:

from claude_obsidian.transaction import OPERATION_TYPES, safe_operation_id

def validate_op(op: str) -> str:
    """Verify operation is supported and return normalized ID."""
    if op not in OPERATION_TYPES:
        raise ValueError(f"Unsupported operation type: {op}")
    return safe_operation_id(op)  # Validates ID format

Constructing Transaction Bundles

Create bundles with the correct schema and operation field:

from pathlib import Path

def make_save_bundle(vault: Path, rel_path: str, content: bytes) -> dict:
    """Create a 'save' transaction bundle for wiki updates."""
    return {
        "schema": "claude-obsidian.transaction.v1",
        "operation": "save",
        "writes": [
            {
                "path": rel_path,
                "data": content.decode(),
                "mode": 0o644,
            }
        ],
    }

# Usage example

bundle = make_save_bundle(
    Path("/my/vault"), 
    "wiki/example.md", 
    b"# Example Content"

)

# Bundle passed to plan_approval_sha256 for approval

Integration with Vault Operations

The high-level API in claude_obsidian/vault_ops.py wraps these primitives, automatically setting the correct operation type based on the method called. For example, ingest_raw_files() sets operation to ingest, while save_page() uses save. The CLI entry point in scripts/claude-obsidian.py exposes these through command-line arguments that map directly to the supported operation types.

Summary

• Claude-obsidian defines 13 operation types in claude_obsidian/transaction.py under the OPERATION_TYPES constant.
• Types range from base and generic to specialized operations like autoresearch and lint-fix.
• Authority boundaries restrict which operations can modify raw payloads versus wiki-only content.
• Use safe_operation_id() and membership checks against OPERATION_TYPES to validate operations before bundle construction.
• The transaction system uses these types to construct journal entries and reject unauthorized writes.

Frequently Asked Questions

What happens if I use an unsupported operation type in a transaction?

The validation logic in claude_obsidian/transaction.py raises a ValueError during bundle construction if the operation string is not found in OPERATION_TYPES. This prevents malformed transactions from reaching the approval or commit stages.

Can I create custom operation types for my claude-obsidian extensions?

No, the OPERATION_TYPES set is enforced as a closed enumeration in the source code. Extensions should map their functionality to existing types like generic for wiki modifications or ingest for importing external data. The authority boundary system depends on this fixed enumeration for security validation.

Which operation types can modify raw files in the .raw/ directory?

Only ingest and autoresearch operations possess the authority to touch both wiki content and raw payload files. Operations like save, markdown, and lint-fix are restricted to wiki-only modifications and will be rejected if they attempt to write to raw paths.

How does the CLI map commands to operation types?

The scripts/claude-obsidian.py entry point maps subcommands directly to operation types. For instance, the save command creates bundles with operation "save", while ingest uses "ingest". This mapping ensures that authority boundaries are respected even when invoking operations from the shell.

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