{"id":35885909,"url":"https://github.com/oshtz/brainbox","last_synced_at":"2026-06-06T22:01:02.992Z","repository":{"id":331932436,"uuid":"1130695646","full_name":"oshtz/brainbox","owner":"oshtz","description":"local-first desktop app to capture, organize, and search links \u0026 notes ","archived":false,"fork":false,"pushed_at":"2026-06-04T20:40:55.000Z","size":1361,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2026-06-04T22:10:14.781Z","etag":null,"topics":["knowledge-management","notes","personal-knowledge-base"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oshtz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-08T21:55:10.000Z","updated_at":"2026-06-04T20:41:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oshtz/brainbox","commit_stats":null,"previous_names":["oshtz/brainbox"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/oshtz/brainbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oshtz%2Fbrainbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oshtz%2Fbrainbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oshtz%2Fbrainbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oshtz%2Fbrainbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oshtz","download_url":"https://codeload.github.com/oshtz/brainbox/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oshtz%2Fbrainbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34001197,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["knowledge-management","notes","personal-knowledge-base"],"created_at":"2026-01-08T20:15:32.896Z","updated_at":"2026-06-06T22:01:02.981Z","avatar_url":"https://github.com/oshtz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# brainbox\n\nLocal‑first capture, organize, and search for links and notes. brainbox is a desktop app built with Tauri (Rust) and React that keeps your data on your machine, with fast full‑text search and handy capture flows.\n\n\u003e **⚠️ EDUCATIONAL/LEARNING PROJECT**\n\u003e This is an open source learning project demonstrating desktop app development with Tauri, React, and Rust. It is **NOT intended for production use** with sensitive data.\n\n\u003e **📚 Purpose**\n\u003e brainbox serves as a comprehensive example of:\n\u003e - Building cross-platform desktop apps with Tauri 2\n\u003e - Implementing full-text search with Tantivy\n\u003e - Local-first data storage with SQLite\n\u003e - Client-side encryption with proper key derivation\n\u003e - React + TypeScript frontend architecture\n\u003e - Auto-updates and protocol handlers\n\n## Features\n\n- Vaults: create, rename, cover images, delete, and reorder items per vault.\n- Capture: add notes or URLs; auto-detects URLs and enriches with OpenGraph metadata.\n- Previews: YouTube thumbnails, site favicon, and title/description extraction.\n- Search: local full‑text search powered by Tantivy (BM25 ranking).\n- AI (brainy): intelligent assistant with tool calling capabilities — can create notes, search vaults, fetch web content, and organize items. Supports multiple providers (Ollama, OpenAI, Anthropic, Google, OpenRouter).\n- Hotkey: global capture hotkey (Windows) to pop open the capture modal.\n- Protocol: `brainbox://capture?url=...\u0026title=...` handler (Windows) for one‑click sends.\n- Tray: system tray icon with show/hide/quit actions.\n- Auto-Updates: seamless updates via GitHub releases.\n- Local‑first: data stored in a local SQLite database; no cloud required.\n\n## Tech Stack\n\n- Desktop: Tauri 2 (Rust), plugins: global_shortcut, shell, single_instance, updater.\n- Backend: Rust (`rusqlite`, `tantivy`, `reqwest`, `quick-xml`, `chacha20poly1305`).\n- Frontend: React 18, TypeScript, Vite.\n- Styling: CSS tokens, themes, and custom component library.\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 18+ with Corepack/pnpm.\n- Rust (stable) and Tauri system prerequisites for your OS:\n  - Windows: Visual Studio Build Tools, WebView2.\n  - macOS: Xcode Command Line Tools.\n  - See: https://tauri.app/start/prerequisites/\n\n### Install\n\n#### For Development\n\n```bash\ncorepack enable\npnpm install\n```\n\n#### For End Users\n\n**Download from Releases**\n\n1. Go to [GitHub Releases](https://github.com/oshtz/brainbox/releases)\n2. Download the appropriate artifact for your platform:\n   - **Windows**: `brainbox-portable.exe`\n   - **macOS**: `.dmg` file (Apple Silicon M1/M2/M3+ only)\n\n**macOS Installation Instructions**\n\nDue to Apple's security requirements, unsigned apps show security warnings. Follow these steps:\n\n1. **Download the DMG** from the releases page\n2. **Open the DMG** and drag brainbox to Applications\n\n**If you see \"brainbox is damaged and can't be opened\":**\n\nThis is a common issue with unsigned apps. Try these solutions in order:\n\n**Method 1: Remove Quarantine (Recommended)**\n```bash\nxattr -dr com.apple.quarantine /Applications/brainbox.app\n```\n\n**Method 2: Disable Gatekeeper Temporarily**\n```bash\nsudo spctl --master-disable\n# Launch the app, then re-enable:\nsudo spctl --master-enable\n```\n\n**Method 3: Allow Specific App**\n```bash\nsudo spctl --add /Applications/brainbox.app\nsudo spctl --enable /Applications/brainbox.app\n```\n\n**Method 4: Right-click Method**\n1. Right-click the app in Applications and select \"Open\"\n2. Click \"Open\" when macOS asks for confirmation\n\n**If none of the above work:**\n- Try downloading the DMG again (it might have been corrupted)\n- Check that you're using an Apple Silicon Mac (M1/M2/M3+)\n- Report the issue on GitHub with your macOS version\n\n\u003e **Note**: brainbox is an open source project and the macOS version is unsigned to avoid requiring Apple Developer credentials. These security warnings are normal for unsigned apps.\n\n### Run (desktop)\n\n```bash\npnpm tauri dev\n```\n\nVite is configured for Tauri at `http://127.0.0.1:1420` with strict port matching.\n\n### Run (web only)\n\n```bash\npnpm dev\n```\n\nThis runs the frontend in a browser without Tauri backend features.\n\n### Build (desktop)\n\n```bash\npnpm tauri build\n```\n\nBuild artifacts (installers/bundles) are created via Tauri for your platform.\n\n### Verify\n\n```bash\npnpm run verify\n```\n\nThis runs the frontend production build, unit tests, and Playwright smoke tests.\n\n### Desktop Smoke\n\n```bash\npnpm run smoke:tauri\n```\n\nThis builds the real Tauri debug binary without bundling, starts the Vite dev server it expects, launches the desktop app with an isolated temporary `BRAINBOX_DATA_DIR`, verifies that the app initializes its SQLite DB and search index, then closes both processes.\n\nRelease gates and manual desktop QA are tracked in [docs/release-readiness.md](docs/release-readiness.md).\n\n### Auto-Updates\n\nbrainbox includes an automatic update system that keeps your app current without manual downloads:\n\n- **Automatic Checks**: App silently checks for updates on startup\n- **Manual Control**: Check for updates anytime in Settings → App Updates\n- **Simple Artifacts**: macOS updates use the release DMG, and Windows updates use the portable EXE\n- **Cross-Platform**: Works on Windows and macOS\n- **Non-Intrusive**: You choose when to install updates\n\n## Usage\n\n### Create a Vault\n\n- Launch the app and create a new vault from the UI.\n- Each vault stores items (notes/URLs) encrypted at rest in a local SQLite DB.\n\n### Add Items\n\n- Click Capture to add a note or paste a URL.\n- URLs get enriched with title/description and a preview image when available.\n- YouTube links automatically use a high‑quality thumbnail.\n\n### Search\n\n- Use the search bar to find items across vaults via Tantivy full‑text search.\n\n### AI (brainy)\n\nbrainy is an intelligent assistant built into brainbox with full tool calling capabilities.\n\n**Features:**\n- Summarize notes and captured links automatically\n- Create, update, and organize vault items via natural language\n- Search across your vaults\n- Fetch and process web content and YouTube transcripts\n- Move items between vaults\n\n**Supported Providers:**\n\n| Provider | Type | Tool Calling |\n|----------|------|--------------|\n| Ollama | Local | Prompt-based |\n| LM Studio | Local | Prompt-based |\n| OpenAI | Cloud | Native |\n| Anthropic | Cloud | Native |\n| Google Gemini | Cloud | Native |\n| OpenRouter | Cloud | Native |\n\n**Setup:**\n- Configure under Settings → AI: select a provider and enter credentials if needed.\n- For local AI (Ollama): set Base URL (default `http://127.0.0.1:11434`) and choose a Model (e.g., `llama3.2`, `mistral`, `qwen2.5`).\n- For cloud providers: enter your API key and select a model.\n- Customize the system prompt to tune brainy's writing style.\n\n**Usage:**\n- Click the brainy button (sparkles icon) in the sidebar to open the chat panel.\n- Ask brainy to perform actions like \"create a new note about project ideas\" or \"search for notes about recipes\".\n- brainy will execute tools automatically and confirm completed actions.\n\n### Capture Flows\n\n- Global Hotkey (Windows): default `Alt+Shift+B` toggles the capture modal.\n- Custom Protocol (Windows): open `brainbox://capture?url={URL}\u0026title={TITLE}` to send the current page to brainbox. The app registers the protocol under the current user.\n- Bookmarklet: use `examples/bookmarklet-direct.js` to copy the current page’s `{url,title}` as JSON to the clipboard; then paste into brainbox’s capture field.\n- Bridge Page: `examples/brainbox-bridge.html` is a small page that redirects to the brainbox protocol; you can host/use it to create links that trigger the app.\n\n## Data \u0026 Security\n\n- Storage: database file is created at the OS \"local app data\" directory as `brainbox.sqlite`.\n  - Windows: `%LOCALAPPDATA%` (e.g., `C:\\\\Users\\\\\u003cyou\u003e\\\\AppData\\\\Local`).\n  - macOS: `~/Library/Application Support`.\n- Index: search index stored under `search_index/` in the same directory.\n- Encryption: uses XChaCha20‑Poly1305 (32‑byte key) for item content and vault passwords.\n  - **✅ Security Update (v0.0.1)**: Encryption keys are now properly derived from user passwords using PBKDF2 with 100,000 iterations and vault-specific salts.\n  - Keys are derived on-demand and cached in memory during the session for performance.\n  - Keys are automatically cleared when vaults are closed or the app exits.\n  - New sync exports require a sync file passphrase and wrap vault names, item titles, content, summaries, covers, and device name in an encrypted envelope. Legacy plaintext sync files can still be imported for migration.\n  - Standalone capture files are not exported by encrypted sync because they sit outside the sync JSON envelope.\n  - **⚠️ Educational Purpose**: This implementation demonstrates proper cryptographic practices but is intended for learning. For production use with sensitive data, additional security measures would be required:\n    - Hardware-backed key storage (TPM, Secure Enclave)\n    - Biometric authentication\n    - Key rotation mechanisms\n    - Professional security audit\n    - Secure key backup and recovery\n  - AI can run locally via Ollama or LM Studio for fully offline operation. Cloud providers (OpenAI, Anthropic, Google, OpenRouter) are also supported. Leaving AI unconfigured keeps brainbox fully offline.\n\n## OS Support\n\n| Platform | Status | Notes |\n|----------|--------|-------|\n| **Windows** | Full Support | Global hotkey, protocol handler |\n| **macOS** | Core Features | App runs, hotkey/protocol pending |\n\n## Project Layout\n\n```\nbrainbox/\n├─ src/                    # React app (UI, components, contexts, utils)\n│  ├─ components/          # UI components (BrainyChat, Sidebar, etc.)\n│  └─ utils/ai/            # AI service layer\n│     ├─ service.ts        # Unified AI provider management\n│     ├─ types.ts          # TypeScript interfaces\n│     ├─ tools.ts          # Tool definitions for brainy\n│     ├─ toolExecutor.ts   # Maps tools to Tauri commands\n│     ├─ agentLoop.ts      # Hybrid native/prompt-based agent loop\n│     └─ providers/        # Provider implementations (Ollama, OpenAI, etc.)\n├─ src-tauri/              # Tauri (Rust) backend, commands, tray, protocol\n│  ├─ src/lib.rs           # Main Tauri builder and command registration\n│  ├─ src/sync_commands.rs # Sync command wrappers\n│  ├─ src/paths.rs         # App data path helpers\n│  ├─ src/vault.rs         # SQLite models for vaults and items\n│  └─ src/search.rs        # Tantivy index and search service\n├─ styles/                 # Design tokens, globals, themes\n├─ public/                 # Static assets\n├─ examples/\n│  ├─ bookmarklet-direct.js    # Clipboard-based bookmarklet\n│  └─ brainbox-bridge.html     # Protocol bridge page\n```\n\n## Scripts\n\n- `dev`: run Vite locally.\n- `tauri dev`: run desktop app in dev mode (Vite + Tauri).\n- `build`: build frontend assets.\n- `tauri build`: produce desktop bundles.\n\n## Development \u0026 Deployment\n\n### Branching Strategy\n\n- **`main` branch**: Production-ready code that triggers automatic releases\n- **`dev` branch**: Active development (default working branch)\n\n### Workflow\n\n1. Work on features in the `dev` branch\n2. Test thoroughly before merging to `main`\n3. Merge `dev` → `main` triggers automatic CI/CD pipeline\n4. GitHub Actions builds and releases for all platforms\n\nGitHub Actions can be configured to build and release for all platforms automatically.\n\n## Known Issues\n\n**Platform Support**:\n- Global hotkey: Windows only (macOS)\n- Protocol handler: Windows only (macOS)\n\n## Roadmap / Ideas\n\n- Proper key management and encryption UX.\n- Cross‑platform global hotkey and protocol support.\n- Richer previews and content extraction.\n- Import/export and backup/sync options.\n- Plugin API for custom capture/processing flows.\n\n## License\n\nMIT — see `LICENSE` for details.\n\n## Acknowledgements\n\n- Built with [Tauri](https://tauri.app/), [React](https://react.dev/), [Vite](https://vitejs.dev/), and [Tantivy](https://github.com/quickwit-oss/tantivy).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foshtz%2Fbrainbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foshtz%2Fbrainbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foshtz%2Fbrainbox/lists"}