Libra VCS for Obsidian

Version-control your Obsidian vault with Libra — the AI-agent-native, Git-compatible version control system. This plugin recognizes when your vault lives inside a Libra repository (a .libra/ directory) and brings Libra's everyday VCS workflow and its AI-native features directly into Obsidian.

Libra is desktop-only software, so this plugin requires the Obsidian desktop app (it shells out to the libra binary).

Features

Source control (Git-compatible surface)

• Source Control view (right sidebar) — current branch, ahead/behind vs upstream, and grouped Staged / Changes lists.
• Stage / unstage / discard individual files or everything at once.
• Commit box with a configurable message template (Ctrl/Cmd+Enter to commit).
• Sync / Push / Pull / Fetch with progress notices and friendly Libra error codes surfaced on failure.
• Branching — fuzzy "switch branch" picker and "create branch".
• Per-file actions — view diff, open in Obsidian, file history, and blame.
• Commit history view with inline, color-coded diffs (click a commit to expand).
• Status-bar indicator — branch, dirty-file count, ahead/behind.
• Auto-refresh on file changes and an optional auto-commit timer.

Libra AI-native features

The Libra Code (AI) view exposes what makes Libra different from a vanilla Git client:

• AI Code — launches libra code --web (the AI runtime) bound to localhost and embeds its UI in an Obsidian pane. Choose provider/model and an env file for API keys in settings.
• Usage — token and cost accounting from libra usage report.
• Automation — list libra automation rules and run them (dry-run or live).
• Publish — inspect libra publish status (read-only Cloudflare Worker publishing).

How repository detection works

On load, the plugin walks up from the vault folder looking for a .libra entry (a directory, or — for repos created with --separate-libra-dir — a pointer file). If found, the repository root becomes the working directory for every libra invocation. If not found, the Source Control view offers to run libra init for you.

Note: Libra operates at the repository root. If your vault is a subfolder of a larger Libra repo, "Stage all" and auto-commit act on the whole repository, not just the vault subtree. For vault-scoped version control, make the vault folder itself the repository root.

Requirements

• Obsidian desktop 1.5.0+

• The libra binary installed and on your PATH, or its absolute path set in settings. Install it with:

  curl --proto '=https' --tlsv1.2 -sSf https://download.libra.tools/install.sh | sh

  The plugin also probes common install locations (~/.libra/bin/libra, /usr/local/bin, /opt/homebrew/bin) because GUI apps often launch with a minimal PATH.

Settings

Setting	What it does
Libra executable path	Absolute path to libra (empty = resolve from PATH).
Commit message template	Prefilled commit message; {{date}} expands to now.
Stage everything on commit	Run libra add -A before committing from the box.
Pull before push when syncing	The Sync command runs pull then push.
Refresh on file change	Re-read status shortly after notes change.
Auto-refresh interval	Periodic status refresh (0 = off).
Auto-commit interval	Periodically stage + commit the whole vault (0 = off).
Show status-bar indicator	Branch + dirty count in the status bar.
Libra Code host / port	Where libra code --web binds for the embedded UI.
AI provider / model	Passed to libra code as --provider / --model.
Provider env file	dotenv file with provider keys (--env-file).

Commands

All commands are available from the command palette under Libra: Open source control / history / Libra Code, Refresh, Commit…, Stage all, Sync, Push, Pull, Fetch, Switch/Create branch, Diff/History/Blame current file, Start/Stop Libra Code server, Publish: show status.

Development

npm install
npm run dev      # watch-build to main.js
npm run build    # typecheck + production bundle

The bundle entry point is src/main.ts; output is main.js at the plugin root (loaded by Obsidian alongside manifest.json and styles.css). To test in a vault, symlink or copy this folder into <vault>/.obsidian/plugins/libra-vcs/.

License

MIT © Libra