tmux-agent-cli-note

中文文档

A vim-like brainstorm note tool that runs inside tmux. Write notes, then send them directly to AI CLI agents (Claude Code, OpenCode, Codex, etc.) in the same tmux window.

Features

• Vim-like modal editor — NORMAL / INSERT / COMMAND modes with familiar keybindings
• Per-directory notes — notes are stored in .note/notes.json under each working directory
• Multi-agent support — auto-detects all AI CLI panes, shows a selector when multiple are found
• CJK friendly — proper display width handling for Chinese/Japanese/Korean characters
• Zero Node.js dependencies — STT backends use optional external tools (Python, Swift, whisper-cli)
• Session tracking — links notes to Claude Code sessions via tmux hooks, shows session status in list view
• Speech-to-text (STT) — voice recording with 6 backends (whisper-cpp, faster-whisper, SenseVoice, Paraformer, Vosk, macOS Speech), transcribe directly in the editor

Requirements

• tmux 3.0+
• Node.js 18+
• Must be run inside a tmux session

Install

npm install -g tmux-agent-cli-note

Commands

note update — Self-update

note update

Check for the latest version and update automatically.

note setup-hooks — Install Claude Code hooks

note setup-hooks

Install the SessionStart hook into ~/.claude/settings.json to enable session tracking. This hook writes the Claude Code session ID to a tmux pane option, allowing notes to be linked to specific sessions.

note stt — Manage STT (Speech-to-Text) models

note stt install <url> [--backend <backend>] [--language <lang>]
note stt list
note stt remove <id>
note stt default <id>
note stt language [<code>]
note stt check

Subcommand	Description
install	Download and register a model from URL
list	List installed models (shows id, backend, size, language; [default] marks active model)
remove <id>	Delete a model by id (the filename shown by list)
default <id>	Set default model by id
language [<code>]	Get or set transcription language (zh-cn, zh-tw, en, auto, …). Omit code to show current.
check	Check if required tools (sox/ffmpeg, whisper-cpp) are available

Examples:

# Install a multilingual model
note stt install https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin

# Install with specific language (zh-cn = Simplified, zh-tw = Traditional)
note stt install https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin --language zh-cn

# List installed models
note stt list
# Output:
#   ggml-small.bin [default]
#     backend: whisper-cpp  size: 465.0MB  lang: multi

# Set default model (id is the filename from `list`)
note stt default ggml-small.bin

# Set transcription language
note stt language zh-cn  # Simplified Chinese
note stt language zh-tw  # Traditional Chinese
note stt language en
note stt language        # prints: Current STT language: zh-cn

Setup (one-time)

Step 1 — Install a recording tool (required for all backends):

brew install sox      # macOS / Linux (recommended)
sudo apt install sox  # Linux

Step 2 — Pick a backend and install it:

---

whisper-cpp — local, fast, Metal GPU on macOS:

brew install whisper-cpp
# Linux: build from https://github.com/ggerganov/whisper.cpp

# Models (pick one):
note stt install https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin            # 75MB
note stt install https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin            # 142MB
note stt install https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin           # 466MB
note stt install https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin          # 1.5GB
note stt install https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin  # 1.6GB

---

faster-whisper — Python, int8 quantized, multilingual:

pip3 install faster-whisper torchaudio torch --index-url https://download.pytorch.org/whl/cpu

# Models (HuggingFace ID, downloaded by library on first transcription):
note stt install Systran/faster-whisper-tiny    --backend faster-whisper --language multi
note stt install Systran/faster-whisper-base    --backend faster-whisper --language multi
note stt install Systran/faster-whisper-small   --backend faster-whisper --language multi
note stt install Systran/faster-whisper-medium  --backend faster-whisper --language multi
note stt install Systran/faster-whisper-large-v3 --backend faster-whisper --language multi

---

SenseVoice — Python, strong Chinese/multilingual support:

pip3 install funasr torchaudio torch --index-url https://download.pytorch.org/whl/cpu

note stt install iic/SenseVoiceSmall --backend sensevoice --language multi

---

Paraformer — Python, Chinese-optimized:

pip3 install funasr torchaudio torch --index-url https://download.pytorch.org/whl/cpu

note stt install iic/paraformer-zh --backend paraformer --language zh-cn

---

Vosk — Python, fully offline, no GPU:

pip3 install vosk

# Models (zip auto-extracted):
note stt install https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip --language en     # 40MB
note stt install https://alphacephei.com/vosk/models/vosk-model-cn-0.22.zip --language zh-cn           # 1.6GB

---

macOS Speech — on-device Apple Speech Recognition, no model download:

xcode-select --install  # only needed if swift is not installed

# Register a language:
note stt install macos-en    --backend macos-speech --language en
note stt install macos-zh-cn --backend macos-speech --language zh-cn
note stt install macos-zh-tw --backend macos-speech --language zh-tw

---

Step 3 — Verify:

note stt check

Supported backends

Backend	File format	Dependency
whisper-cpp	.bin / .gguf	whisper-cli binary
faster-whisper	HuggingFace ID	Python faster-whisper + torch
SenseVoice	HuggingFace ID	Python funasr + torch + torchaudio
Paraformer	HuggingFace ID	Python funasr + torch + torchaudio
Vosk	.zip	Python vosk
macOS Speech	—	swift (Xcode CLT), macOS only

Usage

Run note inside a tmux pane:

note

Modes

Mode	Description
NORMAL	Default mode. Navigate, enter other modes.
INSERT	Type text freely. Press Esc to return to NORMAL.
COMMAND	Type commands after :. Press Enter to execute.
LIST	Browse all notes in the current directory.
SELECT	Choose which AI agent to send to (when multiple found).
RECORDING	Voice recording in progress (STT).
STT PREVIEW	Review transcribed text before inserting.

NORMAL Mode Keys

Key	Action
i	Enter INSERT mode
:	Enter COMMAND mode
q	Quit editor, return to list
h j k l	Move cursor left / down / up / right
x	Delete character under cursor
dd	Delete current line
g	Go to top
G	Go to bottom
a	Append after cursor, enter INSERT
A	Append at end of line, enter INSERT
o	Open new line below, enter INSERT
O	Open new line above, enter INSERT
;r	Start voice recording (STT)
Ctrl+D / Ctrl+U	Half page down / up
Ctrl+F / Ctrl+B	Full page down / up
PageDown / PageUp	Full page down / up
?	Toggle help overlay

INSERT Mode Keys

Key	Action
Esc	Return to NORMAL mode
Ctrl+R	Start voice recording (STT)
Ctrl+D / Ctrl+U	Half page down / up
Ctrl+F / Ctrl+B	Full page down / up
PageDown / PageUp	Full page down / up

COMMAND Mode Keys

Command	Action
:s	Send note content to AI agent pane
:q	Quit editor
:w	Save note
:ls	Return to note list
:stt	Start voice recording (STT)
:stt-models	Select default STT model

File Reference (@@)

In INSERT mode, type @@ to open a file picker. Browse the project directory and insert a file or directory path prefixed with @.

Key	Action
j / k	Move selection down / up
Enter / l	Enter directory / select file
Tab	Select highlighted entry (file or directory)
h / Backspace	Go to parent directory
Esc	Cancel, return to editor

Selected paths are inserted as @path/to/file. Backspacing to the / after @path/ reopens the picker at that directory.

LIST Mode Keys

Key	Action
j / k	Move selection up / down
Enter	Open selected note
n	Create new note
d	Delete selected note (with confirmation)
q	Quit

Send Flow

1. Press :s in NORMAL mode
2. Auto-detect AI agent panes in the current tmux window
3. One agent found — content is sent immediately
4. Multiple agents found — selector appears, press number to choose, Esc to cancel
5. On first send to a Claude Code pane, you'll be prompted to enable hooks for session tracking
   • Press y to install the hook (or run note setup-hooks manually)
   • Press n to skip (won't prompt again)

Text is pasted into the agent's input box. It is not auto-submitted — you can review and edit before pressing Enter in the agent pane.

STT (Speech-to-Text) Flow

1. Press ;r (NORMAL), Ctrl+R (INSERT), or :stt (COMMAND) to start recording
2. Status bar shows red -- RECORDING -- with elapsed time
3. Press Enter to stop recording and transcribe, Esc to cancel
4. Status bar shows -- STT PREVIEW -- with transcribed text preview
5. Press Enter to insert text at cursor, Esc to discard

Data Storage

Notes are stored per working directory:

your-project/
└── .note/
    └── notes.json

Example:

{
  "directory": "/path/to/your-project",
  "notes": [
    {
      "id": "a1b2c3",
      "content": "Your brainstorm text...",
      "createdAt": "2026-04-14T16:00:00Z",
      "updatedAt": "2026-04-14T16:05:00Z",
      "sentAt": "2026-04-14T16:10:00Z",
      "sentToPane": "%5",
      "sessionId": "abc123-def456"
    }
  ]
}

Development

# Install dependencies
npm install

# Run directly with tsx (no build needed)
npm run dev

# Run with arguments
npm run dev:args -- update

# Build then run compiled output
npm run dev:build

# Type check only
npm run typecheck

Script	Description
npm run dev	Run entry point via tsx (skip build)
npm run dev:args	Same as dev, convenient for passing args
npm run dev:build	Build with tsc, then run compiled JS
npm run build	Compile TypeScript to dist/
npm run typecheck	Type check without emitting files

License

MIT