> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkpoints

> How Entire captures your AI coding sessions

Entire captures AI coding sessions as you work, and creates permanent checkpoints when you make Git commits.

## How It Works

1. Start an AI coding session with a supported agent, such as Claude Code, Codex, Gemini CLI, OpenCode, or Pi
2. When you or the agent run `git commit`, the session data is attached to your commit
3. The checkpoint ID is added as a commit trailer. For example:

```
feat: Add user authentication

This commit adds OAuth2 login flow with Google and GitHub providers.

Entire-Checkpoint: a3b2c4d5e6f7
```

4. The session log and other metadata are stored in a checkpoint in the `entire/checkpoints/v1` branch
5. On your next `git push`, the `entire/checkpoints/v1` branch will be automatically pushed too

## Manual Attach

If Entire did not capture a session automatically, you can attach it later:

```bash theme={null}
entire session attach <session-id> -a <agent>
```

This is useful when:

* Hooks were not installed when the session started
* Hooks failed to fire
* The session was research-only and did not produce file changes
* The session started in another folder but turned out to be relevant somewhere else

`entire session attach` reads the transcript, writes the session into `entire/checkpoints/v1`, and links it to your latest commit.

* If the last commit already has an `Entire-Checkpoint` trailer, the session is added to that checkpoint
* If the last commit has no checkpoint yet, Entire creates one and asks whether to amend the commit
* In non-interactive flows, Entire prints the `Entire-Checkpoint: ...` trailer so you can add it manually

Example:

```bash theme={null}
entire session attach 019d6c43-1537-7343-9691-1f8cee04fe59 -a codex -f
```

## Benefits

* **Clean Git history** - No extra commits from Entire
* **Safe everywhere** - Can be used on `main` or any branch
* **Rewind support** - You can rewind file changes and session state
* **Resume support** - You or a coworker can resume a branch / commit session

## Best Practices

* Make commits at logical stopping points or ask your agent to make granular commits
* Use meaningful commit messages—they become checkpoint labels
* Commit before major changes if you want a rewind point

### Auto-Summarize

When enabled, Entire uses AI to automatically generate summaries of your sessions when you commit. These summaries are stored with your checkpoint metadata.

```json theme={null}
{
  "strategy_options": {
    "summarize": {
      "enabled": true
    }
  }
}
```

<Note>
  Auto-summarize requires Claude CLI to be installed and authenticated. The
  summary generation happens in the background and won't block your commit.
</Note>

Summaries include:

* A brief description of what was accomplished
* Key decisions made during the session
* Files that were modified

## Checkpoint Remote

By default, Entire pushes the `entire/checkpoints/v1` branch to the same remote as your code. If you want to push checkpoint data to a separate repository, you can configure a checkpoint remote.

This is useful for keeping checkpoint data off your main repository on GitHub, centralizing checkpoints across multiple repositories, or separating audit trails from production code.

### Setup

Configure the checkpoint remote via the CLI:

```bash theme={null}
entire enable --checkpoint-remote github:myorg/checkpoints-private
```

Or add it directly to your settings:

```json theme={null}
{
  "strategy_options": {
    "checkpoint_remote": {
      "provider": "github",
      "repo": "myorg/checkpoints-private"
    }
  }
}
```

<Note>
  Currently, only `github` is supported as a provider. When using a
  checkpoint remote, commit and push
  [`.entire/settings.json`](/cli/configuration#project-settings) to your
  default branch so entire.io can locate your checkpoint data.
</Note>

### How It Works

When you push code, Entire automatically:

1. **Derives the checkpoint URL** — Uses the same protocol (SSH or HTTPS) as your push remote
2. **Pushes checkpoints separately** — The `entire/checkpoints/v1` branch goes to your checkpoint remote

### Fork Detection

Entire includes built-in fork detection to prevent contributors from accidentally pushing to an organization's private checkpoint repository.

If the push remote owner differs from the checkpoint remote owner, the checkpoint push is **skipped**:

* You're pushing to `alice/main-repo` (your fork)
* Checkpoint remote is configured as `org/checkpoints-private`
* Since `alice` ≠ `org`, checkpoints fall back to your fork's origin

This ensures that fork contributors don't need write access to the upstream checkpoint repository.

### Error Handling

If the checkpoint remote is unreachable, Entire warns you but continues:

```
[entire] Pushing entire/checkpoints/v1 to checkpoint remote...
[entire] Warning: couldn't sync entire/checkpoints/v1: ...
[entire] A checkpoint remote is configured in Entire settings but could not be reached.
[entire] Checkpoints are saved locally but not synced. Ensure you have access to the checkpoint remote.
```

Your main Git push still succeeds. Checkpoint failures are non-blocking.

## Troubleshooting

### GitLab squash merges

By default, GitLab squash merges do not preserve commit trailers from the original commits. This removes the `Entire-Checkpoint` trailer that Entire uses to link commits to Checkpoint metadata.

To preserve it, configure the Squash commit message template under Settings > Repository > Merge requests.

Use a template that includes the squashed commit content, for example:

```text theme={null}
%{title} (%{reference})

%{all_commits}
```