@searls/turbocommit 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Searls LLC
+
+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

@@ -0,0 +1,179 @@
+[![Certified Shovelware](https://justin.searls.co/img/shovelware.svg)](https://justin.searls.co/shovelware/)
+
+# turbocommit
+
+turbocommit creates a git commit containing everything Claude Code changes 
+on each turn. Think of it like save state in a game emulator: whenever you 
+fall in a pit, you can safely rewind and try again.
+
+Captures every prompt/response transcript for the associated changes so you 
+and your agent never lose the thread on what you were doing after the fact,
+even if you didn't leave behind any comments or docs.
+
+Each commit also [links back to the previous commit from the same Claude Code
+session](#continuity-across-workstreams), so you can run multiple agent 
+sessions concurrently and detangle which agent committed what after the fact.
+
+## How it works
+
+turbocommit registers four hooks with Claude Code: **PreToolUse**,
+**SessionStart**, **SessionEnd**, and **Stop**.
+
+- **PreToolUse** tracks which sessions actually modify files (Write, Edit,
+  MultiEdit, NotebookEdit, MCP tools). Read-only sessions (Grep, Read,
+  Bash-only) are never committed.
+- **SessionStart / SessionEnd** chain sessions across `/clear` boundaries
+  so planning context survives into the eventual commit.
+- **Stop** fires after every turn. If the session modified files, it
+  commits with `git add -A`. If not, it buffers the transcript for pickup
+  by a later session that does commit.
+
+The commit message headline is generated by a title agent (configurable).
+The body contains the full prompt/response transcript. When planning
+context was buffered from ancestor sessions, it appears under a
+`## Planning` section before the `## Implementation` section.
+
+## Install
+
+```bash
+brew install searlsco/tap/turbocommit
+turbocommit install
+```
+
+Then enable it per-project:
+
+```bash
+cd your-repo
+turbocommit init
+```
+
+## Uninstall
+
+```bash
+turbocommit deinit     # disable in a project
+turbocommit uninstall  # remove the global hook
+brew uninstall turbocommit
+```
+
+## Where turbocommit goes in your hook chain
+
+`turbocommit install` adds one hook group per event (PreToolUse,
+SessionStart, SessionEnd, Stop). The hooks are fire-and-forget: they
+always exit 0 and never block Claude.
+
+If you rearrange your hooks manually, the turbocommit hooks can go
+anywhere — order doesn't matter since they never block.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `turbocommit install` | Add hooks to `~/.claude/settings.json` |
+| `turbocommit uninstall` | Remove them |
+| `turbocommit init` | Create `.claude/turbocommit.json` in current repo |
+| `turbocommit deinit` | Remove it |
+| `turbocommit doctor` | Check hook and config health |
+| `turbocommit monitor` | Tail the event log (start/success/skip/fail) |
+| `turbocommit help` | Show usage |
+| `turbocommit --version` | Show version |
+
+## Continuity across workstreams
+
+Every turbocommit adds a `Continuation of <SHA>` reference linking back to
+the previous commit from the same Claude session. This means you can run
+multiple sessions in parallel — different tabs, different tasks — all
+committing to a single branch, and still trace each logical workstream
+by following the SHA chain.
+
+Here's a real stretch of [`prove_it`](https://github.com/searlsco/prove_it)'s
+`main` branch. Two sessions and a couple manual commits, all interleaved:
+
+1. [`cb20f72`](https://github.com/searlsco/prove_it/commit/cb20f72) 🔵 Fix PROVE_IT_DISABLED leak in integration tests
+2. [`cff5a2e`](https://github.com/searlsco/prove_it/commit/cff5a2e) 🔵 Fix env variable leaks in integration test harness
+3. [`5c3ca43`](https://github.com/searlsco/prove_it/commit/5c3ca43) 🟠 Fix reviewer rationale parsing for multi-line verdicts
+4. [`6f22cee`](https://github.com/searlsco/prove_it/commit/6f22cee) 🟠 Remove dead cached output filter and JSDoc
+5. [`efca526`](https://github.com/searlsco/prove_it/commit/efca526) v0.44.0
+6. [`1561c46`](https://github.com/searlsco/prove_it/commit/1561c46) update conifg
+7. [`de771db`](https://github.com/searlsco/prove_it/commit/de771db) 🟠 Fix init to preserve custom sources during config upgrade
+8. [`538fc72`](https://github.com/searlsco/prove_it/commit/538fc72) 🟠 Fix signal command to fail honestly outside hook context
+
+Each linked commit's description starts with the reference back:
+
+```
+Fix signal command to fail honestly outside hook context
+
+Continuation of de771db
+
+Prompt:
+...
+```
+
+So after the fact, you can reconstruct each session's lineage:
+
+**🟠 Session A:** [`5c3ca43`](https://github.com/searlsco/prove_it/commit/5c3ca43) → [`6f22cee`](https://github.com/searlsco/prove_it/commit/6f22cee) → [`de771db`](https://github.com/searlsco/prove_it/commit/de771db) → [`538fc72`](https://github.com/searlsco/prove_it/commit/538fc72)
+
+**🔵 Session B:** [`cb20f72`](https://github.com/searlsco/prove_it/commit/cb20f72) → [`cff5a2e`](https://github.com/searlsco/prove_it/commit/cff5a2e)
+
+No feature branches. No rebasing. Just a flat history where every thread
+is traceable.
+
+## Configuration
+
+`turbocommit init` creates `.claude/turbocommit.json` with `{"enabled": true}`.
+You can also place a global config at `~/.claude/turbocommit.json` — project
+config is deep-merged on top.
+
+Here's every property with its default:
+
+```jsonc
+{
+  // Required. turbocommit is inert unless this is true.
+  "enabled": true,
+
+  // Co-Authored-By trailer.
+  //   true  → auto-detect model from transcript (default)
+  //   false → no trailer
+  //   "Name <email>" → custom trailer value
+  "coauthor": true,
+
+  "title": {
+    // "agent" (default) → run a title agent to generate the headline
+    // "transcript"      → extract the first prompt as the headline
+    "type": "agent",
+
+    // Command to run for title generation (only when type is "agent").
+    "command": "claude -p --model haiku",
+
+    // Prompt template sent to the title agent. Use {{transcript}} as the
+    // placeholder for the session transcript.
+    "prompt": "You have 10 seconds. Write a single-line git commit headline (max 72 chars) from this coding session transcript. Speed over perfection — a rough title beats no title.\n\nRules:\n- Imperative mood (\"Add\", \"Fix\", \"Update\")\n- Specific about what changed\n- No trailing period\n- No conventional commit prefixes unless clearly a fix/feat\n\nTranscript:\n{{transcript}}\n\nRespond with ONLY the headline, nothing else. Do not deliberate."
+  },
+
+  "body": {
+    // "transcript" (default) → use the formatted prompt/response transcript
+    // "agent"                → run a body agent to summarize
+    "type": "transcript",
+
+    // Command to run for body generation (only when type is "agent").
+    "command": "claude -p --model haiku",
+
+    // Prompt template sent to the body agent. Use {{transcript}} as the
+    // placeholder for the session transcript.
+    "prompt": "Given this transcript of a coding session, write a concise git commit body.\n\nRules:\n- Summarize what was done and why\n- Be concise — a few sentences or bullet points\n- Focus on the \"why\" more than the \"what\"\n\nTranscript:\n{{transcript}}\n\nRespond with ONLY the commit body, nothing else.",
+
+    // Wrap prose lines at this width. Code blocks, tables, headers, and
+    // other structured content are preserved verbatim.
+    // false/absent → no wrapping (default).
+    "maxLineLength": false
+  }
+}
+```
+
+Set `TURBOCOMMIT_DISABLED` to any non-empty value to skip turbocommit at
+runtime without changing config.
+
+## Requirements
+
+- Node.js >= 18
+- Git
+- Claude Code

package/cli.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+const { readStdin } = require('./lib/io')
+const { install, uninstall } = require('./lib/install')
+const { init, deinit } = require('./lib/init')
+const { run } = require('./lib/run')
+const { handleTrack } = require('./lib/track')
+const { handleSessionStart, handleSessionEnd } = require('./lib/session')
+const { doctor } = require('./lib/doctor')
+const { monitor } = require('./lib/monitor')
+const { gitRoot } = require('./lib/git')
+
+const VERSION = require('./package.json').version
+
+const USAGE = `turbocommit v${VERSION}
+Auto-commit after every Claude Code turn.
+
+Commands:
+  install     Add turbocommit hooks to ~/.claude/settings.json
+  uninstall   Remove turbocommit from settings
+  init        Create .claude/turbocommit.json in current git repo
+  deinit      Remove .claude/turbocommit.json
+  doctor      Check hook and config health
+  monitor     Tail the event log (start/success/fail)
+  hook        Hook entry points (called by Claude Code, not manually)
+  help        Show this help text
+  --version, -v  Show version
+
+Usage:
+  turbocommit install     # set up the global hooks
+  turbocommit init        # enable in a project
+  turbocommit doctor      # verify everything is wired correctly
+  turbocommit monitor     # watch commits in real-time
+`
+
+function main (argv) {
+  const cmd = argv[0]
+
+  switch (cmd) {
+    case 'install':
+      return cmdInstall()
+    case 'uninstall':
+      return cmdUninstall()
+    case 'doctor':
+      return cmdDoctor()
+    case 'monitor':
+      return cmdMonitor()
+    case 'init':
+      return cmdInit()
+    case 'deinit':
+      return cmdDeinit()
+    case 'hook':
+      return cmdHook(argv.slice(1))
+    case 'run':
+      return cmdRunDeprecated()
+    case '--version':
+    case '-v':
+    case 'version':
+      console.log(VERSION)
+      return
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      console.log(USAGE)
+      return
+    default:
+      console.error(`Unknown command: ${cmd}`)
+      console.error('Run "turbocommit help" for usage.')
+      process.exitCode = 1
+  }
+}
+
+function cmdInstall () {
+  const result = install()
+  if (result.alreadyInstalled) {
+    console.log('turbocommit already installed.')
+    console.log(`  Settings: ${result.settingsPath}`)
+    return
+  }
+  console.log('turbocommit installed.')
+  console.log(`  Settings: ${result.settingsPath}`)
+  console.log('')
+  console.log('════════════════════════════════════════════════════════════════════')
+  console.log('IMPORTANT: Restart Claude Code for the hooks to take effect.')
+  console.log('════════════════════════════════════════════════════════════════════')
+  console.log('')
+  console.log('Next steps:')
+  console.log('  1. Restart Claude Code (required)')
+  console.log('  2. Run: turbocommit init  in a repo to enable auto-commits')
+}
+
+function cmdUninstall () {
+  const result = uninstall()
+  if (!result.wasInstalled) {
+    console.log('turbocommit was not installed.')
+    return
+  }
+  console.log('turbocommit uninstalled.')
+  console.log(`  Settings: ${result.settingsPath}`)
+}
+
+function cmdInit () {
+  const result = init()
+  if (!result.ok) {
+    console.error(`Error: ${result.error}`)
+    process.exitCode = 1
+    return
+  }
+  if (result.alreadyExists) {
+    console.log('turbocommit already enabled in this repo.')
+    console.log(`  Config: ${result.path}`)
+    return
+  }
+  console.log('turbocommit enabled.')
+  console.log(`  Config: ${result.path}`)
+}
+
+function cmdDeinit () {
+  const result = deinit()
+  if (!result.ok) {
+    console.error(`Error: ${result.error}`)
+    process.exitCode = 1
+    return
+  }
+  if (!result.existed) {
+    console.log('turbocommit was not enabled in this repo.')
+    return
+  }
+  console.log('turbocommit disabled.')
+  console.log(`  Removed: ${result.path}`)
+}
+
+function cmdDoctor () {
+  const STATUS = { ok: '  ok', warn: 'warn', error: ' err', info: 'info' }
+  const result = doctor()
+  for (const check of result.checks) {
+    console.log(`[${STATUS[check.status] || check.status}] ${check.name}: ${check.message}`)
+  }
+  if (!result.ok) {
+    process.exitCode = 1
+  }
+}
+
+function cmdMonitor () {
+  monitor()
+}
+
+function cmdHook (argv) {
+  const event = argv[0]
+  try {
+    const input = readStdin()
+    const root = gitRoot()
+    switch (event) {
+      case 'pre-tool-use':
+        handleTrack(input, root)
+        return
+      case 'session-start':
+        handleSessionStart(input, root)
+        return
+      case 'session-end':
+        handleSessionEnd(input, root)
+        return
+      case 'stop':
+        run(input)
+        break
+      default:
+        // Unknown hook event — ignore silently (never fail)
+        break
+    }
+  } catch {
+    // Never fail — fire and forget
+  }
+}
+
+function cmdRunDeprecated () {
+  let hookInput
+  try {
+    hookInput = JSON.parse(readStdin())
+  } catch {
+    hookInput = {}
+  }
+  // Prevent infinite loop: if we already blocked once, let Claude stop
+  if (hookInput.stop_hook_active) return
+  const msg = 'turbocommit hooks are outdated (v0.6). ' +
+    'Auto-commits are paused until you upgrade. ' +
+    'Run: turbocommit install'
+  // Block the stop so the agent sees the reason and can relay it to the user
+  const output = JSON.stringify({ decision: 'block', reason: msg })
+  process.stdout.write(output + '\n')
+}
+
+main(process.argv.slice(2))

package/lib/agent.js

@@ -0,0 +1,77 @@
+const { tryRun } = require('./io')
+
+const DEFAULT_COMMAND = 'claude -p --model haiku'
+
+const DEFAULT_TITLE_PROMPT = `You have 10 seconds. Write a single-line git commit headline (max 72 chars) from this coding session transcript. Speed over perfection — a rough title beats no title.
+
+Rules:
+- Imperative mood ("Add", "Fix", "Update")
+- Specific about what changed
+- No trailing period
+- No conventional commit prefixes unless clearly a fix/feat
+
+Transcript:
+{{transcript}}
+
+Respond with ONLY the headline, nothing else. Do not deliberate.`
+
+const DEFAULT_BODY_PROMPT = `Given this transcript of a coding session, write a concise git commit body.
+
+Rules:
+- Summarize what was done and why
+- Be concise — a few sentences or bullet points
+- Focus on the "why" more than the "what"
+
+Transcript:
+{{transcript}}
+
+Respond with ONLY the commit body, nothing else.`
+
+function renderPrompt (template, transcript) {
+  return template.replace(/\{\{transcript\}\}/g, () => transcript)
+}
+
+function runAgent (root, command, prompt) {
+  const binary = command.split(/\s+/)[0]
+  const whichResult = tryRun(`which ${binary}`, {})
+  if (whichResult.code !== 0) return null
+
+  const result = tryRun(command, {
+    cwd: root,
+    timeout: 45000,
+    input: prompt,
+    env: { ...process.env, TURBOCOMMIT_DISABLED: '1', CLAUDECODE: '' }
+  })
+
+  if (result.code !== 0) return null
+
+  const output = (result.stdout.trim() || result.stderr.trim())
+  return output || null
+}
+
+function runTitleAgent (root, titleCfg, transcript) {
+  const command = titleCfg.command || DEFAULT_COMMAND
+  const template = titleCfg.prompt || DEFAULT_TITLE_PROMPT
+  const prompt = renderPrompt(template, transcript)
+  const result = runAgent(root, command, prompt)
+  if (!result) return null
+  // Take only first line and enforce 72 char limit
+  return result.split('\n')[0].slice(0, 72) || null
+}
+
+function runBodyAgent (root, bodyCfg, transcript) {
+  const command = bodyCfg.command || DEFAULT_COMMAND
+  const template = bodyCfg.prompt || DEFAULT_BODY_PROMPT
+  const prompt = renderPrompt(template, transcript)
+  return runAgent(root, command, prompt)
+}
+
+module.exports = {
+  DEFAULT_COMMAND,
+  DEFAULT_TITLE_PROMPT,
+  DEFAULT_BODY_PROMPT,
+  renderPrompt,
+  runAgent,
+  runTitleAgent,
+  runBodyAgent
+}

package/lib/doctor.js

@@ -0,0 +1,101 @@
+const os = require('os')
+const path = require('path')
+const { loadJson, mergeConfig } = require('./io')
+const { hasTurbocommit, isFullyInstalled, getSettingsPath, HOOK_DEFS } = require('./install')
+const { gitRoot } = require('./git')
+const { configPath } = require('./init')
+
+function globalConfigPath () {
+  return path.join(os.homedir(), '.claude', 'turbocommit.json')
+}
+
+function doctor (settingsPath, cwd) {
+  settingsPath = settingsPath || getSettingsPath()
+  cwd = cwd || process.cwd()
+  const checks = []
+
+  // 1. Global settings exist
+  const settings = loadJson(settingsPath)
+  if (!settings) {
+    checks.push({ name: 'Global settings', status: 'error', message: `Not found: ${settingsPath}` })
+    return { ok: false, checks }
+  }
+  checks.push({ name: 'Global settings', status: 'ok', message: settingsPath })
+
+  // 2. All hooks installed
+  if (!isFullyInstalled(settings)) {
+    const missing = Object.keys(HOOK_DEFS).filter(event =>
+      !hasTurbocommit((settings.hooks && settings.hooks[event]) || [])
+    )
+    checks.push({ name: 'Hooks installed', status: 'error', message: `Missing hooks: ${missing.join(', ')}. Run: turbocommit uninstall && turbocommit install` })
+    return { ok: false, checks }
+  }
+  checks.push({ name: 'Hooks installed', status: 'ok', message: `All ${Object.keys(HOOK_DEFS).length} hooks installed` })
+
+  // 3. Stop group isolation — turbocommit must be the sole hook in the last group
+  const stopGroups = (settings.hooks && settings.hooks.Stop) || []
+  const tcGroupIndex = findTurbocommitGroup(stopGroups)
+  if (tcGroupIndex >= 0) {
+    const tcGroup = stopGroups[tcGroupIndex]
+    const isLastGroup = tcGroupIndex === stopGroups.length - 1
+    const isSoleHook = tcGroup.hooks.length === 1
+
+    if (!isSoleHook) {
+      checks.push({ name: 'Group isolation', status: 'warn', message: 'turbocommit shares a Stop group with other hooks — will commit even if another hook blocks' })
+    } else if (!isLastGroup) {
+      checks.push({ name: 'Group isolation', status: 'warn', message: 'Another group runs after turbocommit in Stop' })
+    } else {
+      checks.push({ name: 'Group isolation', status: 'ok', message: 'Sole hook in last Stop group' })
+    }
+  }
+
+  // 4. Global turbocommit config
+  const globalPath = globalConfigPath()
+  const globalCfg = loadJson(globalPath)
+  if (globalCfg) {
+    checks.push({ name: 'Global config', status: 'ok', message: globalPath })
+  } else {
+    checks.push({ name: 'Global config', status: 'info', message: 'Not found (optional)' })
+  }
+
+  // 5. Local config exists
+  const root = gitRoot(cwd)
+  if (!root) {
+    checks.push({ name: 'Local config', status: 'info', message: 'Not in a git repo — skipping local checks' })
+  } else {
+    const localPath = configPath(root)
+    const localConfig = loadJson(localPath)
+    if (!localConfig) {
+      if (globalCfg) {
+        checks.push({ name: 'Local config', status: 'info', message: 'Not found (using global config)' })
+      } else {
+        checks.push({ name: 'Local config', status: 'warn', message: `Not found: ${localPath}. Run: turbocommit init` })
+      }
+    } else {
+      checks.push({ name: 'Local config', status: 'ok', message: localPath })
+    }
+
+    // 6. Enabled — evaluate merged config
+    const merged = mergeConfig(globalCfg || {}, localConfig || {})
+    if (merged.enabled !== true) {
+      checks.push({ name: 'Enabled', status: 'warn', message: 'enabled is not true in merged config' })
+    } else {
+      checks.push({ name: 'Enabled', status: 'ok', message: 'Enabled' })
+    }
+  }
+
+  const ok = checks.every(c => c.status !== 'error')
+  return { ok, checks }
+}
+
+function findTurbocommitGroup (groups) {
+  for (let i = 0; i < groups.length; i++) {
+    const hooks = (groups[i] && groups[i].hooks) || []
+    if (hooks.some(h => h.command && h.command.includes('turbocommit'))) {
+      return i
+    }
+  }
+  return -1
+}
+
+module.exports = { doctor }

package/lib/git.js

@@ -0,0 +1,70 @@
+const { execSync } = require('child_process')
+
+function git (args, opts = {}) {
+  const cwd = opts.cwd || process.cwd()
+  return execSync(`git ${args}`, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe']
+  }).trimEnd()
+}
+
+function gitRoot (cwd) {
+  try {
+    return git('rev-parse --show-toplevel', { cwd })
+  } catch {
+    return null
+  }
+}
+
+function hasChanges (cwd) {
+  try {
+    git('diff --quiet HEAD', { cwd })
+  } catch {
+    return true
+  }
+  try {
+    git('diff --cached --quiet', { cwd })
+  } catch {
+    return true
+  }
+  // Also check for untracked files
+  const untracked = git('ls-files --others --exclude-standard', { cwd })
+  return untracked.length > 0
+}
+
+function addAndCommit (cwd, headline, body) {
+  git('add -A', { cwd })
+  git(`commit -m "${esc(headline)}" -m "${esc(body)}" --no-verify`, { cwd })
+  return git('rev-parse HEAD', { cwd })
+}
+
+function hasCommits (cwd) {
+  try {
+    git('rev-parse HEAD', { cwd })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function currentBranch (cwd) {
+  try {
+    return git('branch --show-current', { cwd }) || 'HEAD'
+  } catch {
+    return 'HEAD'
+  }
+}
+
+function esc (s) {
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`')
+}
+
+module.exports = {
+  git,
+  gitRoot,
+  hasChanges,
+  addAndCommit,
+  hasCommits,
+  currentBranch
+}

package/lib/init.js

@@ -0,0 +1,41 @@
+const fs = require('fs')
+const path = require('path')
+const { gitRoot } = require('./git')
+const { writeJson, ensureDir } = require('./io')
+
+function configPath (root) {
+  return path.join(root, '.claude', 'turbocommit.json')
+}
+
+function init (cwd) {
+  const root = gitRoot(cwd)
+  if (!root) {
+    return { ok: false, error: 'Not a git repository' }
+  }
+
+  const p = configPath(root)
+  if (fs.existsSync(p)) {
+    return { ok: true, alreadyExists: true, path: p }
+  }
+
+  ensureDir(path.dirname(p))
+  writeJson(p, { enabled: true })
+  return { ok: true, alreadyExists: false, path: p }
+}
+
+function deinit (cwd) {
+  const root = gitRoot(cwd)
+  if (!root) {
+    return { ok: false, error: 'Not a git repository' }
+  }
+
+  const p = configPath(root)
+  if (!fs.existsSync(p)) {
+    return { ok: true, existed: false, path: p }
+  }
+
+  fs.unlinkSync(p)
+  return { ok: true, existed: true, path: p }
+}
+
+module.exports = { init, deinit, configPath }