hintvim

Preview · a replayed session in a sandbox

claude · ~/work/app · hintvim

│ ┃ hintvim ✕ › fix the failing auth test and add an audit log call │ ┃ a: Copy last reply │ ┃ s: Copy last code block ⏺ Read(src/auth.ts) │ ┃ f: Copy working directory ⎿ Read 6 lines │ ┃ g: Copy session id ⏺ Update(src/auth.ts) │ ┃ q: Show context usage ⎿ Added 2 lines, removed 1 line │ ┃ w: Compact conversation ⏺ Bash(bun test) │ ⎿ 3 pass, 1 fail │ │ ● Done. refresh now rejects expired claims and logs an audit event. │ │ ✻ Worked for 42s · done 4:20 PM │ │ › /hintvim │ │ ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── › ? for shortcuts

Draws

Pane · hintvim

a: Copy last reply s: Copy last code block f: Copy working directory g: Copy session id q: Show context usage w: Compact conversation

README

<h1 align="center">hintvim</h1>

Vimium-style keyboard hints for the Claude desktop app.

Press Ctrl+;, type a label, and that button is pressed.

What is hintvim?

hintvim is a small macOS menu bar app. Press Ctrl+; to label up to 169 visible controls exposed through Accessibility in the Claude window: the sidebar, the title bar, the model and mode menus, each message's buttons. Type the label and that element is pressed. No mouse.

Ctrl+; puts labels on the sidebar; typing CE opens the More menu

Ctrl+;            →  labels appear on accessible buttons, links, and inputs
type "sf"         →  that element is pressed
j / k / d / u     →  scroll
Esc               →  leave

hintvim is an unofficial community project. It is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" is a trademark of Anthropic, PBC.

Why

Claude Desktop ships plenty of shortcuts (Cmd+K, Cmd+1…9, Cmd+Shift+F), but anything without a binding needs the mouse: the working-directory pill, the model and mode menus, per-message actions. Hint mode labels these controls without a shortcut per control.

Install

Requires macOS 13 or later and Claude Desktop.

brew install --cask jeongjaesoon/tap/hintvim && hintvim setup

Then turn on hintvim in System Settings → Privacy & Security → Accessibility. macOS asks the first time the app starts. That's it: click into Claude and press Ctrl+;.

The formula builds the app from source on your Mac, so it needs no Developer ID and Gatekeeper does not stop it. Homebrew already requires the Command Line Tools this build uses.

What `hintvim setup` changes

Setup is idempotent, logs each step to ~/Library/Logs/hintvim/setup.log, and hintvim uninstall reverts all of it.

Adds a login item, ~/Library/LaunchAgents/io.github.jeongjaesoon.hintvim.plist, and starts the app. This is all Ctrl+; needs.
Installs the optional hintvim Claude plugin: claude plugin marketplace add JeongJaeSoon/hintvim and claude plugin install hintvim@hintvim. It gives Desktop's Code tab the /hintvim command.
Only if Claude Desktop bundles a Claude Code older than 2.1.287, adds "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" to env in ~/.claude/settings.json, after a backup. Older releases load plugin mods only behind this switch; from 2.1.287 they load by default and ignore it. Setup records that it added the switch, removes it once Desktop is on 2.1.287 or later, and never touches a switch you set yourself.
At each login the login item starts the app and re-checks the switch, because a Claude Desktop update replaces its bundled Claude Code.

To keep ~/.claude untouched, run hintvim setup --app-only: you get Ctrl+; and the menu bar icon, without the plugin, the switch, or /hintvim.

Install from Claude instead

If you start from Claude's plugin manager, add the marketplace and install the plugin (in a terminal, or + → Plugins → Add plugin in Desktop's Code tab):

claude plugin marketplace add JeongJaeSoon/hintvim
claude plugin install hintvim@hintvim

Then, in a new Code session, run /hintvim:setup. Claude installs the app for you, with Homebrew if you have it or by building from source if you don't, and runs hintvim setup. The plugin alone can't do hint mode: How it works explains why it needs the app.

Use

Click into the Claude window and press Ctrl+;.

Key	Action
`Ctrl+;`	Show or hide the labels. Claimed only while Claude is the frontmost app, so other apps keep the chord.
`a s f g q w e r t z x c v`	Type a label. The element is pressed, or focused if it's a text field.
`j` / `k`	Scroll down / up a little, then relabel
`d` / `u`	Scroll down / up half a page, then relabel
`Delete`	Undo one typed letter, or leave if nothing is typed
`Esc`	Leave
`Cmd` + anything	Leave, and the shortcut still works (`Cmd+Tab`, `Cmd+W`)

While labels show, keys go to hintvim and never reach Claude, so nothing leaks into the prompt. Switching to another app ends hint mode. Labels follow the window when it moves or resizes. The window's close, minimize and full-screen buttons get no label, so a typo can't close the window.

Letters are read by physical position on a US (ANSI) layout, so labels work with a Korean or Japanese input source on. With Dvorak or AZERTY, type the key in the QWERTY position.

The menu bar icon (a keyboard) shows hints, shows whether Accessibility is allowed, and quits the app.

Ctrl+; and the menu bar need only the app. In a Local session of Desktop's Code tab (or in claude in a terminal), the plugin adds:

/hintvim: the same as Ctrl+;. If the app is missing, it says how to install it.
/hintvim-palette: a pane of six actions (copy the last reply, the last code block, the working directory or the session id; show context usage; compact). In Desktop you click them; their letter hotkeys only work in the terminal.
/hintvim:setup and /hintvim:doctor: skills that install the app or find out why hints don't appear.

Desktop's prompt box prints /hintvim isn't a command here. under either command because it only knows built-in commands. The command still runs.

Update

brew upgrade hintvim && hintvim setup

hintvim was called claude-vimium before 1.0.0. brew upgrade moves a claude-vimium install to hintvim, and hintvim setup then removes claude-vimium's login item, plugin, state and Accessibility entry.

업데이트 후 hintvim setup으로 새 앱을 재시작합니다. 기존 Formula 사용자는 brew upgrade hintvim을 계속 사용할 수 있습니다. Formula와 Cask는 동시에 설치할 수 없습니다.

v1.1.0부터 Developer ID 서명·Apple 공증을 거친 앱을 Homebrew에서 그대로 설치합니다. 신규 설치와 기존 ad-hoc 버전에서의 첫 전환은 접근성 허용이 필요할 수 있습니다. 이후 업데이트는 같은 서명 기준과 bundle ID를 유지합니다. 이 Mac에서 signed 1.0.2 → 1.1.0을 brew upgrade로 업데이트하고 접근성 설정을 변경하지 않은 상태에서 새 앱의 권한과 Claude Desktop 대상 탐지를 확인했습니다.

When Claude Desktop updates, nothing needs redoing. The app works on Desktop's window through macOS, the plugin stays installed in ~/.claude, and the login item re-checks the mods switch.

Uninstall

hintvim uninstall && brew uninstall hintvim

uninstall removes the login item, the plugin and its marketplace, the mods switch if setup added it, and the app's state and logs. It also tries tccutil reset Accessibility for the app. If that fails, it tells you to remove hintvim from the Accessibility list yourself.

Troubleshooting

Run hintvim doctor, or /hintvim:doctor in a Code session. Doctor checks the app, the login item, the Accessibility permission, how many elements hint mode can see in Claude's window, the plugin, and the mods switch. Each failing line names its fix.

Symptom	Fix
`Ctrl+;` shows nothing	Claude must be the frontmost app. If you closed its last window, `Ctrl+;` reopens it; if no window comes back, click Claude in the Dock. Then run `hintvim doctor`.
Accessibility is on but nothing happens	The entry belongs to an older build. Remove it with −, then `hintvim stop && hintvim start` and allow it again.
`brew untap jeongjaesoon/tap` refuses	The tap holds other formulae you have installed. Leave it tapped; `brew uninstall hintvim` is enough.
`/hintvim` is unknown	The mod loads only in a session started after setup, and only in Local sessions. Start a new one. Still missing: `hintvim doctor` says whether mods can load. Anthropic can turn installed mods off remotely, and then `/hintvim` is gone until they turn them back on; `Ctrl+;` keeps working, since the app does not depend on the plugin.

Compatibility

	Tested
macOS	26.5 (Apple silicon). The app is built universal and targets macOS 13.
Claude Desktop	2.7032.0, bundling Claude Code 2.1.280 (mods switch on)
Claude Code	2.1.287 (terminal, mods on by default)
Input sources	US English, Korean

Hint mode finds elements by their Accessibility roles, not by class names (the app's are hashed and change every release), so a Claude Desktop update rarely affects it. A large UI redesign could. Please open an issue with the versions from hintvim doctor if labels stop appearing after an update.

How it works

Claude Desktop ── Code session ──▶ hintvim plugin (a Claude Code mod)
                                      │ /hintvim → open hintvim://toggle
                                      ▼
Ctrl+; ──────────────────────────▶ hintvim app (menu bar, starts at login)
                                      │ macOS Accessibility API
                                      ▼
                         labels over the whole Claude window

A plugin alone can't do hint mode. Claude Code mods hook the Claude Code engine, not the window: they draw only in the engine's own places (panes, the band above the prompt, tool rows), so the app's sidebar and title bar are out of reach. A mod can't register a global key either. A Button hotkey is one letter, and only while the mod's own pane has the focus, and in Desktop clicking a pane doesn't take the keyboard from the prompt box.

macOS's Accessibility API can see the window. Asked through AXManualAccessibility, Chromium exposes the full tree of Claude's window, web content and chrome alike, and AXPress fires the same handlers a click would. So the work splits:

app/ is the menu bar app: a Carbon hotkey for Ctrl+;, an Accessibility walk over clickable roles clipped to visible scroll areas, a transparent panel that draws the labels, and an event tap that takes the keys while they show. It needs only the Accessibility permission, not Input Monitoring.
plugin/ is the optional mod. It reaches the app through the hintvim:// URL scheme, which also starts the app if it isn't running.
bin/hintvim sets up, checks, and removes everything around them.

Why an app and not a Claude Code mod?

Mods were the first plan, and the plugin is one. But a mod can't do this job:

It draws only inside the Claude Code engine's own surfaces, so the sidebar, the title bar and the model menu are out of reach.
It can't register a global key, so there's no Ctrl+;.
Anthropic can turn installed mods off remotely, and then /hintvim disappears.

Injecting a script into the window is closed too: the window renders remote claude.ai, the app is a hardened binary that refuses debuggers and injected libraries, and it quits when started with remote-debugging flags. The Accessibility API works from outside the app, so a Desktop update or a mods switch-off leaves Ctrl+; working.

Without installing anything

A DevTools snippet gives the same hint mode over the web page inside the window (not its sidebar or title bar), with a settings and help panel. It needs no permissions and nothing installed, but you run it again after each app restart. The page also explains why the snippet can't be installed into Claude Desktop permanently.

Limitations

macOS only.
The leader key and the hint alphabet are fixed in the app. The DevTools snippet lets you change them.
Hint mode labels at most 169 visible controls per refresh. Scroll to relabel; controls beyond that limit do not receive a label.
기존 ad-hoc 앱에서 Developer ID 서명 앱으로 처음 전환할 때 접근성 허용이 필요할 수 있습니다.
The overlay drawing and key handling have no automated tests; they are verified by hand on a real Claude Desktop.

Development

make test                                  # Node, shell and Swift unit tests
make app                                   # build/Hintvim.app (universal)
claude plugin validate plugin              # what the mod hooks and calls
claude plugin test plugin                  # plugin/hooks/register.test.tsx

bin/hintvim run from the repository uses build/Hintvim.app, and HINTVIM_MARKETPLACE=$PWD bin/hintvim setup installs the plugin from your checkout. Every rebuild is a new app to macOS, so allow Accessibility again after each one.

See CONTRIBUTING.md for the manual checks a change to the app needs, and SECURITY.md to report a vulnerability. docs/superpowers/ holds the original design spec, plan, and research notes.

License

MIT

Support

If hintvim saves you some clicks, you can sponsor its development.

Cask를 완전히 제거할 때는 hintvim uninstall 후 brew uninstall --cask hintvim을 실행합니다. 일반 업그레이드에서는 hintvim uninstall을 실행하지 않습니다.

Source 1 files

hooks/register.tsx 114 lines

1import type { EngineInterface, Register } from 'claude-code'
2
3const PANE = 'hintvim'
4// Same default alphabet as src/hintvim.js. A Button hotkey is one
5// lowercase letter, so labels never grow past one character here.
6const ALPHABET = 'asfgqwertzxcv'
7
8type ActionId = 'reply' | 'code' | 'cwd' | 'session' | 'usage' | 'compact'
9
10export const ACTIONS: readonly { id: ActionId; label: string }[] = [
11  { id: 'reply', label: 'Copy last reply' },
12  { id: 'code', label: 'Copy last code block' },
13  { id: 'cwd', label: 'Copy working directory' },
14  { id: 'session', label: 'Copy session id' },
15  { id: 'usage', label: 'Show context usage' },
16  { id: 'compact', label: 'Compact conversation' },
17]
18
19export function lastCodeBlock(text: string): string | undefined {
20  const blocks = [...text.matchAll(/```[^\n]*\n([\s\S]*?)```/g)]
21  return blocks.at(-1)?.[1]
22}
23
24export const INSTALL_HINT =
25  'the hintvim app was not found. Run /hintvim:setup, or: brew install jeongjaesoon/tap/hintvim && hintvim setup'
26
27// Hint mode lives in the Hintvim app: it needs the Accessibility tree and
28// a global key, and no mod surface reaches either. The URL scheme also starts
29// the app when it is not running.
30async function openApp($: EngineInterface, command: 'start' | 'toggle') {
31  const run = await $.process.run(['/usr/bin/open', '-g', `hintvim://${command}`], { timeoutMs: 10_000 })
32  return run.exitCode === 0
33}
34
35export const register: Register = on => {
36  on('session.start', async ($, e, next) => {
37    await $.command.register({
38      name: 'hintvim',
39      description: 'Show hint labels over the Claude window (same as Ctrl+;)',
40      immediate: true,
41    })
42    await $.command.register({
43      name: 'hintvim-palette',
44      description: 'Copy the last reply, code block, cwd or session id; show usage; compact',
45      immediate: true,
46    })
47    if (!(await openApp($, 'start'))) $.ui.toast(`hintvim: ${INSTALL_HINT}`)
48    return next(e)
49  })
50
51  on('command.run', { command: 'hintvim' }, async $ => {
52    return (await openApp($, 'toggle')) ? {} : { text: `hintvim: ${INSTALL_HINT}` }
53  })
54
55  on('command.run', { command: 'hintvim-palette' }, async $ => {
56    await $.ui.open({ id: PANE, title: 'hintvim', focus: true, closeOnEscape: true, rows: ACTIONS.length + 1 })
57    return {}
58  })
59
60  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
61    const { Box, Button } = $.ui.resolve(e)
62
63    const lastReply = async () => {
64      const messages = await $.session.messages()
65      if ('deny' in messages) return undefined
66      return messages.findLast(m => m.role === 'assistant' && m.text.trim() !== '')?.text
67    }
68    const copy = async (text: string | undefined, what: string) => {
69      if (text === undefined) return `No ${what} to copy`
70      const done = await $.ui.copy({ text, surface: e.surface })
71      return done.isCopied ? `Copied ${what}` : `Could not copy ${what}: ${done.reason}`
72    }
73    const run = async (id: ActionId): Promise<string> => {
74      switch (id) {
75        case 'reply':
76          return copy(await lastReply(), 'last reply')
77        case 'code': {
78          const reply = await lastReply()
79          return copy(reply && lastCodeBlock(reply), 'code block')
80        }
81        case 'cwd':
82          return copy(await $.session.cwd(), 'working directory')
83        case 'session':
84          return copy(await $.session.id(), 'session id')
85        case 'usage': {
86          const { context } = await $.session.usage()
87          return `Context ${context.percent ?? '?'}% · ${await $.session.model()}`
88        }
89        case 'compact':
90          await $.command.run({ command: 'compact' })
91          return 'Compacted'
92      }
93    }
94
95    return (
96      <Box flexDirection="column">
97        {ACTIONS.map((action, i) => (
98          <Button
99            key={`hint:${ALPHABET[i]}`}
100            hotkey={ALPHABET[i]}
101            plain
102            onPress={async () => {
103              await $.ui.close({ id: PANE })
104              $.ui.toast(await run(action.id))
105            }}
106          >
107            {action.label}
108          </Button>
109        ))}
110      </Box>
111    )
112  })
113}
114

Install

$claude plugin marketplace add JeongJaeSoon/hintvim

$claude plugin install hintvim@hintvim

Entry name may differ; see the README.

$claude plugin marketplace add https://www.slopshopper.com/community/marketplace.json

$claude plugin install hintvim@slopshopper-community

Points at the author's repo. Nothing re-hosted.

$git clone https://github.com/JeongJaeSoon/hintvim

$claude --plugin-dir ./hintvim/plugin

One session, nothing installed.

In the preview

opens a pane: hintvim
adds /hintvim, /hintvim-palette

Hooks

session.startcommand.run{command=hintvim}command.run{command=hintvim-palette}ui.render{component=Pane, requestId=hintvim}

Reaches

$.command.register$.command.run$.process.run$.session.cwd$.session.id$.session.messages$.session.model$.session.usage$.ui.close$.ui.copy$.ui.open$.ui.resolve$.ui.toast

Checks

validate: passed

Tests ✓ · no state contract · first seen 2026-10-06

Draws

What is hintvim?

Why

Install

What hintvim setup changes

Install from Claude instead

Use

Update

Uninstall

Troubleshooting

Compatibility

How it works

Why an app and not a Claude Code mod?

Without installing anything

Limitations

Development

License

Support

What `hintvim setup` changes