npm package: @searls/turbocommit
Description: Auto-commit after every Claude Code turn
Latest version: 0.12.0

[![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,

  // Auto-push after each turbocommit.
  // Only pushes when fast-forward is possible (never forces).
  //   true  → push after each commit
  //   false → don't push (default)
  "push": false,

  "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