Tsuzuri

~ 綴り • Terminal Markdown Notebook ~

A block-based notebook for your terminal. Your notes stay plain Markdown files.

tsuzuri-laptop.mp4

Installation

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/jaisuriya-11/tsuzuri/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/jaisuriya-11/tsuzuri/main/install.ps1 | iex

Manual download: grab tsuzuri-macos.tar.gz, tsuzuri-linux.tar.gz or tsuzuri-windows.zip from the latest release and put tsuzuri on your PATH.

Go: go install github.com/jaisuriya-11/tsuzuri/cmd/tsuzuri@latest

Tsuzuri is a single binary with no dependencies. It runs on macOS (Intel and Apple Silicon), Windows 10/11 and any x86-64 Linux distribution. On other CPUs (e.g. Raspberry Pi), install with Go. A Nerd Font is recommended for icons.

Quick start

cd ~/notes        # any folder; your .md files show up in the explorer
tsuzuri

Press ? inside the app to see every shortcut.

tsuzuri --dir ~/notes          # open a specific folder
tsuzuri --theme <name>         # pick a theme for this session
tsuzuri --list-themes
tsuzuri --themes-dir <path>    # custom themes folder or single .json file

Features

• Plain Markdown files. No database or lock-in: use git, sync the folder, open notes in any editor.
• A full workspace. Start screen, file tree, tabs, statusline and 97 themes.
• Modal keyboard editing with mouse support, plus unsaved tabs and Save As.
• / block menu for headings, to-dos, tables, callouts, code, images and more.
• Live preview laid out like a page, with syntax highlighting, images and cover banners drawn in the terminal.
• Drag blocks to reorder them in the preview by their ⠿ handle, or add one below with +, like Notion.
• Boards, calendars, timelines, charts and forms, stored as text and editable from the preview.
• Flowcharts from Mermaid syntax (graph TD / graph LR), drawn with real shapes: boxes, decisions, circles, databases.
• 2, 3 and 4 column layouts from the / menu.
• Resizable panes: drag the dividers between the explorer, editor and preview.
• Fast search across file names and note contents.

Flowcharts

Write a flow (or mermaid) code block and the preview draws it:

```flow
graph LR
start([Start]) --> check{Is it working?}
check -->|yes| done([Ship it])
check -->|no| fix[Fix it]
fix --> check
```

Shapes: [box], (rounded), ([stadium]), {decision}, {{hexagon}}, ((circle)), [(database)], [[subroutine]]. Arrows: -->, -.-> (dotted), ==> (thick), with labels as -->|yes| or -- yes -->.

Columns

Type /2 columns (or 3, 4). Each +++ line starts a new column, and each column is ordinary Markdown:

~~~columns
## Todo
- [ ] Write the docs
+++
## Notes
Columns stack on narrow screens.
~~~

Custom themes

Drop a JSON palette into the themes folder in your user config directory:

• Linux: ~/.config/tsuzuri/themes/<name>.json
• macOS: ~/Library/Application Support/tsuzuri/themes/<name>.json
• Windows: %APPDATA%\tsuzuri\themes\<name>.json

User themes appear automatically in the live theme picker (Space t) and in --list-themes. Bundled themes take precedence on a name collision.

To use themes from a different folder (or a single palette file), set themes_dir in your config:

• config.json: {"theme": "onedark", "themes_dir": "~/my-themes"} — a directory of *.json palettes, or one .json file
• flag: tsuzuri --themes-dir ~/my-themes (overrides the config value)

Example ~/.config/tsuzuri/themes/minimal.json:

{
  "light": false,
  "fg": "#d8dee9",
  "bg": "#2e3440",
  "darker_bg": "#242933",
  "line": "#3b4252",
  "blue": "#88c0d0"
}

Uninstall

Your notes are never touched. Remove the binary the way you installed it:

rm -f /usr/local/bin/tsuzuri ~/.local/bin/tsuzuri   # macOS / Linux

On Windows, delete %LOCALAPPDATA%\Programs\tsuzuri and remove it from your PATH. Settings are in ~/.config/tsuzuri (macOS: ~/Library/Application Support/tsuzuri, Windows: %APPDATA%\tsuzuri).

Contributing

Contributions are welcome! See CONTRIBUTING.md.

Credits

Built with Bubble Tea and Lip Gloss (the editor is adapted from Bubbles). Theme palettes are MIT-licensed community palettes, syntax highlighting by chroma.

License

MIT