claude-code-mouse (ccm)

English | 中文

---

English

A thin wrapper that adds mouse-click cursor positioning (plus triple-click to clear) to the Claude Code CLI.

Just want mouse clicks? Use the official flag

Claude Code already ships with an environment variable that enables mouse-click cursor positioning natively — no wrapper needed. If that's all you want, you don't need ccm at all:

Option 1 — one command (via ccm):

ccm setup

This safely merges "env": { "CLAUDE_CODE_NO_FLICKER": "1" } into your ~/.claude/settings.json. Then restart Claude Code.

Option 2 — manual (zero install): Edit ~/.claude/settings.json and add:

{
  "env": {
    "CLAUDE_CODE_NO_FLICKER": "1"
  }
}

Why still install ccm?

ccm runs Claude Code through a PTY wrapper and adds features the official flag doesn't:

• Triple-click to clear input — three clicks within 400 ms at the same spot sends Ctrl+U to the input.
• A single ccm setup command to enable the official mouse support (above).

If you only need single-click cursor positioning, just run ccm setup (or edit the JSON) and you're done — no need to use ccm as your launcher.

Install

Option A — from source (recommended for now)

git clone https://github.com/YOUR_USERNAME/claude-code-mouse.git
cd claude-code-mouse
npm install
npm link

This registers ccm on your PATH.

Option B — from npm

npm install -g claude-code-mouse

Requires Node.js ≥ 18 and a working claude binary already on your PATH.

Usage

Just run ccm instead of claude:

ccm                  # same as `claude`
ccm --continue       # any args are forwarded to claude
ccm -p "hello"       # ...

• Click anywhere in the input box — the cursor jumps there.
• Triple-click (3 clicks within 400 ms near the same spot) — clears the entire current input line (sends Ctrl+U).
• Option / Alt + drag — bypasses mouse tracking and performs your terminal's native text-selection (for copy/paste). Mouse tracking normally captures drags, so this modifier is required.

How it works

1. Spawns claude inside a pseudo-terminal (via node-pty).
2. Enables SGR mouse reporting (\x1b[?1000h\x1b[?1006h) on the outer terminal.
3. On a left-click, queries the current cursor position via DSR (\x1b[6n), computes the delta to the click target, and injects arrow-key sequences (\x1b[A/B/C/D) into the child PTY.

It's a terminal-agnostic version of iTerm2's "Option-click moves cursor" feature, scoped to Claude Code.

Troubleshooting

Error: posix_spawnp failed at startup. The spawn-helper binary in node-pty's prebuilt tarball is sometimes unpacked without the executable bit. The postinstall script should fix this automatically; if not, run:

chmod +x node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper

(Use the matching platform directory for your OS.)

ccm: cannot find claude binary. Set CLAUDE_BIN explicitly:

CLAUDE_BIN=/path/to/claude ccm

Clicks don't move the cursor. Your terminal may not forward SGR mouse events. Try iTerm2 or WezTerm to confirm. Some multiplexers (tmux, screen) need their own mouse mode enabled.

Known limitations

• Text selection with the mouse is captured by mouse tracking — use Option/Alt + drag to select.
• Multi-line deltas assume the prompt doesn't scroll; very long pasted inputs may misalign.
• Only left-click press is handled. Right-click, scroll wheel, and drag are passed through untouched.
• If Claude Code itself starts enabling mouse tracking in a future version, state may collide.

Security

• No network requests, no file writes, no logging — the wrapper only spawns claude in a PTY and relays bytes.
• Click handling is purely local: mouse coordinates → integer deltas → arrow-key sequences into the child PTY. No arbitrary data can be injected by remote content.
• Only runtime dependency is node-pty (maintained by Microsoft for VS Code).
• Source is under 200 lines in one file — audit yourself in a few minutes.
• On crash or SIGHUP, the wrapper restores mouse tracking and raw-mode state before exiting.

License

MIT

---

中文

一个给 Claude Code CLI 加上鼠标点击定位光标（以及三连击清空输入）的轻量包装工具。

只想让鼠标能点？用官方环境变量

Claude Code 其实自带一个环境变量可以开启鼠标点击定位光标，根本不需要任何包装器。如果你只要这个功能，不用装 ccm：

方式 1 —— 一条命令（借助 ccm）：

ccm setup

这条命令会安全地把 "env": { "CLAUDE_CODE_NO_FLICKER": "1" } 合并到你的 ~/.claude/settings.json 里。之后重启 Claude Code 即可。

方式 2 —— 手动（零安装）： 编辑 ~/.claude/settings.json，加上：

{
  "env": {
    "CLAUDE_CODE_NO_FLICKER": "1"
  }
}

为什么还要装 ccm？

ccm 通过 PTY 包装运行 Claude Code，额外提供官方环境变量没有的功能：

• 三连击清空输入 —— 400ms 内在同一位置附近点击 3 次，向输入框发送 Ctrl+U。
• 一条 ccm setup 命令帮你开启上面那个官方配置。

如果你只要单击定位光标，跑一下 ccm setup（或手动改 JSON）就够了，不必把 ccm 作为 Claude Code 的启动器。

安装

方式 A —— 从源码安装（当前推荐）

git clone https://github.com/你的用户名/claude-code-mouse.git
cd claude-code-mouse
npm install
npm link

ccm 命令就注册到全局 PATH 里了。

方式 B —— 从 npm 安装

npm install -g claude-code-mouse

需要 Node.js ≥ 18，并且你的系统里已经有可用的 claude 命令。

使用

把原本的 claude 换成 ccm 就行：

ccm                  # 等同于 claude
ccm --continue       # 所有参数会原样传给 claude
ccm -p "hello"       # ...

• 单击输入框任意位置 —— 光标跳到该处。
• 三连击（400ms 内在同一位置附近点击 3 次）—— 清空当前整行输入（相当于发送 Ctrl+U）。
• 按住 Option / Alt 再拖拽 —— 绕过鼠标跟踪，走终端原生的文字选中行为（用于复制/粘贴）。鼠标跟踪开启后普通拖拽会被拦截，所以复制文字需要按这个修饰键。

工作原理

1. 用 node-pty 在一个伪终端里启动 claude。
2. 在外层终端上开启 SGR 鼠标协议（\x1b[?1000h\x1b[?1006h）。
3. 检测到鼠标左键点击时，用 DSR（\x1b[6n）查询当前光标位置，算出到点击目标的行列差，然后把对应数量的方向键转义序列（\x1b[A/B/C/D）注入到子进程 stdin。

本质上是把 iTerm2 的 "Option-click moves cursor" 功能做成了终端无关的版本，专门服务于 Claude Code。

常见问题

启动时报 Error: posix_spawnp failed。 node-pty 的预编译包里 spawn-helper 有时会丢失可执行权限。postinstall 脚本会自动修复；如果没生效，手动运行：

chmod +x node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper

（路径里的 darwin-arm64 换成你系统对应的目录。）

提示 ccm: cannot find claude binary。 手动指定 claude 路径：

CLAUDE_BIN=/path/to/claude ccm

点击没反应。 你的终端可能没转发 SGR 鼠标事件。可以换成 iTerm2 或 WezTerm 试试。如果你用了 tmux / screen，需要另外开启它们的鼠标模式。

已知限制

• 鼠标拖拽选中文字会被鼠标跟踪拦截，需要按住 Option / Alt 再拖拽。
• 多行输入时假设输入框没有滚动，超长粘贴可能对不准位置。
• 目前只处理鼠标左键按下事件。右键、滚轮、拖拽会原样透传。
• 如果将来 Claude Code 本身启用了鼠标跟踪，可能会和本工具的状态冲突。

安全性

• 没有网络请求、没有文件写入、没有日志记录 —— 包装器只做一件事：用 PTY 启动 claude 并转发字节流。
• 点击处理完全本地化：鼠标坐标 → 整数差值 → 方向键转义序列注入子进程。远程内容无法借此注入任意数据。
• 唯一运行时依赖是 node-pty（微软为 VS Code 维护）。
• 源码不到 200 行，单文件，几分钟就能自己审计一遍。
• 进程崩溃或收到 SIGHUP 信号时，会自动还原鼠标跟踪模式和终端 raw mode，不会污染终端状态。

开源协议

MIT