jot

Terminal-first markdown notes + todos with linked tasks.

Plain .md files with YAML frontmatter, edited in nvim with obsidian.nvim. Write [[slug]] wiki links to connect notes, embed checkbox tasks with #tags to create linked todos, and let jot track everything in git — every save is a commit. Sensitive notes encrypt at rest via kvlt (age + SSH keys). An MCP server exposes the full surface to LLM agents. No database: files are the source of truth.

📦 Install

Requires neovim with plugins — see nvim Setup below. Also requires ripgrep and fzf for search.

curl -fsSL https://github.com/retr0h/jot/raw/main/install.sh | bash

🔨 Build from source

git clone https://github.com/retr0h/jot.git
cd jot
go build -o jot .

🚀 Quick Start

jot init
jot note new --title "Sprint Planning"
jot note new --title "network/Switch Config"
jot note new --title "secrets/API Keys" --secure
cat meeting.md | jot note new --title "Meeting Notes"
echo "secret stuff" | jot note new --title "Credentials" --secure
jot note list
jot note search --query "kubernetes"
jot task list
jot task due
jot git log

✨ Features

Feature	Description
Markdown notes	`.md` files with YAML frontmatter, edited in nvim
`[[wiki links]]`	Cross-reference notes by slug; obsidian.nvim navigates
Checkbox tasks	`- [ ] desc \| due:date #tag` with due dates + tags
Git-backed	Every edit auto-commits; `jot git log/diff/show`
Secure vaults	`--secure` encrypts notes via kvlt (age + SSH keys)
Full-text search	Concurrent goroutine file scan — no index, no database
MCP server	8 tools over stdio for Claude / Cursor / any MCP client
Subdirectory nesting	`jot note new --title "ops/runbook"` for organization
nvim plugin	Ships `lua/jot/` — auto-configures obsidian.nvim
Max Headroom palette	Magenta `#c678dd` accent across CLI, installer, nvim

📝 Note Format

---
title: Team standup 2026-05-14
tags: [work, meetings]
created: 2026-05-14
---

# Team standup 2026-05-14

Discussed the [[deployment-runbook]] and next steps.

- [ ] follow up on infra ticket | due:friday #work #ops
- [ ] review PR before EOD #work
- [x] Send meeting summary | done:2026-05-14
- [ ] Update [[deployment-runbook]]

[[slug]] links connect notes. Checkbox tasks create linked todos. #tags are searchable via CLI (jot tag list) and nvim (<leader>jt). Frontmatter tags: arrays are also recognized.

🖥️ nvim Setup

vim.pack.add({"https://github.com/epwalsh/obsidian.nvim.git"})
vim.pack.add({"https://github.com/OXY2DEV/markview.nvim.git"})
vim.pack.add({"https://github.com/retr0h/jot.git"})

jot ships an nvim plugin that auto-configures obsidian.nvim and markview.nvim when $JOT_NOTES_DIR is set (jot sets this automatically when spawning the editor). Zero manual config.

Keybindings

Key	Action
`<leader>j?`	Show keybindings (`:JotHelp`)
`<leader>jf`	Follow `[[link]]` under cursor
`<leader>jj`	Jump to note (fuzzy switch)
`<leader>js`	Search notes (ripgrep)
`<leader>jt`	Browse `#tags`
`<leader>jb`	Backlinks to current note
`<leader>jl`	Links in current note
`<leader>jn`	New note
`<leader>jx`	Toggle `[ ]` / `[x]` done
`[[`	Autocomplete note slugs
`#`	Autocomplete tags

Snippets

Type task then Enter to expand with tab-stop placeholders:

- [ ] description | due:today #tag

Tab jumps between placeholders. Date completions (next 7 days + day names) appear automatically while typing the due field.

🤖 MCP Server

Auto-discovered by Claude Code via .mcp.json:

{
  "mcpServers": {
    "jot": { "command": "jot", "args": ["mcp", "start"] }
  }
}

Tool	Description
`list_notes`	List notes, optionally filtered by tag
`get_note`	Read full markdown by slug (transparently decrypts secure notes)
`create_note`	Create a note with frontmatter (supports `secure: true`)
`delete_note`	Remove a note file
`search_notes`	Full-text search
`rename_note`	Rename a note and rewrite all `[[wikilinks]]`
`encrypt_note`	Encrypt an existing note via kvlt
`decrypt_note`	Decrypt a secure note back to plaintext
`list_tasks`	Tasks filtered by status/tag
`task_done`	Mark a task as complete
`tasks_due`	Tasks due in a date range
`list_tags`	All tags across notes

Secure notes over MCP require passphrase-free SSH keys configured in ssh_keys — there is no TTY for interactive prompts.

⚙️ Configuration

~/.config/jot/jot.yaml:

# notes_dir: ""       # override notes directory
# ssh_keys: []        # SSH key paths for kvlt (empty = auto-discover ~/.ssh/)

Git is always on — every edit auto-commits. See Configuration for the full reference (env vars, flags, precedence, SSH keys).

📖 Documentation

Configuration — env vars, flags, SSH keys, data layout
Development — architecture, testing conventions, adding commands
Contributing — commit style, lint chain, PR checklist

📄 License

MIT

retr0h/jot

README

jot