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

> Discover the claude-obsidian save workflow. Learn how its 4-stage atomic pipeline ensures validated, auditable, and user-confirmed vault modifications before commitment.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: internals
- Published: 2026-08-28

---

**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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/skills/save/SKILL.md) and the draft collection logic within [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/skills/save/SKILL.md) and implemented by the `Transaction` class in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py), while the CLI rendering utilities live in [`claude_obsidian/cli.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/cli.py).

## Core Implementation Files and Classes

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

- **[`skills/save/SKILL.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py)** — Implements `create_ledger_entry()` to generate provenance records with agent identifiers and cryptographic checksums.
- **[`claude_obsidian/cli.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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:

```python
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:

```bash

# 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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/cli.py).