jot

README

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

Documentation

Overview

Package main is the jot CLI entry point. The CLI tree lives in the `cmd` package; implementation lives under `internal/jot`.