SnapCodex

Capture thoughts in seconds. Organize knowledge for years.
A portable, zero-friction note-taking app with voice capture, automatic Git sync, and Obsidian integration.

Features • Quick Start • Usage • Architecture • Roadmap • Contributing • License

---

Why SnapCodex?

Most note apps make you open an app, navigate menus, create a file, then type. By the time you're ready, the idea is gone.

SnapCodex eliminates that friction:

• < 1 second to open from hotkey — assign to any keyboard shortcut or launcher, the capture window appears instantly
• < 1 second to close — press ESC (text) or Space (voice) and the window vanishes. Saving, transcription, and Git sync happen invisibly in background (~3s for text, ~10s for voice)
• 0 accounts required — portable .exe, no sign-up, no cloud lock-in. Works 100% offline as a local notepad. Add a free Gemini API key to unlock voice transcription

Your notes are plain Markdown files in a Git repo. Open them in Obsidian, VS Code, or any text editor. Your data is always yours.

"Strategic generosity builds empires. Stinginess builds walls." "A generosidade estratégica constrói impérios. A mesquinharia constrói muros."

---

Features

⚡ Quick Capture

Press a hotkey → a minimal dark window appears instantly → type your thought → press ESC → window closes immediately.
In the background: saved as .md with automatic timestamped filename, committed to Git, and pushed — you never see any of this.

🎤 Voice Capture

Press a hotkey → window appears with mic ready → press Space to start recording → speak → press Space again → window closes instantly.
In the background: audio is sent to Gemini API, transcribed, polished into structured Markdown, saved as two notes (raw + organized), committed and pushed. Hands-free capture for when you're away from the keyboard.

Note: Voice capture requires a free Gemini API key. Without it, SnapCodex works as a full-featured local notepad with Git sync — no transcription.

🔄 Automatic Git Sync

A background daemon handles commit + push automatically. Every note is versioned from the moment it's created. Full history, diffs, and rollback — powered by Git.

🔒 Secure by Design

• API keys encrypted with AES-256-GCM (stored locally, never transmitted)
• No telemetry, no analytics, no cloud accounts
• Portable .exe (~7MB) — runs from a USB drive if you want

📁 Obsidian-Ready

Notes are plain Markdown with YAML frontmatter. Point your Obsidian vault to the same folder and get:

• Graph View — visualize connections between ideas
• Backlinks — bidirectional [[links]] between notes
• Search — full-text + tag-based search across your knowledge base
• Templates — standardized note formats

SnapCodex captures. Obsidian organizes. Both read/write to the same folder.

---

Quick Start

Prerequisites

• Windows 10/11
• Git installed and configured
• (Optional) Gemini API key for voice capture

Installation

1. Download snapcodex.exe from Releases
2. Place it anywhere (Desktop, USB drive, wherever)
3. Run it — no installation required

First Run

# Open the full editor
snapcodex.exe

# Quick capture (hotkey mode)
snapcodex.exe --quick

# Voice capture
snapcodex.exe --voice

On first launch, a setup wizard appears to configure your notes repository, Git settings, and optionally your Gemini API key. No terminal commands needed — everything is done through the interface.

---

Usage

Modes

Mode	Command	What it does
Full	snapcodex.exe	Opens the complete editor with sidebar, note management, and settings
Quick	snapcodex.exe --quick	Minimal dark popup → type → ESC → closes instantly, saves in background
Voice	snapcodex.exe --voice	Space to record → Space to stop → closes instantly, transcribes in background

Keyboard Shortcuts

Shortcut	Context	Action
ESC	Quick mode	Save and close — note is saved, Git sync runs in background
ESC	Voice mode	Cancel recording and close
Space	Voice mode	Toggle recording (start/stop). Stopping closes the window and transcribes in background
Ctrl+S	Full mode	Save current note

Setting Up Voice Capture

1. Open SnapCodex in Full mode
2. Go to Settings → API Key
3. Paste your Gemini API key
4. The key is encrypted locally with AES-256-GCM

Setting Up Git Sync

1. Create a private repo on GitHub (or any Git host)
2. Configure the remote in SnapCodex Settings
3. Sync runs automatically in the background (commit + push)

Obsidian Integration

1. Install Obsidian (free)
2. Create a vault pointing to the same folder SnapCodex uses for notes
3. That's it — every note captured by SnapCodex appears instantly in Obsidian

---

Architecture

┌──────────────────────────────────────────────────┐
│  CAPTURE LAYER (zero friction)                   │
│                                                  │
│  ⚡ --quick → text note in 3 seconds             │
│  🎤 --voice → record → transcribe → save         │
│  📝 Full editor for longer notes                 │
└──────────────────┬───────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────┐
│  STORAGE LAYER (plain files)                     │
│                                                  │
│  📁 Local folder with .md files                  │
│  📄 YAML frontmatter (created, source, tags)     │
│  📂 _inbox/ for unprocessed captures             │
└──────────────────┬───────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────┐
│  SYNC LAYER (automatic)                          │
│                                                  │
│  🔄 Git auto-commit + push (background daemon)   │
│  🐙 GitHub/GitLab/any remote for backup          │
│  📜 Full version history for every note          │
└──────────────────────────────────────────────────┘

Tech Stack

Component	Technology
Language	Rust
GUI	egui (native, no Electron)
Transcription	Gemini API (user's own key)
Sync	Git (automatic commit + push)
Encryption	AES-256-GCM (API keys)
Binary	Single .exe, ~7MB, portable

---

Roadmap

• Quick Capture (--quick) — ESC to save & close
• Voice Capture (--voice) — Space to record/stop, auto-close
• Automatic Git Sync (background daemon)
• API Key Encryption (AES-256-GCM)
• Portable single-binary distribution
• First-run setup wizard (no terminal needed)
• YAML frontmatter on generated notes
• Inbox folder (_inbox/) for captured notes
• Obsidian integration guide & templates
• System tray with quick-access menu

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes
4. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

---

License

This project is licensed under the MIT License — see LICENSE for details.

---

_{Built with 🦀 Rust and ❤️ by Marlon Motta
Just a human trying to help other humans learn better.
Apenas um humano tentando ajudar outros humanos a aprender melhor.}