Grim 📖 (Grimoire)

A lightweight, high-performance CLI tool for managing secure, encrypted Markdown note vaults for Obsidian, VS Code, Vim, and other text editors.

Powered by filippo.io/age (X25519 Master Key Architecture + Scrypt KDF) and written in pure Go.

💖 Acknowledgments & Credits

• Filippo Valsorda — Author and creator of the age encryption tool and format.
• Steve Francia (spf13) & contributors — Creators of the Cobra CLI framework.
• fsnotify Team — High-performance filesystem event notifications for Go.
• Go Community & The Go Authors (Google) — For the elegance, speed, and standard library of the Go language.
• Antigravity (Google DeepMind) — AI pair programmer & co-creator of the Grim codebase and architecture.

---

📜 Origin & Name

Grim is short for Grimoire (*\ɡrɪmˈwɑːr*).

Historically, a grimoire is a textbook of magic, secret knowledge, and esoteric recipes, traditionally kept under lock and key by scholars and practitioners.

In the digital era, Grim serves as the modern cryptographic grimoire for developers, security researchers, and note-takers: a personal sanctuary to hold your most sensitive thoughts, infrastructure credentials, server keys, and private journals — invisible to the operating system's disk, and unlocked only in temporary volatile memory.

---

🌟 Key Features

• Dedicated Obsidian Integration: Automatic vault registration in obsidian.json, native URL protocol handling (obsidian://open?path=...), sandbox awareness (Flatpak/Snap), and compatibility with Graph View, Canvas, Wikilinks, images/screenshots, and plugins.
• Editor Support: Works with Vim, Neovim, VS Code, Helix, Nano, Micro, Sublime Text, Emacs, and custom editors.
• X25519 Master Key Architecture: Instantaneous vault unlock and microsecond file saves, regardless of vault size (10 or 10,000 notes).
• Age Encryption: Modern file-level encryption using age (Scrypt KDF protects the master key metadata).
• Isolated Volatile Memory: Unlocks files directly into RAM (tmpfs / isolated memory cache), never writing plaintext notes to physical SSD/HDD.
• Continuous Live Sync: Uses fsnotify to detect file saves and immediately auto-encrypts changes to .age files on physical disk.
• Auto-Lock & Multi-Pass Memory Wipe: Closes the session on timeout, Ctrl+C, lock command, or editor exit, and overwrites RAM files with zeroes and random bytes before unmounting.
• Interactive Setup Wizard: Built-in grim setup wizard to configure editors, auto-lock timeouts, and re-encrypt vaults.
• Git-Friendly: Because each note is encrypted to its own .md.age file, you can easily use Git (git init, git commit, git push) to sync your encrypted vault.

---

🔮 Obsidian & Editor Ecosystem

While Grim works with various text editors and IDEs, it provides dedicated integration for Obsidian:

💎 Why Grim is a Good Encrypted Backend for Obsidian:

• Zero Plugins Required: No third-party Obsidian community plugins needed inside your vault. Encryption runs externally via pure Go and age.
• Native Obsidian Features: Because notes live as a standard folder structure in volatile memory during your session, core Obsidian capabilities work naturally:
  • 🕸️ Graph View & Canvas
  • 🔗 Wikilinks ([[note-name]]) & Tag indexing (#tag)
  • 🖼️ Attachments & Screenshots: Paste images directly (Ctrl+V), embed PDFs, or store audio memos — encrypted automatically.
  • 🧩 Community Plugins & Themes: Settings in .obsidian/ are preserved and synchronized.
• Automated obsidian.json Registry: Grim injects the active RAM workspace into Obsidian's known vaults list on launch, and cleans it up upon lock, so you don't have to manually browse or import folders.
• Sandbox & Flatpak Awareness: Automatic environment detection handles Native Linux packages, Flatpak sandboxes, Snap, macOS app bundles, and Windows.

---

📋 Command Cheat Sheet

Action	Command	Alias	Description
Open Vault	grim [vault]	—	Decrypt to RAM and launch editor
List Vaults	grim list	grim ls	Show configured vaults and lock status
Settings Wizard	grim setup	—	Interactive configuration wizard
Discover / Attach	grim add [dir]	grim a	Scan disk or attach existing vault
Lock Vault	grim lock [vault]	—	Wipe in-memory workspace immediately
Status	grim status	grim st	Check active RAM sessions
Remove Vault	grim remove <vault>	grim rm	Remove vault from configuration
Create Vault	grim init <vault> <dir>	—	Initialize a new encrypted vault

---

🚀 Quick Start

1. Build & Install

Via go install (Recommended):

go install github.com/ijin82/grim/cmd/grim@latest

Or build from source:

# Build the binary
go build -o grim ./cmd/grim

# Install to system PATH (~/.local/bin or /usr/local/bin)
./grim install
# or with Makefile:
make install

---

2. Initialize or Attach a Vault

Create a new vault:

grim init work ~/Documents/SecretGrimoire.enc

Or attach an existing vault (synced from Cloud/Dropbox/Git):

# Auto-scan disk for existing Grim vaults:
grim add
# or short alias:
grim a

# Or attach a specific folder directly:
grim add work ~/Dropbox/SecretGrimoire.enc

[!TIP] Smart Auto-Discovery: Running grim add without arguments (or with a parent folder) performs an instant scan of the current directory . (up to 3 levels deep) and standard cloud paths (~/Documents, ~/Dropbox, ~/Nextcloud, ~/OneDrive, ~/Sync, ~/GDrive, ~/Yandex.Disk). It identifies vaults by their .vault-meta.age signature and presents an interactive menu to attach them with a single keystroke.

---

3. Open and Start Editing

# Open specific vault:
grim work

# Or open default vault:
grim

1. Enter your master passphrase.
2. The vault is decrypted into RAM in less than a second.
3. Your editor (Obsidian / VS Code / Vim) opens automatically.
4. Every time you save a note (Ctrl+S), Grim instantly encrypts it to disk.

---

4. Lock & Safe Exit

To lock your vault and wipe the in-memory notes:

• Press Ctrl+C in the terminal, or
• Type lock (or q) and press Enter, or
• For terminal editors (like vim/nvim): simply exit the editor (:wq / :q), or
• Wait for the auto-lock timeout (default: 30 minutes).

---

🛠️ Settings & Setup Wizard (grim setup)

Launch the interactive configuration wizard:

grim setup

Interactive Menu:

📖 Grim Setup & Settings
==================================================
1) Select Default Editor      (current: obsidian)
2) Change Auto-lock Timeout
3) Change Vault Master Passphrase (re-encrypt)
4) Configure Specific Vault Settings
5) Set Default Vault          (current: work)
0) Exit
==================================================
Choose option [0-5]:

Direct CLI Commands

# Interactive setup for a specific vault (editor & timeout):
grim setup work

# Set global default editor:
grim setup editor vim
grim setup editor code

# Change master passphrase for a vault:
grim setup passwd work

# Set default auto-lock timeout (in minutes):
grim setup timeout 20

# Directly set editor for a specific vault:
grim setup work code

---

⚡ Shell Autocompletion (Tab)

Grim supports full shell autocompletion for subcommands and vault names.

Bash

# Enable permanently for all new sessions:
echo 'source <(grim completion bash)' >> ~/.bashrc

Zsh

# Enable permanently:
echo 'source <(grim completion zsh)' >> ~/.zshrc

Fish

grim completion fish > ~/.config/fish/completions/grim.fish

---

💻 Cross-Platform Support & OS Nuances

Grim is written in pure Go without CGO dependencies and runs natively on Linux, macOS, and Windows.

Feature	🐧 Linux	🍎 macOS	🪟 Windows
Config Location	~/.config/grim/config.yaml	~/.config/grim/config.yaml	%APPDATA%\grim\config.yaml
RAM Workspace Path	/run/user/$UID/grim (tmpfs RAM)	~/Library/Caches/grim	%LOCALAPPDATA%\grim\cache
Workspace Permissions	0700 (Owner-only)	0700 (Owner-only)	User profile ACLs
Obsidian Integration	Native, Flatpak & xdg-open	open "obsidian://open?..."	cmd.exe /c start "obsidian://..."
VS Code Command	code <path>	code <path>	code.cmd <path>
Terminal Editors	vim, nvim, nano, micro, hx	Terminal / iTerm2 (vim, nvim)	PowerShell / Git Bash (vim, nvim)

🍎 macOS Notes:

• VS Code CLI: If code isn't found in your Terminal, open VS Code, press Cmd+Shift+P, and run "Shell Command: Install 'code' command in PATH".
• Obsidian: Works automatically out of the box via macOS URL scheme registration.
• Homebrew / PATH: Run ./grim install or make install to place the binary in ~/.local/bin or /usr/local/bin.

🪟 Windows Notes:

• PowerShell Autocompletion:

  grim completion powershell | Out-String | Invoke-Expression
  

  (To make permanent, add the line above to your $PROFILE).
• File Locking & Antivirus: Grim uses a 50ms debounced atomic writer (.tmp + atomic rename) to avoid file lock collisions with Windows Defender or background indexing services.
• Terminal Vim: Terminal editors run natively in Windows Terminal, PowerShell, and Git Bash.

---

📋 Commands Summary

• grim [vault] — Unlock vault into RAM, start sync, launch editor.
• grim init <vault> <dir> — Create a new encrypted vault.
• grim add [vault] [dir] (or grim a) — Attach existing vault or auto-discover from disk.
• grim list (or grim ls) — List all configured vaults and their status.
• grim status (or grim st) — View active unlocked vaults in RAM.
• grim lock [vault] — Force lock and wipe RAM workspace.
• grim remove <vault> (or grim rm) — Remove vault from configuration.
• grim setup — Interactive configuration wizard (editor, timeout, passphrase).
• grim setup [vault] — Interactive settings for a specific vault.
• grim set-default <vault> — Set the default vault.
• grim install — Install grim binary into system $PATH.
• grim completion [bash|zsh|fish|powershell] — Generate shell autocompletion script.