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