Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install wanderer

It will make the wanderer command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall wanderer uninstalls.

Back to the crate overview.

Readme

Wanderer

A minimal, opinionated note-taking TUI.

screenshot

Philosophy

One format: YYYYMMDD-HHMM.md or YYYYMMDD-HHMM-title.md
No configuration: Just works
UNIX-friendly: Flat files, use grep to search, shell aliases for "vaults"

Install

Prerequisites

Rust (to build)
fzf (for fuzzy searching)
$EDITOR set (vim, nano, code, etc.)

Build

cargo install --path .

Ensure ~/.cargo/bin is in your PATH.

Usage

wanderer              # Opens current directory
wanderer ~/notes      # Opens specific directory

Workflow

Connecting the Dots

Wanderer stays flat by relying on LINKS and TAGS to organize information, rather than folders.

1. Lifecycle: Capture & Clarify

This workflow is built into the UI design:

Capture (Inbox)
- Press n and just hit Enter.
- Captures a thought instantly as YYYYMMDD-HHMM.md.
- Visual: Marked with a DarkGray sidebar. These are "unprocessed" notes.
Clarify (Process)
- Review your inbox notes.
- Press r to add a "slug" (e.g., meeting).
- Becomes YYYYMMDD-HHMM-meeting.md.
- Visual: Marked with a Cyan sidebar. These are "processed" or "topic" notes.
Connect (Network)
- Use [[wikilinks]] and #tags to weave topic notes together.
- Use "Standard Notes" (e.g. todo.md, projects.md) as Map of Content (MOC) or Dashboards.

2. Tagging

Just type #tagname anywhere in your note.

Inline: "Discussed #marketing strategy with team."
Footer: Add categories at the bottom: #work #meeting

Searching tags: Since tags are just text, you can search them easily.

Press t to fuzzy search tags using fzf.
Or use standard tools:

grep "#work" *.md

3. Linking

Connect notes using [[wikilinks]].

"Reference to [[20251227-2130]] regarding the project."
"See also [[Project Ideas]]."

Wanderer highlights these in the preview so you can spot connections at a glance.

Creating Notes

Press n
Type optional title (e.g., "meeting notes") or just press Enter
Note opens in $EDITOR (defaults to nvim)

Examples:

n → Enter                    → 20251227-2130.md
n → "weekly review" → Enter  → 20251227-2130-weekly-review.md
n → "Project Ideas" → Enter  → 20251227-2130-project-ideas.md

Reading Notes

j/k or arrows: Navigate file list
Select a .md file to preview with syntax highlighting
Ctrl+d/Ctrl+u: Scroll preview down/up
g/G: Jump to top/bottom of note
e: Edit in external editor

Managing Notes

r: Smart Rename.
- For timestamped notes: Edits only the "slug" (meeting -> planning), preserving the ID.
- For standard files: Renames the full filename.
- Note: Filenames are strictly enforced (lowercase, dashes, .md only).
d: Delete (confirm with y)

Markdown Support

Wanderer uses a custom markdown parser with support for:

Headers: # H1, ## H2, ### H3
Formatting: **bold**, *italic*, `inline code`
Lists: Bullet (- or *) and Numbered (1.)
Links: [[wikilinks]] and images ![alt](url)
Code Blocks: Fenced with ```
Tags: #tagname (highlighted)

Keybindings

Key	Action
`q`	Quit
`n`	New note
`e`	Edit in $EDITOR
`r`	Rename
`d`	Delete
`t`	Search tags
`/`	Search notes
`j`/`k`	Navigate file list up/down
`Enter`	Edit selected note / Open
`Ctrl+d` / `PgDn`	Scroll preview down
`Ctrl+u` / `PgUp`	Scroll preview up
`g`	Scroll to top
`G`	Scroll to bottom
`Esc`	Cancel current action

Organizing Notes

Wanderer is designed for a flat structure. Simple lists are easier to maintain than complex hierarchies.

# Flat (simple)
~/notes/
├── 20251227-2130-meeting.md
├── 20251227-2145-idea.md
└── 20251228-0900-todo.md

Use shell aliases for quick access:

alias notes="wanderer ~/notes"
alias work="wanderer ~/work/notes"
alias journal="wanderer ~/journal"

Searching Notes

Wanderer follows UNIX philosophy — use existing tools.

Inside Wanderer:

Press / to fuzzy search notes using fzf (must be installed).

From the terminal:

# Find notes containing "meeting"
grep -r "meeting" ~/notes/

# Find by filename
find ~/notes -name "*project*"

# Fuzzy find with fzf
find ~/notes -name "*.md" | fzf --preview 'cat {}'

Configuration

Config file is located at ~/.config/wanderer/config.toml (or equivalent for your OS).

# Display format regarding dates in file list
# Options: "raw" | "compact" (default) | "relative"
date_format = "compact"

# External editor command (optional)
# Defaults to $EDITOR environment variable, then "nvim"
editor = "code"

Environment

$EDITOR: Your preferred editor (defaults to nvim)

License

MIT