unramble 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayush Yadav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,206 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/wordmark-dark.svg">
+    <img src="assets/wordmark.svg" alt="unramble" width="360">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><b>Press Ctrl+G and the rambling prompt you just dictated becomes the one you meant to type — in place, inside Claude Code, on the plan you already have.</b></p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#what-it-does">What it does</a> ·
+  <a href="#plan-or-api-key">Plan or API key</a> ·
+  <a href="docs/BENCHMARKS.md">Benchmarks</a> ·
+  <a href="docs/HOW-IT-WORKS.md">How it works</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/yadava5/unramble/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/yadava5/unramble/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/unramble"><img alt="npm" src="https://img.shields.io/npm/v/unramble"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude%20Code-plugin-d97757">
+  <img alt="No API key needed" src="https://img.shields.io/badge/API%20key-not%20needed-2ea44f">
+</p>
+
+<p align="center">
+  <img src="assets/demo.gif" alt="A rough dictated prompt is typed into Claude Code, Ctrl+G is pressed, the band reads refining…, and three seconds later the box holds a clean numbered prompt" width="820">
+</p>
+
+You talk faster than you type, so you dictate. Then Claude Code gets *"uh no wait, not the
+handler, the session middleware"* and takes every word literally. unramble rewrites the draft
+before you send it: fillers and false starts gone, the correction applied, separate asks
+numbered, standing rules under *Constraints*. Same meaning — nothing added, nothing you said
+lost. Ctrl+G again puts your original back.
+
+## Install
+
+Pick one. Both install the same plugin and bind Ctrl+G.
+
+**A. In your terminal** (zsh, bash, PowerShell — not inside Claude Code; needs Node 18+):
+
+```sh
+npx unramble
+```
+
+**B. Inside Claude Code** — start `claude`, then type these at its `❯` prompt, one at a time:
+
+```text
+/plugin install unramble --marketplace yadava5/unramble
+/unramble setup
+```
+
+Answer `y` to add the marketplace and pick a scope (user is the default). `setup` binds Ctrl+G;
+it keeps a backup of your `keybindings.json` and never overwrites a key you bound yourself.
+
+Then quit Claude Code and start a new session (`claude`), say or type a prompt, and press
+**Ctrl+G**. Built and tested on Claude Code **2.1.308**; see
+[Where it is tested](#where-it-is-tested).
+
+## What it does
+
+The demo above is a real rewrite (Sonnet on a Claude Code plan, 3.3 s). What was said:
+
+> okay so um the login page is broken again I think, like when you hit submit it just spins
+> forever. can you look at the auth handler, uh no wait, not the handler, the session
+> middleware, that's what changed yesterday. and then once it works add a test for it so this
+> doesn't happen again. oh and don't touch the database migrations, we're kind of mid deploy
+
+What Claude Code gets:
+
+```text
+The login page is broken again, I think: when you hit submit, it spins forever.
+
+1. Look at the session middleware, which is what changed yesterday.
+2. Once it works, add a test for it so this doesn't happen again.
+
+Constraints:
+- Don't touch the database migrations; we're mid deploy.
+```
+
+(It is not perfect: "kind of" mid deploy lost its hedge. The [benchmarks](docs/BENCHMARKS.md)
+count that as a minor defect.)
+
+| Key | Does |
+|---|---|
+| **Ctrl+G** | rewrite the draft (the band above the box says `refining…`) |
+| **Ctrl+G** on the rewrite | put your original back, exactly |
+| **Ctrl+G** while it runs | cancel; your draft stays |
+
+### What it will not do
+
+- **Send anything you did not ask it to.** Nothing leaves the box until you press Ctrl+G.
+- **Lose a machine value.** A rewrite that drops a path, `--flag`, number, URL, `@ref` or
+  `[Pasted text]` chip is refused and your draft stays — unless you corrected that value on
+  the spot ("src/utils, no wait, src/lib").
+- **Touch pasted logs or code.** They are masked before the model sees the draft and put back
+  byte for byte.
+- **Answer your question or do the task.** "Can you check X?" stays a question for Claude Code.
+- **Overwrite you.** If you typed while it ran, your text wins.
+
+## Plan or API key
+
+| Engine | Pays with | Setup | Default |
+|---|---|---|---|
+| `plan` | your Claude Code subscription, like any prompt | none | ✓ |
+| `api` | your own Anthropic API key, per rewrite | [a separate opt-in step](docs/API-KEY.md) | |
+
+The plan engine calls the model through your Claude Code session's own login
+(`$.model.complete`), so there is no key anywhere in the plugin. Each rewrite is one short
+call: ~3k tokens of rules (cached after the first rewrite) plus your words.
+
+The API engine exists for people who would rather pay a fraction of a cent per rewrite than
+spend plan usage. It stays off until you switch it on, the key lives in Claude Code's secure
+storage, and a failed API call never falls back to your plan. Read
+[docs/API-KEY.md](docs/API-KEY.md) — and the ~100 lines of
+[`hooks/engine.ts`](hooks/engine.ts) — before you paste a key in.
+
+## Settings
+
+`/config` (the unramble rows), or `claude plugin configure unramble`:
+
+| Setting | Default | |
+|---|---|---|
+| Engine | `plan` | `plan` or `api` |
+| Model | `sonnet` | `sonnet` (fast, light on your plan) or `opus` (the most faithful) |
+| Names you often say | empty | comma-separated names of your tools, agents and projects, so a dictation slip is spelled right |
+| Anthropic API key | empty | read only when Engine is `api` |
+
+`/unramble status` shows what is live.
+
+## How good is it
+
+Measured on 39 of the hardest real dictated prompts, two runs each, with Claude Opus judging
+every rewrite against a fixed rubric ([method and full tables](docs/BENCHMARKS.md)):
+
+| Model | Rewrites with no meaning change | Median time |
+|---|---|---|
+| Sonnet (default) | 76/78 | 3.0 s |
+| Opus | 78/78 | 3.2 s |
+
+That set is every case that ever failed during tuning, so it is harder than everyday speech.
+It is also one person's speech, in English, about software; the [eval kit](eval/README.md)
+runs the same check on yours. Haiku was tried and dropped (9 major errors in 17 prompts).
+
+## Where it is tested
+
+Ctrl+G reaches the plugin as whatever bytes the terminal sends for it, and terminals send it
+two ways, so both were tried with a real keypress:
+
+| Where | Ctrl+G arrives as | Result |
+|---|---|---|
+| kitty, macOS | kitty keyboard protocol | rewrite, restore, cancel, `/unramble status` ✓ |
+| Terminal.app, macOS | legacy `0x07` | rewrite and restore ✓ |
+| Ghostty 1.3, macOS | not measured | rewrite and restore ✓ |
+| VS Code terminal, macOS | not measured | rewrite and restore ✓ (Ctrl+G reaches Claude Code, not VS Code's *Go to Line*) |
+| Cursor terminal, macOS | not measured | rewrite and restore ✓ |
+| Linux (Debian, tmux) | legacy `0x07` | key reaches the plugin and the model call goes out ✓ |
+| Windows, Linux, macOS (CI) | — | install, Ctrl+G binding, uninstall and all tests, every push |
+
+Not yet tried by hand: iTerm2, Windows Terminal, and Kiro's terminal (Kiro is built on the same
+editor as VS Code and Cursor). If one does not work, please
+[open an issue](https://github.com/yadava5/unramble/issues/new/choose).
+
+## Limits
+
+- **Terminal UI only.** The Ctrl+G chord reaches plugins in Claude Code's terminal interface
+  (`claude` run in a terminal, including the one inside VS Code or Cursor). The VS Code
+  extension's own chat panel and the desktop app are not supported.
+- **A short window can hide the band.** In an 80×24 window with a tall status line, Claude Code
+  may not draw the `⌃G refine` row; Ctrl+G still works.
+- **Long pastes stay as chips.** When a dictation app pastes a long block, Claude Code folds it
+  into a `[Pasted text #N]` chip that plugins cannot read in 2.1.308, so that text is kept as
+  is. Claude Code's built-in voice input, macOS Dictation and typing all work fully.
+- **Garbled speech stays garbled.** If the transcription is wrong in a way context cannot fix
+  ("Apple ID" for a project name), the rewrite keeps it as heard rather than guess. Add the
+  name to *Names you often say*.
+- **The plugin API is early access.** CI runs the latest Claude Code weekly to catch a release
+  that moves it.
+
+## Uninstall
+
+```sh
+npx unramble uninstall
+```
+
+That removes the plugin and takes back only the two `ctrl+g` bindings setup added. Without
+Node: `claude plugin uninstall unramble@unramble`, then delete those two lines from
+`keybindings.json` yourself.
+
+## Where it came from
+
+I dictate long prompts into Claude Code and wanted them organised before the model reads
+them. It started as a personal `$VISUAL` script on 2026-10-17 and went through eight rule
+versions in two days, each measured before it shipped; the history is in the git log and
+[docs/BENCHMARKS.md](docs/BENCHMARKS.md). This public version is a rebuild that runs on your
+plan instead of an API key. I used Claude Code to build it.
+
+## Contributing
+
+Reports of a rewrite that changed your meaning are the most useful thing you can send; there
+is an [issue template](https://github.com/yadava5/unramble/issues/new/choose) for it. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Ayush Yadav

package/cli/unramble.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// npx unramble [install | uninstall | status] — sets the plugin up in one paste.
+//
+// install:   claude plugin install unramble --marketplace yadava5/unramble, then binds Ctrl+G
+//            in keybindings.json (a backup is kept beside it).
+// uninstall: removes the plugin and takes back only the keybindings install added.
+// status:    shows whether the plugin is installed and Ctrl+G is bound.
+//
+// No dependencies. It changes nothing but the plugin install and those two keybindings.
+
+import { spawnSync } from 'node:child_process'
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import { isBound, parse, plan, serialize, unplan } from '../hooks/keybindings.js'
+
+const MARKETPLACE = process.env.UNRAMBLE_MARKETPLACE || 'yadava5/unramble'
+const PLUGIN = 'unramble'
+const configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude')
+const keybindings = join(configDir, 'keybindings.json')
+
+const say = (line = '') => process.stdout.write(`${line}\n`)
+const fail = line => {
+  process.stderr.write(`unramble: ${line}\n`)
+  process.exit(1)
+}
+
+/** Runs `claude` with the person's own environment and terminal; true on success. */
+function claude(args, { quiet = false } = {}) {
+  const r = spawnSync('claude', args, {
+    stdio: quiet ? 'pipe' : 'inherit',
+    shell: process.platform === 'win32',
+    encoding: 'utf8',
+  })
+  if (r.error?.code === 'ENOENT') {
+    fail('Claude Code is not on your PATH. Install it first: https://code.claude.com/docs/en/setup')
+  }
+  return { ok: r.status === 0, out: `${r.stdout ?? ''}${r.stderr ?? ''}` }
+}
+
+function readKeys() {
+  const text = existsSync(keybindings) ? readFileSync(keybindings, 'utf8') : null
+  try {
+    return { text, file: parse(text) }
+  } catch (err) {
+    fail(`${keybindings} is not valid keybindings JSON (${err.message}); left it alone.`)
+  }
+}
+
+function bindKeys() {
+  const { text, file } = readKeys()
+  const next = plan(file)
+  if (next.kind === 'ready') return say('✓ Ctrl+G was already bound')
+  if (next.kind === 'conflict') {
+    say(`! Left keybindings alone: ${next.why}.`)
+    say(`  Free that chord in ${keybindings}, then run /unramble setup in Claude Code.`)
+    return
+  }
+  if (text !== null) copyFileSync(keybindings, `${keybindings}.unramble-backup`)
+  writeFileSync(keybindings, serialize(next.file))
+  say(`✓ Bound Ctrl+G in ${keybindings}${text !== null ? ' (backup: keybindings.json.unramble-backup)' : ''}`)
+  for (const c of next.changes) say(`    ${c}`)
+}
+
+function install() {
+  say(`Installing unramble from ${MARKETPLACE}…`)
+  if (!claude(['plugin', 'install', PLUGIN, '--marketplace', MARKETPLACE]).ok) {
+    fail('the plugin install did not finish; nothing else was changed.')
+  }
+  bindKeys()
+  say()
+  say('Done. Start a new Claude Code session, speak or type a rough prompt, and press Ctrl+G.')
+  say('It runs on your Claude Code plan. Settings: /config (unramble rows) or /unramble status.')
+}
+
+function uninstall() {
+  const removed = claude(['plugin', 'uninstall', `${PLUGIN}@${PLUGIN}`]).ok
+  if (removed) claude(['plugin', 'marketplace', 'remove', PLUGIN], { quiet: true })
+  const { text, file } = readKeys()
+  const back = unplan(file)
+  if (back.changes.length) {
+    if (text !== null) copyFileSync(keybindings, `${keybindings}.unramble-backup`)
+    writeFileSync(keybindings, serialize(back.file))
+    say(`✓ Took back the Ctrl+G bindings in ${keybindings}`)
+  }
+  say(removed ? '✓ unramble is uninstalled' : '! The plugin was not installed (or the uninstall failed); see above.')
+}
+
+function status() {
+  const listed = claude(['plugin', 'list'], { quiet: true })
+  const installed = new RegExp(`\\b${PLUGIN}@`).test(listed.out)
+  say(`Plugin:  ${installed ? 'installed' : 'not installed'}`)
+  say(`Ctrl+G:  ${isBound(readKeys().file) ? 'bound' : 'not bound'} (${keybindings})`)
+}
+
+const command = process.argv[2] ?? 'install'
+const commands = { install, uninstall, status }
+if (command === '--help' || command === '-h' || !(command in commands)) {
+  say('Usage: npx unramble [install | uninstall | status]')
+  process.exit(command in commands || command.startsWith('-') ? 0 : 1)
+}
+commands[command]()

package/hooks/keybindings.js

@@ -0,0 +1,132 @@
+// @ts-check
+// Ctrl+G reaches a plugin only through a band Button naming an engine keybinding action that
+// no engine handler holds while the prompt is focused, and only when that chord is bound in the
+// Global context. So setup binds Global ctrl+g to app:cycleDiffBase (handled only while the diff
+// panel is open, where it keeps working) and unbinds Chat ctrl+g (by default the external
+// editor, which stays on ctrl+x ctrl+e). A chord the person bound to something else is theirs:
+// setup reports the conflict and changes nothing.
+//
+// Plain JavaScript on purpose: the plugin imports it, and so does the npx installer, which runs
+// from a package cache where Node will not strip TypeScript.
+
+export const ACTION = 'app:cycleDiffBase'
+export const CHORD = 'ctrl+g'
+const EDITOR = 'chat:externalEditor'
+const EDITOR_CHORD = 'ctrl+x ctrl+e'
+
+/** @typedef {Record<string, string | null>} Bindings */
+/** @typedef {{ context: string, bindings: Bindings }} Block */
+/** @typedef {{ bindings: Block[], [key: string]: unknown }} KeybindingsFile */
+/**
+ * @typedef {{ kind: 'ready' }
+ *   | { kind: 'change', file: KeybindingsFile, changes: string[] }
+ *   | { kind: 'conflict', why: string }} SetupPlan
+ */
+
+/** @type {KeybindingsFile} */
+const SKELETON = {
+  $schema: 'https://www.schemastore.org/claude-code-keybindings.json',
+  $docs: 'https://code.claude.com/docs/en/keybindings',
+  bindings: [],
+}
+
+/** @param {KeybindingsFile} file @returns {KeybindingsFile} */
+const clone = file => JSON.parse(JSON.stringify(file))
+
+/**
+ * Parses keybindings.json text; an absent file is an empty one. Throws on anything else.
+ * @param {string | null} text
+ * @returns {KeybindingsFile}
+ */
+export function parse(text) {
+  if (text === null || !text.trim()) return clone(SKELETON)
+  const data = JSON.parse(text)
+  if (!data || typeof data !== 'object' || !Array.isArray(data.bindings)) {
+    throw new Error('keybindings.json has no "bindings" list')
+  }
+  return data
+}
+
+/** @param {KeybindingsFile} file @param {string} context @returns {Block | undefined} */
+const blockOf = (file, context) =>
+  file.bindings.find(b => b && b.context === context && b.bindings && typeof b.bindings === 'object')
+
+/**
+ * Whether Ctrl+G already reaches unramble.
+ * @param {KeybindingsFile} file
+ */
+export function isBound(file) {
+  return blockOf(file, 'Global')?.bindings[CHORD] === ACTION && blockOf(file, 'Chat')?.bindings[CHORD] === null
+}
+
+/**
+ * What setup would do to this file, without doing it.
+ * @param {KeybindingsFile} current
+ * @returns {SetupPlan}
+ */
+export function plan(current) {
+  if (isBound(current)) return { kind: 'ready' }
+  const globalNow = blockOf(current, 'Global')?.bindings[CHORD]
+  if (globalNow !== undefined && globalNow !== ACTION) {
+    return { kind: 'conflict', why: `ctrl+g is bound to "${globalNow}" in your Global keybindings` }
+  }
+  const chatNow = blockOf(current, 'Chat')?.bindings[CHORD]
+  if (chatNow !== undefined && chatNow !== null && chatNow !== EDITOR) {
+    return { kind: 'conflict', why: `ctrl+g is bound to "${chatNow}" in your Chat keybindings` }
+  }
+
+  const file = clone(current)
+  /** @type {string[]} */
+  const changes = []
+  /** @param {string} context @returns {Block} */
+  const ensure = context => {
+    let block = blockOf(file, context)
+    if (!block) {
+      block = { context, bindings: {} }
+      file.bindings.push(block)
+    }
+    return block
+  }
+  const global = ensure('Global')
+  if (global.bindings[CHORD] !== ACTION) {
+    global.bindings[CHORD] = ACTION
+    changes.push(`Global: ctrl+g → ${ACTION} (lets the unramble band take Ctrl+G)`)
+  }
+  const chat = ensure('Chat')
+  if (chat.bindings[CHORD] !== null) {
+    chat.bindings[CHORD] = null
+    changes.push('Chat: ctrl+g → unbound (it opened the external editor)')
+  }
+  if (!Object.values(chat.bindings).includes(EDITOR) && chat.bindings[EDITOR_CHORD] === undefined) {
+    chat.bindings[EDITOR_CHORD] = EDITOR
+    changes.push(`Chat: ${EDITOR_CHORD} → ${EDITOR} (the external editor keeps a key)`)
+  }
+  return { kind: 'change', file, changes }
+}
+
+/**
+ * Takes back exactly what setup added, and nothing the person set themselves: Global ctrl+g
+ * only while it still names unramble's action, Chat ctrl+g only while it is still unbound.
+ * The ctrl+x ctrl+e editor key stays; it is Claude Code's own action.
+ * @param {KeybindingsFile} current
+ * @returns {{ file: KeybindingsFile, changes: string[] }}
+ */
+export function unplan(current) {
+  const file = clone(current)
+  /** @type {string[]} */
+  const changes = []
+  const global = blockOf(file, 'Global')
+  if (global?.bindings[CHORD] === ACTION) {
+    delete global.bindings[CHORD]
+    changes.push('Global: ctrl+g removed')
+  }
+  const chat = blockOf(file, 'Chat')
+  if (chat && chat.bindings[CHORD] === null) {
+    delete chat.bindings[CHORD]
+    changes.push('Chat: ctrl+g back to its default (the external editor)')
+  }
+  return { file, changes }
+}
+
+/** @param {KeybindingsFile} file */
+export const serialize = file => `${JSON.stringify(file, null, 2)}\n`

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "unramble",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Ctrl+G turns a rambling, dictated prompt into a clean, ordered one, in place, on your own Claude Code plan.",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "dictation",
+    "voice",
+    "prompt",
+    "rewrite"
+  ],
+  "homepage": "https://github.com/yadava5/unramble#readme",
+  "bugs": "https://github.com/yadava5/unramble/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yadava5/unramble.git"
+  },
+  "license": "MIT",
+  "author": "Ayush Yadav (https://github.com/yadava5)",
+  "type": "module",
+  "bin": {
+    "unramble": "cli/unramble.mjs"
+  },
+  "files": [
+    "cli/unramble.mjs",
+    "hooks/keybindings.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "claude plugin validate . && claude plugin test . && node --test cli/*.test.mjs",
+    "test:cli": "node --test cli/*.test.mjs"
+  }
+}