KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #codex #typescript #ai-agents #ai-agent #cli #claude-code #open-source #deepseek-harness #dsh-plugin #python #mcp

turbocommit

★ 56 Open GitHub ↗

Save state for Claude Code. Use git commits to preserve your prompts and protect your progress!

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Certified Shovelware](https://justin.searls.co/img/shovelware.svg)](https://justin.searls.co/shovelware/)

# turbocommit

turbocommit creates a git commit containing everything Claude Code or Codex
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 agent
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 hooks with the harnesses you use:

- Claude Code: **PreToolUse**, **SessionStart**, **SessionEnd**, and **Stop**.
- Codex: **PreToolUse**, **SessionStart**, **PreCompact**, 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.
- **PreCompact** on Codex buffers visible transcript context before compaction.
- **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.

### Changes across multiple repositories

A session that starts in an enabled repository can commit changes in other
enabled local checkouts during the same turn. Turbocommit discovers each
checkout from explicit file paths supplied to Claude Code tools, Codex
`apply_patch`, and path-bearing MCP tools. Shell commands alone do not discover
additional repositories.

Each touched checkout:

- Reads its own merged global and project configuration.
- Keeps the normal `git add -A` behavior.
- Gets an independent commit with the full turn transcript.
- Gives the configured title agent repository-specific bounded diff context.

Turbocommit attempts every commit before pushing every successful commit whose
repository has `push: true`. Failures are retained and retried on a later Stop,
along with every transcript accumulated before the commit succeeds.

Separate worktrees are committed independently. Enabled submodules are
committed and pushed before enabled parent repositories. When one turn creates
commits in multiple repositories, each commit includes a shared
`Turbocommit-Session` trailer.

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
```

Or install from npm:

```bash
npm install -g @searls/turbocommit
turbocommit install
```

With no flags, `turbocommit install` installs into existing harness config
directories only: `~/.claude` and/or `~/.codex`. To force one harness and create
its config directory if needed:

```bash
turbocommit install --harness claude
turbocommit install --harness codex
```

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 for each installed harness.
The hooks are fire-and-forget: they always exit 0 and never block the agent.

If you rearrange your hooks manually, the turbocommit hooks can go anywhere.
Order doesn't matter since they never block.

Codex users should restart Codex and run `/hooks` after install to review and
trust the hook commands.

## Commands

| Command | Description |
|---------|-------------|
| `turbocommit install` | Add hooks to existing Claude and/or Codex config dirs |
| `turbocommit install --harness claude` | Add hooks to `~/.claude/settings.json` |
| `turbocommit install --harness codex` | Add hooks to `~/.codex/hooks.json` |
| `turbocommit uninstall` | Remove them |
| `turbocommit init` | Create `.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 agent session. This means you can run
multiple sessions in parallel, across different tabs and 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 `.turbocommit.json` with `{"enabled": true}`.
The legacy project path `.claude/turbocommit.json` is still read when the
neutral file is absent.

Global config follows the XDG Unix config standard:

```text
$XDG_CONFIG_HOME/turbocommit/config.json
```

When `XDG_CONFIG_HOME` is unset, turbocommit reads:

```text
~/.config/turbocommit/config.json
```

The legacy global path `~/.claude/turbocommit.json` is still read when the XDG
file is absent. Project config is deep-merged on top of global config.

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 or Codex CLI

turbocommit

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README