Skip to content
Back to search

hex-upsert

MarketplaceWorks with Claude CodeGitHub

hex-upsert: teach Hex your dictation mishearings from Claude Code's corrections.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ACNoonan/hex-upsert with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ACNoonan/hex-upsert'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/acnoonan--hex-upsert/badge.svg)](/listings/acnoonan--hex-upsert)

HTML

<a href="/listings/acnoonan--hex-upsert"><img src="/api/listings/acnoonan--hex-upsert/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need [Hex](https://anoma.ly/hex), Claude Code and Python 3.9 or later on your PATH. In Claude Code:

/plugin marketplace add ACNoonan/hex-upsert
/plugin install hex-upsert@hex-upsert

Set Hex's history retention to 30 days or Forever in its settings (Hex 3 keeps 7 days by default). The gate checks every pair against your own transcripts, so it needs history to work with.

That's all the setup the default mode needs:

- **Every session**, a `SessionStart` hook tells Claude to tag the mishearings it fixes, as `[heard: "X" → meant: "Y"]`. It tags only a term worth teaching Hex, one you'd want replaced every time you say it (`pie torch` → `PyTorch`). A dropped or swapped ordinary word (`don't` → `do`) gets fixed in context and no tag. You don't edit your `CLAUDE.md`. If your `CLAUDE.md` already has the rule, the hook skips it. - **Once a week**, on your first Claude Code start, the hook runs the cheap read-only steps (about 2 seconds, no model call). If a misheard pair has new evidence on 2 or more days, the least any replacement needs, Claude mentions it once and offers to run the skill. - **The skill** (`/hex-upsert:hex-upsert`) labels every occurrence in your session, gates it and shows you the result. It changes Hex only after you say yes. Once you've reviewed a pair, the hook stays quiet about it until new occurrences turn up.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "hex-upsert",
  3. "owner": {
  4. "name": "Adam Noonan"
  5. },
  6. "description": "hex-upsert: teach Hex your dictation mishearings from Claude Code's corrections.",
  7. "plugins": [
  8. {
  9. "name": "hex-upsert",
  10. "source": "./",
  11. "description": "Turns the dictation mishearings Claude corrects into Hex replacements, gated so a replacement never corrupts a word you really meant."
  12. }
  13. ]
  14. }
README.md · README · 151 lines
  1. # hex-upsert
  2. hex-upsert is a Claude Code plugin for [Hex](https://github.com/anomalyco/hex) dictation. It
  3. turns the mishearings Claude already corrects into Hex replacements, and only the ones that are
  4. safe in every sentence.
  5. ## Why it exists
  6. Hex transcribes speech into Claude Code. When a word comes out wrong, Claude usually reads the
  7. intended meaning and says what it assumed. That correction is lost after the session. hex-upsert
  8. mines those corrections and proposes the ones that are safe to apply to every transcript.
  9. A Hex replacement is a literal, context-free find-and-replace. A naive rule like `sequel → SQL`
  10. would also rewrite every real "sequel". So hex-upsert only promotes a pair when the misheard form
  11. is almost never meant literally, using a zero-failure lower confidence bound on precision. Context
  12. dependent errors stay with Claude.
  13. ## How it fits with Hex's own features
  14. Hex 3 already has two places for a mishearing. Global replacements rewrite one piece of text as
  15. another. Vocabulary holds a name plus the "sounds like" spellings a transcript shows instead.
  16. Both rely on you to notice the mishearing and type it in, and neither tells you whether a rule
  17. is safe to apply everywhere.
  18. hex-upsert does those two parts. It finds the pairs in the corrections Claude already made,
  19. checks each one against your own Hex history, and writes the safe ones to Global replacements.
  20. If you ask, it also adds the intended word to Vocabulary, with the misheard forms as its "sounds
  21. like" spellings. On Parakeet models, Hex uses Vocabulary while transcribing only with Labs ›
  22. Vocabulary help on.
  23. ## Install
  24. You need [Hex](https://anoma.ly/hex), Claude Code and Python 3.9 or later on your PATH. In Claude Code:
  25. ```
  26. /plugin marketplace add ACNoonan/hex-upsert
  27. /plugin install hex-upsert@hex-upsert
  28. ```
  29. Set Hex's history retention to 30 days or Forever in its settings (Hex 3 keeps 7 days by
  30. default). The gate checks every pair against your own transcripts, so it needs history to work
  31. with.
  32. That's all the setup the default mode needs:
  33. - **Every session**, a `SessionStart` hook tells Claude to tag the mishearings it fixes, as
  34. `[heard: "X" → meant: "Y"]`. It tags only a term worth teaching Hex, one you'd want replaced
  35. every time you say it (`pie torch` → `PyTorch`). A dropped or swapped ordinary word
  36. (`don't` → `do`) gets fixed in context and no tag. You don't edit your `CLAUDE.md`. If your
  37. `CLAUDE.md` already has the rule, the hook skips it.
  38. - **Once a week**, on your first Claude Code start, the hook runs the cheap read-only steps
  39. (about 2 seconds, no model call). If a misheard pair has new evidence on 2 or more days, the
  40. least any replacement needs, Claude mentions it once and offers to run the skill.
  41. - **The skill** (`/hex-upsert:hex-upsert`) labels every occurrence in your session, gates it
  42. and shows you the result. It changes Hex only after you say yes. Once you've reviewed a pair,
  43. the hook stays quiet about it until new occurrences turn up.
  44. ## What it's been tested on
  45. **v0.3, early.** It works with Hex 3 on macOS, Linux and Windows, and with Hex 2.3.1 on macOS.
  46. | | Tested how |
  47. |---|---|
  48. | Hex 2.3.1, macOS | On a real install, daily |
  49. | Hex 3.4.0, macOS | On a real install: settings read, replacements applied live through `hex settings apply` |
  50. | Hex 3, Linux and Windows | Against a test double of Hex's `hex` CLI, built from the Hex 3.4.0 source and checked against the real macOS replies. Reports welcome |
  51. | Linux, Windows | The test suite runs there in CI, including installing and removing the weekly job |
  52. ## What it reads, and where it goes
  53. - **Read locally:** your Claude Code session logs (`~/.claude/projects/`, only the assistant's
  54. `[heard → meant]` tags, from the last 60 days) and Hex's `history.json`:
  55. | Hex | Data folder |
  56. |---|---|
  57. | Hex 3, macOS | `~/Library/Application Support/hex` |
  58. | Hex 3, Linux | `$XDG_DATA_HOME/hex`, else `~/.local/share/hex` |
  59. | Hex 3, Windows | `%APPDATA%\hex` |
  60. | Hex 2, macOS | `~/Library/Application Support/voice-control` |
  61. Hex 3 imports nothing from Hex 2. If you upgraded, both folders exist: the tool writes to
  62. Hex 3 and still reads the Hex 2 history as extra evidence.
  63. - **Sent to Claude:** to label a pair, Claude reads a snippet of about 140 characters around each
  64. match in your Hex history. In the default mode that happens inside your own Claude Code
  65. session. In scheduled mode it goes through headless `claude -p` on your subscription.
  66. Nothing goes anywhere else.
  67. - **Written:** only Hex's Global replacements (and vocabulary, if you ask), only after a yes
  68. (or with `--auto-apply`). On Hex 3 the change goes through Hex's own `hex settings apply`,
  69. which validates it and applies it live, with the old value saved to `hex-upsert/backups/`. On
  70. Hex 2 it writes `settings.json` while Hex is quit, with a timestamped backup next to it.
  71. Working files stay in a `hex-upsert` folder beside Hex's data folder.
  72. - **Refused:** if Hex's settings don't have the shape this tool expects (say, after a Hex
  73. update), it writes nothing and tells you which field changed.
  74. ## Run it unattended (optional)
  75. Ask Claude to run `hex-upsert schedule`, or run the installer yourself. Either way it installs a
  76. job that runs Sundays at 04:00, and a missed run happens at the next chance:
  77. | OS | Installer | Job |
  78. |---|---|---|
  79. | macOS | `sh skills/hex-upsert/scripts/schedule.sh` | launchd agent `local.hex-upsert` |
  80. | Linux | `python3 skills/hex-upsert/scripts/schedule.py` | systemd user timer `hex-upsert.timer`. It runs only while you're logged in, unless you run `loginctl enable-linger` |
  81. | Windows | `python skills\hex-upsert\scripts\schedule.py` | Task Scheduler task `hex-upsert`. A console window may flash when it runs |
  82. What the job does:
  83. - It skips the run if Hex was used in the last 30 minutes.
  84. - Headless `claude -p` labels each occurrence twice. Any disagreement becomes `unclear`, so
  85. one judge flip can't decide a pair. The installer refuses unless you're logged in with a
  86. Claude subscription, and the run strips API keys, so it never bills an API account.
  87. - By default it sends a notification when safe corrections are ready, and the next Claude
  88. session offers to apply them. With `schedule --auto-apply` it applies replacements itself
  89. (never vocabulary or hints) and notifies you. On Hex 2 it quits Hex for a few seconds,
  90. relaunches it and rolls back if Hex won't start.
  91. - Your normal `claude` login expires every few weeks. On macOS, to keep the job running, run
  92. `schedule.sh --store-token` once. It runs `claude setup-token` (a long-lived subscription
  93. token), asks you to paste the token into a hidden prompt, checks it with one tiny call, and
  94. stores it in your login Keychain, not in the launchd file. The job reads it at run time.
  95. - If labelling fails, for instance because a login or token expired, it notifies you.
  96. Run data and the log stay in the `hex-upsert` state folder (macOS logs to
  97. `~/Library/Logs/hex-upsert.log`). Remove the job with `--uninstall` on the same installer; on
  98. macOS that also deletes the Keychain token. Re-run the installer after updating: the job runs a
  99. copy of the scripts, so a plugin update can't break a run halfway.
  100. ## Try it without installing
  101. ```sh
  102. ./examples/run_demo.sh
  103. ```
  104. This runs the whole pipeline on synthetic data in a temp folder. It touches nothing else.
  105. `python3 tests/run_tests.py` runs the same pipeline against both Hex generations, on any OS.
  106. How the gate decides is in [`docs/gate.md`](docs/gate.md).
  107. ## First mining run (2026-11-15)
  108. Aggregate numbers only. The raw data stays private.
  109. - 41 correction notes found in Claude Code logs (29 mishearings, 12 typed typos), from 98 regex
  110. candidates, all hand-checked.
  111. - Counting corrections per occurrence badly understates errors: Claude flags a mishearing once,
  112. not every time. One name scored 0.016 on that ratio and its hand-checked error rate was 66 of 66.
  113. - Three pairs were safe on a hand read of every Hex occurrence (24/24, 32/32 and 66/66 errors).
  114. ## Roadmap
  115. 1. Measure word error rate before and after, with Hex's `benchmark-transcription` command.
  116. 2. Verify Hex 3 and the weekly job on a real Linux and Windows desktop.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.