Crumbs

Crumbs is a keyboard-driven personal productivity system for the terminal. It manages tasks, notes/agendas, a calendar, and people in one interface, and supports bidirectional cross-references between them. Data is stored locally in a SQLite database, no services or accounts needed.

The core of the app's design is based on my vim setup from grad school many years ago -- a minimalist, distraction-free environment that helped me jot down and organize fleeting thoughts and ideas before I forgot them. Use Crumbs either through the terminal app, or via scripted/agentic workflows using the CLI to store and organize information.

Quick Start

You'll need Rust, Neovim, and a Nerd Font configured in your terminal.

brew install rust neovim
cargo install --git https://github.com/rsmenon/crumbs.git
crumb

Press ? from anywhere for the keybinding reference. Press q to quit.

crumb                       # launch the TUI
crumb --vault=work          # launch with a separate work vault
crumb task add "Buy milk"   # JSON CLI
crumb today                 # today's tasks, notes, and agendas

Guides

Guide	What it covers
Getting Started	Installation, navigation, your first five minutes
Tasks	Creating, editing, filtering, archiving, and prioritising work
Notes	Free-form writing, tagging, and the embedded Neovim editor
Calendar	The three-pane month view and scheduling by date
People	Collaborators, per-person agendas, and mention timelines
Quick Capture	The sink: getting thoughts in without switching context
Linking	Cross-references, the ref explorer, pinning, backlinks
CLI Reference	The JSON command-line API for scripts and agents

Data

Everything crumbs knows about lives in ~/.crumb/:

~/.crumb/
├── crumbs.db        # default SQLite database
├── settings.yaml    # configuration file
└── <name>.db        # named vault databases

The database is a regular SQLite file — back it up by copying it, inspect it with sqlite3, or sync it with any file-sync tool. Don't run two crumbs processes against the same file simultaneously.

settings.yaml is created on first launch with commented defaults:

data_dir: /Users/you/.crumb

palette:
  # Accent colors
  blue:   '#458588'   # todo status
  aqua:   '#689d6a'   # accent highlights, @person mentions
  yellow: '#d79921'   # in-progress status, due dates within 3 days
  red:    '#cc241d'   # errors, high priority, blocked, overdue
  green:  '#98971a'   # success, done status
  orange: '#d65d0e'   # warnings, medium priority
  purple: '#b16286'   # #topic tags, private entries
  # Backgrounds
  bg0:          '#282828'
  bg1:          '#3c3836'
  bg2:          '#504945'
  bg_col_focus: '#665c54'
  # Foregrounds
  fg0:    '#ebdbb2'
  fg4:    '#a89984'
  fg_dim: '#7c6f64'

Override data_dir to store your data on an encrypted volume, in iCloud Drive, or anywhere else on the filesystem. Edit any palette color (must be #rrggbb format) to retheme the app — invalid values fall back to the defaults shown above. Keybindings are not configurable.

Vaults

A vault is a separate database file. Pass --vault=<name> to use <name>.db in data_dir:

crumb --vault=work          # ~/.crumb/work.db
crumb --vault=personal      # ~/.crumb/personal.db
crumb --vault=work task list  # CLI also accepts --vault

Named vaults are created automatically on first use. Vaults are fully isolated — links, tags, people, and search results never cross between them.

Updating

cargo install --git https://github.com/rsmenon/crumbs.git --force

Schema migrations run automatically on the next launch.