What Happens During the Save Workflow in Claude-Obsidian: A 4-Stage Atomic Pipeline

The save workflow in claude-obsidian executes a four-stage atomic pipeline—Prepare, Preserve Evidence, Build Transaction, and Preview & Apply—that ensures all vault modifications are validated, auditable, and user-confirmed before commitment.

The AgriciDaniel/claude-obsidian repository implements a transactional save system designed specifically for AI-generated content management. When an Agent produces new Markdown files or modifications, the save workflow guarantees atomic writes, cryptographic provenance, and human-in-the-loop approval before any changes touch the vault. This design prevents partial writes and maintains an immutable audit trail of every modification.

The Four Stages of the Save Workflow

The save workflow follows a strict sequence defined in skills/save/SKILL.md and implemented across the claude_obsidian Python package. Each stage builds upon the previous to create an all-or-nothing transaction bundle.

1. Prepare: Draft Collection and Path Resolution

The workflow begins by gathering all pending drafts from the Agent's context. This includes new notes, updated pages, raw payloads, and ledger entries awaiting persistence.

During preparation, the system validates the structure of each draft and resolves relative paths to absolute vault locations. This ensures that every file target is unambiguous and writable before any disks are touched. The implementation resides in the "Prepare" section of skills/save/SKILL.md and the draft collection logic within claude_obsidian/transaction.py.

2. Preserve Evidence Honestly: Provenance Ledger Creation

Before any write operation occurs, the skill attaches a provenance ledger entry to each draft. This entry records the Agent’s identifier, the operation timestamp, and a SHA-256 checksum of the content.

This cryptographic fingerprinting ensures that later audits can verify the saved data has not been tampered with. The ledger creation logic lives in claude_obsidian/ledgers.py, specifically within the create_ledger_entry() function. This stage fulfills the contractual requirement for honest evidence preservation in AI-generated content systems.

3. Build One Save Transaction: Atomic Bundle Construction

All prepared drafts are bundled into a single Save transaction object. This transaction records the expected SHA-256 hash of every target file, enabling a "read-before-write" safety check that prevents overwriting external modifications.

The bundle is written to a temporary staging area and passed to the transaction engine for validation. This stage is documented in the "Build one Save transaction" section of skills/save/SKILL.md and implemented by the Transaction class in claude_obsidian/transaction.py. The transaction format follows the claude-obsidian.transaction.v1 specification.

4. Preview and Apply: Diff Rendering and Atomic Commitment

The user or calling script is presented with a diff-style preview of every change that would be applied. This human-readable output clearly shows additions, deletions, and modifications before any commitment occurs.

After explicit confirmation, the transaction commits atomically: staging files replace the originals, ledger entries append to wiki/meta/ledgers/, and the vault’s index refreshes. If any step fails, the entire transaction aborts, leaving the vault untouched. The commit logic resides in claude_obsidian/transaction.py, while the CLI rendering utilities live in claude_obsidian/cli.py.

Core Implementation Files and Classes

The save workflow spans several critical files that handle distinct responsibilities:

• skills/save/SKILL.md — Human-readable specification defining the four workflow stages (Prepare, Preserve evidence, Build transaction, Preview & apply) and their contractual obligations.
• claude_obsidian/transaction.py — Contains the Transaction class that aggregates drafts, validates hashes, renders previews via the preview() method, and executes atomic commits through apply().
• claude_obsidian/ledgers.py — Implements create_ledger_entry() to generate provenance records with agent identifiers and cryptographic checksums.
• claude_obsidian/cli.py — Parses command-line arguments for the save skill and forwards them to the transaction engine.
• wiki/meta/ledgers/ — Directory where generated ledger files persist, providing the immutable audit trail required for forensic verification.

Programmatic and CLI Usage Examples

You can invoke the save workflow programmatically using the Transaction class or via the command-line interface.

The following Python example demonstrates the complete pipeline:

from claude_obsidian.transaction import Transaction
from claude_obsidian.ledgers import create_ledger_entry

# 1. Prepare drafts (adding a new note)

drafts = {
    "wiki/ideas/new-concept.md": "# New Concept\n\nDescription of the idea."

}

# 2. Preserve evidence with ledger entry

ledger = create_ledger_entry(
    agent_id="my-agent",
    operation="save",
    targets=list(drafts.keys())
)

# 3. Build atomic transaction

tx = Transaction(drafts=drafts, ledger=ledger)

# 4. Preview changes (renders diff)

tx.preview()

# 5. Apply with confirmation

if tx.confirm():
    tx.apply()
    print(f"Saved! Transaction ID: {tx.id}")

For command-line usage, the skill exposes a direct interface:

# CLI invocation with inline draft and preview flag

claude-obsidian save \
  --draft wiki/notes/todo.md="## TODO\n- [ ] Write article" \

  --preview

Summary

• The save workflow implements a four-stage atomic pipeline that guarantees consistency across vault modifications.
• SHA-256 checksums and provenance ledgers in wiki/meta/ledgers/ provide cryptographic auditability for every write operation.
• The Transaction class in claude_obsidian/transaction.py manages staging, preview rendering, and atomic commitment.
• All drafts validate paths and structure during the Prepare phase before any disk writes occur.
• The system requires explicit user confirmation after showing a diff-style preview, ensuring human oversight of AI-generated changes.

Frequently Asked Questions

How does claude-obsidian prevent partial or corrupted saves?

The repository implements atomic transactions through the Transaction class. All changes stage to a temporary area first; the apply() method only moves files to the vault after successful validation of all hashes and ledger entries. If any verification fails, tx.apply() aborts and the vault remains untouched, preventing partial writes.

What information is stored in the provenance ledger?

Each ledger entry created by create_ledger_entry() in claude_obsidian/ledgers.py stores the Agent identifier, operation type ("save"), target file paths, operation timestamp, and SHA-256 checksums of the content. These entries append to wiki/meta/ledgers/ and provide immutable forensic evidence of who modified what and when.

Where does the save workflow store files before committing them?

The workflow writes bundles to a temporary staging area during the "Build one Save transaction" stage. This staging location holds the transaction bundle (following the claude-obsidian.transaction.v1 format) until the user confirms the diff preview. Only upon confirmation does the transaction engine move files from staging to their final vault locations.

Can the save workflow run without interactive confirmation?

While the default behavior calls tx.confirm() to require human approval, programmatic usage can bypass the interactive prompt by directly invoking tx.apply() after manual verification logic. However, the core design emphasizes human-in-the-loop control, and the CLI always requires the --preview review step before --apply execution according to the implementation in claude_obsidian/cli.py.

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