kiroku-tui

kiroku (記録) — Japanese for "record", "document", or "archive".

A simple, terminal-based personal journaling and note-taking tool written in Rust.

kiroku-tui helps you manage a collection of markdown notes directly from your terminal. It stores your notes in ~/kiroku by default, supports custom notebook directories, and integrates with Git for easy synchronization.

Features

• Terminal Interface: Clean TUI built with ratatui.
• Folder Support: Organize your notes into directories and navigate them with a file browser.
• Fuzzy Search: Quickly find notes by title across all folders.
• Content Search: Deep search within the body of your notes.
• Tag Search: Filter notes by tags defined in YAML frontmatter.
• Note Renaming: Rename existing notes directly within the app.
• Daily Notes: Press D to open or create today's journal entry under daily/YYYY-MM/YYYY-MM-DD.md, seeded from a template on first use.
• Templates: Stock daily, meeting, 1:1, retro, idea, and project templates are seeded on first run; customize freely.
• Task Management: Create, complete, and delete tasks from a dedicated task window.
• Git-Tracked Tasks: Tasks are stored as Markdown files in your notebook's tasks/ directory, with optional due dates and duration estimates.
• Smart Sorting: Toggle between sorting by Date, Name, or Size.
• External Editor: Opens notes in your preferred editor (Vim, Nano, VS Code, etc.).
• Smart Git Sync: Built-in command to add, commit, and push changes. Skips redundant network calls if up-to-date.
• File Watching: Automatically updates the list when files are changed externally.
• Auto-Sync on Exit: Optional setting to automatically sync with Git when quitting.
• Theming: Fully customizable color schemes with built-in theme cycling.
• PDF Preview: View cached first-page previews for PDF files directly in the terminal preview pane (requires pdftoppm from poppler-utils).
• Clipboard Integration: Copy note content or file paths directly to your clipboard.
• Wiki Links: Link notes using [[Note Title]] syntax. Highlight valid/broken links in the preview pane, track incoming backlinks, and navigate between notes using interactive links and backlinks overlay popups.

Installation

Ensure you have Rust and Cargo installed.

For PDF preview support, install poppler-utils:

# Debian/Ubuntu
sudo apt install poppler-utils

# Arch
sudo pacman -S poppler

# macOS
brew install poppler

From Crates.io (Recommended)

cargo install kiroku-tui

From Git

cargo install --git https://github.com/gab-dev-7/kiroku

Note: After installation, ensure that ~/.cargo/bin is in your PATH environment variable to run kiroku from any directory.

Usage

Run the application:

kiroku

To use a custom notebook directory:

kiroku /path/to/notebook

For CLI help and version information:

kiroku --help
kiroku --version

On the first run, it will create a ~/kiroku directory unless you pass a custom path. You can initialize a git repository there if you want to use the sync feature:

cd ~/kiroku
git init
# Add your remote...

Navigation Modes

Browser Mode (Default) View your notes and folders hierarchically.

• Use h and l to navigate in and out of directories.
• Use f to create new folders.

Search Mode When you start searching (/, #, *), the view switches to a flat list of all matching notes, regardless of their folder.

Task Mode Open the task window with t. Tasks are stored in {notebook}/tasks/ as Markdown files so they are included in normal Git sync.

Keybindings

Normal Mode

• ? / F1: Open help popup
• a: Create a new note
• f: Create a new folder
• c: Open the template picker
• D: Open or create today's daily note
• Enter / l: Edit selected note or enter folder
• Backspace / h: Go up a directory
• j / k: Navigate down / up
• Ctrl+j / Ctrl+k: Scroll preview pane down / up
• r: Rename the selected item
• d: Delete the selected item (prompts for confirmation)
• s: Cycle sort mode (Date, Name, Size)
• t: Open task window
• T: Cycle built-in themes (Default → Gruvbox → Tokyo Night)
• g: Sync with Git (add, commit, push)
• /: Search by title
• #: Search by tag
• *: Search by content
• y: Copy note content to clipboard
• Y: Copy note file path to clipboard
• L: Open outgoing links popup
• B: Open backlinks popup
• q: Quit
• F12: Toggle debug logs

Template Picker

• j / k: Navigate templates
• Enter: Create a note from the selected template
• a: Create a new template
• r: Rename the selected template
• d: Delete the selected template
• Esc: Close the template picker

Search Mode

• Type to filter notes
• Enter: Keep current filter and return to list
• Esc: Clear search and return to browser view

Task Mode

• j / k: Navigate tasks
• Space: Toggle the selected task done/undone
• e: Expand / collapse full task body text
• o / Enter: Open selected task in external editor
• a: Add a task (prompts for title/tags, then opens editor for body)
• r: Rename the selected task title (preserves body text)
• d: Delete the selected task
• #: Filter tasks by tag
• Esc / q: Close the task window

Templates

On first run, kiroku creates a starter pack in templates/:

• daily.md: daily notes used by D
• meeting.md: meeting notes in meetings/
• 1-1.md: 1:1 notes in meetings/1-1/
• retro.md: retrospectives in retros/
• idea.md: ideas in ideas/
• project.md: project notes in projects/

Templates can include optional YAML frontmatter:

---
target: meetings/
name_pattern: "{{date}}_meeting"
---
# Meeting: {{date}}

## Attendees

## Notes

• target: vault-relative folder where created notes are saved
• name_pattern: generated filename; if omitted, kiroku asks for a filename

Template bodies and name_pattern support {{date}}, {{time}}, and {{title}}.

Using Tags

kiroku supports tagging notes using YAML frontmatter at the top of your markdown files.

---
tags: [work, meeting, important]
---

# My Note Title

...

Use # to filter your notes by these tags.

Configuration

You can configure kiroku by creating a file at ~/.config/kiroku/config.toml.

Example config.toml:

# Command to open your editor.
# If omitted, defaults to $EDITOR environment variable or "vim".
editor_cmd = "nvim"

# Automatically sync with git when exiting the application.
auto_sync = false

# Default sort mode for notes ("Date", "Name", "Size").
sort_mode = "Date"

# Optional built-in theme name saved by theme cycling.
# Options: "Default", "Gruvbox", "Tokyo Night"
theme_name = "Default"

# Optional command to open PDF files externally.
# If omitted, defaults to "xdg-open" on Linux or "open" on macOS.
pdf_viewer_cmd = "zathura"

# Optional: Customize daily notes location and template.
# Both fields default to the values shown below if omitted.
[daily]
folder = "daily"              # folder relative to vault root
template = "templates/daily.md"  # template path relative to vault root

# Optional: Customize the color theme (hex codes)
[theme]
accent = "#89dceb"    # Key UI elements
selection = "#bb9af7" # Selected item
header = "#89b4fa"    # List headers
dim = "#6c7086"       # Metadata/dates
bold = "#f38ba8"      # Emphasized text

Existing ~/.config/kiroku/tasks.toml task files are migrated into the notebook tasks/ directory on startup.

Contributing

Contributions are welcome! Please check out CONTRIBUTING.md for guidelines on how to get started.

License

MIT License. See LICENSE for details.