{"id":50514051,"url":"https://github.com/szymonwilczek/tmux-jot","last_synced_at":"2026-06-02T22:30:37.430Z","repository":{"id":358032170,"uuid":"1238246994","full_name":"szymonwilczek/tmux-jot","owner":"szymonwilczek","description":"tmux popup note manager serving as sticky notes","archived":false,"fork":false,"pushed_at":"2026-05-15T09:32:02.000Z","size":499,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T11:34:41.518Z","etag":null,"topics":["fzf","notes","ripgrep","tmux","tmux-plugin","tpm"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/szymonwilczek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T00:32:24.000Z","updated_at":"2026-05-15T11:27:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/szymonwilczek/tmux-jot","commit_stats":null,"previous_names":["szymonwilczek/tmux-jot"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/szymonwilczek/tmux-jot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szymonwilczek%2Ftmux-jot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szymonwilczek%2Ftmux-jot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szymonwilczek%2Ftmux-jot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szymonwilczek%2Ftmux-jot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/szymonwilczek","download_url":"https://codeload.github.com/szymonwilczek/tmux-jot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szymonwilczek%2Ftmux-jot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33840212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fzf","notes","ripgrep","tmux","tmux-plugin","tpm"],"created_at":"2026-06-02T22:30:36.311Z","updated_at":"2026-06-02T22:30:37.425Z","avatar_url":"https://github.com/szymonwilczek.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tmux-jot\n\n`tmux-jot` is a tmux popup note manager (sticky notes). It keeps notes on disk, links one active note to each tmux session, and opens notes in a hidden tmux session so the editor state survives popup close/open cycles.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"assets/showcase.mp4\"\u003e\n    \u003cimg src=\"assets/showcase.gif\" alt=\"tmux-jot showcase\" width=\"900\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Requirements\n\n- tmux with `display-popup` support\n- `fzf`\n- `rg` / ripgrep for content search\n- an editor command, default: `nvim`\n\n## Installation\n\n### TPM\n\nSet options before the TPM plugin declaration, then add the plugin:\n\n```tmux\nset -g @jot-dir \"~/.local/share/tmux-jot\"\nset -g @jot-editor \"nvim\"\n\nset -g @plugin 'szymonwilczek/tmux-jot'\n```\n\nReload tmux and install with TPM:\n\n```tmux\nprefix + I\n```\n\n### Manual\n\nClone the repository and load the plugin from `~/.tmux.conf`:\n\n```sh\ngit clone https://github.com/szymonwilczek/tmux-jot ~/.tmux/plugins/tmux-jot\n```\n\n```tmux\nrun-shell \"~/.tmux/plugins/tmux-jot/tmux-jot.tmux\"\n```\n\nSet options before `run-shell` if you configure the plugin manually.\n\n## Usage\n\n| Action | Default binding | Description |\n|---|---:|---|\n| Toggle session note | `prefix + j` | Opens the note linked to the current tmux session. If no note is linked, opens the note picker. If a popup is already open for the client, closes it. |\n| Switch note / picker | `prefix + M-j` | Opens the note picker. Selecting an existing note links it to the current session. Entering a new name creates a note. |\n| Search note content | `prefix + M-w` | Opens an `fzf` content search powered by ripgrep. Selecting a match links and opens the matching note. |\n| Doctor | `prefix + M-i` | Shows context, command availability, paths, config, hidden sessions, and popup state. |\n| Cleanup | `prefix + M-k` | Kills detached hidden editor sessions whose names match the hidden session prefix. |\n| Increase popup size | `prefix + M-=` or `prefix + M-+` | Increases popup width and height by 5 percentage points or cells, depending on configured size units. |\n| Decrease popup size | `prefix + M--` or `prefix + M-_` | Decreases popup width and height by 5 percentage points or cells, depending on configured size units. |\n| Repeat resize | `M-=`, `M-+`, `M--`, `M-_` | Works for `@jot-resize-repeat-time` seconds after a resize command while a tmux-jot popup is open. |\n| Reset popup size | `prefix + M-r` | Resets the current session popup size delta to `0`. |\n\n`M-` means tmux Meta/Alt notation. Bind values are passed directly to `tmux bind-key`, so they may include flags such as `-n` or `-r`.\n\n## Storage Model\n\nNotes are regular files:\n\n```text\n@jot-dir/\u003cnote-name\u003e.\u003cextension\u003e\n```\n\nThe current note for each tmux session is stored as a symlink:\n\n```text\n@jot-session-dir/\u003csafe-session-name\u003e.\u003cextension\u003e\n```\n\nIf `@jot-session-dir` is unset, session links are stored in:\n\n```text\n@jot-dir/.sessions\n```\n\nEditor popups are backed by hidden tmux sessions named from `@jot-hidden-session-prefix` and the safe note name. This keeps the editor process alive between popup open/close cycles.\n\n\u003e Note names may not be empty and may not contain `/`, newline, or carriage return.\n\n## Configuration\n\nSet tmux options before loading the plugin.\n\nWith TPM, options must be set before `set -g @plugin 'szymonwilczek/tmux-jot'`.\n\n```tmux\nset -g @jot-dir \"~/.local/share/tmux-jot\"\nset -g @jot-editor \"nvim\"\nset -g @plugin 'szymonwilczek/tmux-jot'\n```\n\nWith manual installation, options must be set before `run-shell`.\n\n```tmux\nset -g @jot-dir \"~/.local/share/tmux-jot\"\nset -g @jot-editor \"nvim\"\nrun-shell \"~/.tmux/plugins/tmux-jot/tmux-jot.tmux\"\n```\n\nUse an empty string, `off`, `none`, or `disabled` to disable a binding.\n\n| Option | Default | Description | Example |\n|---|---:|---|---|\n| `@jot-key-bind` | `j` | Main toggle binding in the prefix table. Opens the linked session note or the picker. | `set -g @jot-key-bind \"N\"` |\n| `@jot-switch-key-bind` | `M-j` | Opens the note picker. | `set -g @jot-switch-key-bind \"M-n\"` |\n| `@jot-content-search-key-bind` | `M-w` | Opens content search. | `set -g @jot-content-search-key-bind \"M-s\"` |\n| `@jot-doctor-key-bind` | `M-i` | Opens the doctor report. | `set -g @jot-doctor-key-bind \"M-d\"` |\n| `@jot-cleanup-key-bind` | `M-k` | Opens cleanup report and kills detached hidden sessions. | `set -g @jot-cleanup-key-bind \"M-c\"` |\n| `@jot-resize-increase-key-bind` | `-r M-=` | Prefix-table binding for increasing popup size. | `set -g @jot-resize-increase-key-bind \"-r M-=\"` |\n| `@jot-resize-increase-shift-key-bind` | `-r M-+` | Prefix-table shifted variant for increasing popup size. | `set -g @jot-resize-increase-shift-key-bind \"-r M-+\"` |\n| `@jot-resize-increase-repeat-key-bind` | empty | Optional prefix-table repeat binding for increasing popup size. Disabled by default to avoid conflicts with plain `+` or `=`. | `set -g @jot-resize-increase-repeat-key-bind \"-r =\"` |\n| `@jot-resize-increase-repeat-shift-key-bind` | empty | Optional prefix-table shifted repeat binding for increasing popup size. Disabled by default. | `set -g @jot-resize-increase-repeat-shift-key-bind \"-r +\"` |\n| `@jot-resize-decrease-key-bind` | `-r M--` | Prefix-table binding for decreasing popup size. | `set -g @jot-resize-decrease-key-bind \"-r M--\"` |\n| `@jot-resize-decrease-shift-key-bind` | `-r M-_` | Prefix-table shifted variant for decreasing popup size. | `set -g @jot-resize-decrease-shift-key-bind \"-r M-_\"` |\n| `@jot-resize-decrease-repeat-key-bind` | empty | Optional prefix-table repeat binding for decreasing popup size. Disabled by default to avoid conflicts with plain `-`. | `set -g @jot-resize-decrease-repeat-key-bind \"-r -\"` |\n| `@jot-resize-decrease-repeat-shift-key-bind` | empty | Optional prefix-table shifted repeat binding for decreasing popup size. Disabled by default. | `set -g @jot-resize-decrease-repeat-shift-key-bind \"-r _\"` |\n| `@jot-resize-increase-root-repeat-key-bind` | `-n M-=` | Root-table repeat binding used only while tmux-jot resize repeat mode is active. Outside repeat mode, the literal key is sent through. | `set -g @jot-resize-increase-root-repeat-key-bind \"-n M-=\"` |\n| `@jot-resize-increase-root-repeat-shift-key-bind` | `-n M-+` | Root-table shifted repeat binding for increasing popup size. | `set -g @jot-resize-increase-root-repeat-shift-key-bind \"-n M-+\"` |\n| `@jot-resize-decrease-root-repeat-key-bind` | `-n M--` | Root-table repeat binding used only while tmux-jot resize repeat mode is active. | `set -g @jot-resize-decrease-root-repeat-key-bind \"-n M--\"` |\n| `@jot-resize-decrease-root-repeat-shift-key-bind` | `-n M-_` | Root-table shifted repeat binding for decreasing popup size. | `set -g @jot-resize-decrease-root-repeat-shift-key-bind \"-n M-_\"` |\n| `@jot-resize-repeat-time` | `2` | Seconds after a resize command during which root repeat resize bindings are active. | `set -g @jot-resize-repeat-time \"3\"` |\n| `@jot-resize-reset-key-bind` | `M-r` | Resets the current session popup size delta. | `set -g @jot-resize-reset-key-bind \"M-0\"` |\n| `@jot-hidden-session-prefix` | `__tmux__jot_` | Prefix used for hidden editor sessions. | `set -g @jot-hidden-session-prefix \"__jot_\"` |\n| `@jot-debug` | `off` | Enables debug logging. Truthy values: `1`, `on`, `true`, `yes`, `y`. | `set -g @jot-debug \"on\"` |\n| `@jot-icons` | `on` | Enables built-in icons in title and prompt templates. Set to `off` to disable them. | `set -g @jot-icons \"off\"` |\n| `@jot-log-file` | `~/.local/state/tmux-jot.log` | Debug log path. Used only when debug is enabled. | `set -g @jot-log-file \"~/.cache/tmux-jot.log\"` |\n| `@jot-dir` | `~/.local/share/tmux-jot` | Directory containing note files. | `set -g @jot-dir \"~/notes/tmux\"` |\n| `@jot-extension` | `md` | Note file extension. Leading dots are removed; slashes are replaced with `_`. The plugin does not validate file format; any extension can be used. | `set -g @jot-extension \"txt\"` |\n| `@jot-session-dir` | empty | Directory containing per-session symlinks. Empty means `@jot-dir/.sessions`. | `set -g @jot-session-dir \"~/.local/state/tmux-jot/sessions\"` |\n| `@jot-editor` | `$EDITOR` or `nvim` | Editor command used in hidden editor sessions. Any command that can open a file path is supported. | `set -g @jot-editor \"vim\"` |\n| `@jot-shell` | `/bin/bash` | Shell used to run `fzf` commands. | `set -g @jot-shell \"/usr/bin/bash\"` |\n| `@jot-fzf-command` | `fzf` | `fzf` executable or command. | `set -g @jot-fzf-command \"fzf-tmux\"` |\n| `@jot-fzf-options` | empty | Extra options appended to all `fzf` invocations. | `set -g @jot-fzf-options \"--height=100%\"` |\n| `@jot-sort-notes` | `off` | Sorts picker note list when truthy. | `set -g @jot-sort-notes \"on\"` |\n| `@jot-rg-command` | `rg` | Ripgrep command used for content search. | `set -g @jot-rg-command \"rg --hidden\"` |\n| `@jot-content-search-prompt` | `{icon} Search content: ` | Prompt template for content search. Supports `{icon}`, `{session}`, `{note}`, `{file}`. Uses the built-in search icon when `@jot-icons` is `on`. | `set -g @jot-content-search-prompt \"{icon} Search: \"` |\n| `@jot-content-search-preview-window` | `right,60%,border-left` | `fzf --preview-window` value for content search. | `set -g @jot-content-search-preview-window \"down,50%,border-top\"` |\n| `@jot-border-color` | `#b38d59` | Popup border foreground color. | `set -g @jot-border-color \"cyan\"` |\n| `@jot-border-style` | `rounded` | Popup border line style passed to `display-popup -b`. | `set -g @jot-border-style \"single\"` |\n| `@jot-popup-width` | `40%` | Base popup width. Percentages and integer cell values are supported. | `set -g @jot-popup-width \"80\"` |\n| `@jot-popup-height` | `50%` | Base popup height. Percentages and integer cell values are supported. | `set -g @jot-popup-height \"70%\"` |\n| `@jot-popup-x` | `R` | Popup horizontal anchor. `R` means right aligned, `C` means centered, percentages are relative to available space, integers are absolute cells. | `set -g @jot-popup-x \"C\"` |\n| `@jot-popup-y` | `0` | Popup vertical anchor. `C` means centered, percentages are relative to available space, integers are absolute cells. | `set -g @jot-popup-y \"2\"` |\n| `@jot-title-icon` | `📌` | Icon used by the popup title template when `@jot-icons` is `on`. | `set -g @jot-title-icon \"J\"` |\n| `@jot-title` | ` {icon} {note} ` | Popup title template. Supports `{icon}`, `{session}`, `{note}`, `{file}`. | `set -g @jot-title \" {session}: {note} \"` |\n| `@jot-fzf-prompt` | `{icon} Select / Create: ` | Picker prompt template. Supports `{icon}`, `{session}`, `{note}`, `{file}`. Uses the built-in note icon when `@jot-icons` is `on`. | `set -g @jot-fzf-prompt \"{icon} Note: \"` |\n\n## Resize Behavior\n\nBase size comes from `@jot-popup-width` and `@jot-popup-height`. Each resize changes a per-session delta by 5.\n\nFor percentage sizes, the result is clamped to `20%..100%`. For integer cell sizes, the result is clamped to `10..client-size`.\n\nThe reset binding clears only the current tmux session's delta.\n\n## Content Search\n\nContent search uses ripgrep with:\n\n- `--line-number`\n- `--column`\n- `--no-heading`\n- `--smart-case`\n- `--glob \"*.\u003cextension\u003e\"`\n\nThe `fzf` search view is disabled by default and reloads ripgrep results on query changes.\n\n## Troubleshooting\n\nRun doctor:\n\n```tmux\nprefix + M-i\n```\n\nEnable debug logging:\n\n```tmux\nset -g @jot-debug \"on\"\nset -g @jot-log-file \"~/.local/state/tmux-jot.log\"\n```\n\nCleanup detached hidden sessions:\n\n```tmux\nprefix + M-k\n```\n\nIf a binding was previously registered in the root table, explicitly unbind it before loading the plugin:\n\n```tmux\nunbind-key -n j\n```\n\n## Internal tmux Options\n\nThe plugin stores runtime state in tmux options. These are not intended as user configuration:\n\n| Option pattern | Purpose |\n|---|---|\n| `@jot-size-delta` | Per-session resize delta. |\n| `@jot_popup_*` | Active popup state per client. |\n| `@jot_origin_*` | Source session tracking per client. |\n| `@jot_resize_repeat_*` | Resize repeat timeout per client. |\n| `@jot-source-client` | Hidden session source client. |\n| `@jot-origin-session` | Hidden session origin session. |\n\n## License\n\ntmux-jot is licensed under the GNU General Public License v3.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszymonwilczek%2Ftmux-jot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fszymonwilczek%2Ftmux-jot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszymonwilczek%2Ftmux-jot/lists"}