> ## 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.

# Configuration

> Configure Entire settings for your project and preferences

Entire uses a layered configuration system that allows project-wide settings to be shared via Git while supporting personal overrides.

Entire looks for configuration in the following locations (in order of precedence):

1. **Local settings** (highest priority): `.entire/settings.local.json`
2. **Project settings**: `.entire/settings.json`
3. **Defaults** (lowest priority)

## Project Settings

Project settings are stored in `.entire/settings.json` and should be committed to your repository. These settings apply to everyone working on the project.

```json theme={null}
{
  "enabled": true,
  "log_level": "info",
  "telemetry": true,
  "strategy_options": {}
}
```

### Settings Reference

| Setting                       | Type    | Default  | Description                                                                                                                                                                                                                                                                                                |
| ----------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                     | boolean | `true`   | Whether Entire is active in this repository                                                                                                                                                                                                                                                                |
| `external_agents`             | boolean | `false`  | Enable discovery of [external agent plugins](/agents/external-agent-plugins) from `$PATH`                                                                                                                                                                                                                  |
| `sign_checkpoint_commits`     | boolean | `true`   | Sign checkpoint commits using your existing Git signing key (GPG or SSH). Best-effort — falls back to unsigned with a log entry if the signer is unavailable. See [Security & Privacy → Checkpoint commit signing](/security#checkpoint-commit-signing).                                                   |
| `redaction.pii.enabled`       | boolean | `false`  | Enable optional PII redaction (email, phone, address, plus team-defined custom patterns) on top of always-on secret redaction. See [Security & Privacy → PII redaction](/security#pii-redaction-optional).                                                                                                 |
| `redaction.custom_redactions` | object  | `{}`     | Add label → Go/RE2 regex rules that replace matches with `REDACTED`. Use project settings for team rules or local settings for personal rules. See [Security & Privacy → User-defined redaction](/security#user-defined-redaction).                                                                        |
| `log_level`                   | string  | `"info"` | Log verbosity: `debug`, `info`, `warn`, `error`. Can be overridden by `ENTIRE_LOG_LEVEL` env var. Set to `debug` to enable [performance traces](/cli/commands#doctor-trace).                                                                                                                               |
| `telemetry`                   | boolean | `null`   | Send anonymous usage analytics to PostHog (command name, agent, OS, flag names — never values). `null` = not asked yet (will prompt), `true` = opted in, `false` = opted out. See [Security & Privacy → Telemetry and analytics](/security#telemetry-and-analytics) for what's captured and opt-out paths. |
| `strategy_options`            | object  | `{}`     | Additional configuration options (see [Strategy Options](#strategy-options) below)                                                                                                                                                                                                                         |

### Redaction Settings

User-defined redaction rules can live inline in settings or as reusable rule packs. Use `.entire/settings.json` for team-wide rules and `.entire/settings.local.json` for personal-only rules.

```json theme={null}
{
  "redaction": {
    "custom_redactions": {
      "acme_token": "ACME_TOKEN_[A-Za-z0-9]{20,}",
      "internal_id": "INTERNAL_[a-z]{6}_[0-9]{4}"
    }
  }
}
```

For larger sets, put YAML or JSON rule packs in `.entire/redactors/`. Keep personal packs in `.entire/redactors/local/`.

### Strategy Options

The `strategy_options` object contains settings that control how Entire captures and stores session data.

| Setting             | Type    | Default | Description                                                                                           |
| ------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `push_sessions`     | boolean | `true`  | Automatically push `entire/checkpoints/v1` branch on `git push`                                       |
| `checkpoint_remote` | object  | `null`  | Push checkpoint branches to a separate repository (see [Checkpoint Remote](#checkpoint-remote) below) |
| `summarize.enabled` | boolean | `false` | Auto-generate AI summaries at commit time                                                             |

Example:

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

### Checkpoint Remote

Push checkpoint data to a separate repository instead of your main code repository. See [Checkpoint Remote](/cli/checkpoints#checkpoint-remote) for setup and details.

## Local Settings

Local settings are stored in `.entire/settings.local.json` and are automatically added to `.gitignore`. Use these for personal preferences that shouldn't be shared.

```json theme={null}
{
  "log_level": "debug",
  "telemetry": false
}
```

<Tip>
  Local settings are merged with project settings. You only need to specify the
  settings you want to override.
</Tip>

## Project and local files

The `.entire/` directory can contain both project setup and local files. Use the table below to decide which files belong in Git and which should stay on your machine.

| Path                          | Recommendation                            | Use for                                                                                              |
| ----------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `.entire/settings.json`       | Commit when Entire is part of the project | Shared settings, redaction rules, checkpoint remote, and behavior everyone on the project should use |
| `.entire/.gitignore`          | Commit                                    | Keeps local Entire files out of normal commits                                                       |
| `.entire/settings.local.json` | Keep local                                | Personal overrides, debug logging, private provider choices, or machine-specific settings            |
| `.entire/redactors/`          | Commit shared packs                       | Reusable user-defined redaction rule packs for the project                                           |
| `.entire/redactors/local/`    | Keep local                                | Personal rule packs for private codenames, customer references, or local-only patterns               |
| `.entire/logs/`               | Keep local                                | Diagnostic logs from your machine                                                                    |
| `.entire/tmp/`                | Keep local                                | Temporary runtime data                                                                               |
| `.entire/metadata/`           | Keep local                                | Local metadata generated while Entire runs                                                           |
| `.entire/current_session`     | Keep local                                | Pointer to your current local session                                                                |

If you're only trying Entire for yourself, keep `.entire/settings.json` local until the project decides to adopt it.

<Note>
  Checkpoint transcripts are stored separately on the `entire/checkpoints/v1` branch. If your repository is public, pushed checkpoint history is public too. See [Security & Privacy](/security).
</Note>

## Global Settings

Global settings apply to all repositories and are stored in `~/.config/entire/settings.json`.

```json theme={null}
{
  "telemetry": true
}
```

### Global Settings Reference

| Setting     | Type    | Default | Description                                    |
| ----------- | ------- | ------- | ---------------------------------------------- |
| `telemetry` | boolean | `false` | Default telemetry setting for new repositories |

## Environment Variables

Certain settings can be overridden via environment variables:

| Variable                  | Description                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `ENTIRE_LOG_LEVEL`        | Set log verbosity (`debug`, `info`, `warn`, `error`). Takes precedence over the `log_level` setting. |
| `ENTIRE_TELEMETRY_OPTOUT` | Set to any non-empty value to opt out of telemetry regardless of the `telemetry` setting.            |
| `ENTIRE_NO_AUTO_UPDATE`   | Set to any non-empty value to disable the interactive auto-update prompt.                            |

```bash theme={null}
# Enable debug logging for a session
ENTIRE_LOG_LEVEL=debug claude
```

## GUI Git Clients

By default, Entire's Git hooks use the `entire` command without a full path, relying on your shell's `PATH` to find the binary. This works well for terminal commits, but GUI Git clients (Xcode, Tower, GitKraken, Sourcetree, etc.) often don't source your shell profile, so they can't find `entire`.

To fix this, use the `--absolute-git-hook-path` flag:

```bash theme={null}
# During initial setup
entire enable --absolute-git-hook-path

# Or if Entire is already configured
entire configure --absolute-git-hook-path
```

This embeds the full path to the `entire` binary directly in the Git hooks:

```sh theme={null}
# Without --absolute-git-hook-path (default)
entire hooks git post-commit

# With --absolute-git-hook-path
'/Users/you/go/bin/entire' hooks git post-commit
```

### Limitations

* **Not portable** - If you move the `entire` binary, you'll need to re-run `entire enable --absolute-git-hook-path` or `entire configure --absolute-git-hook-path`

### Settings Reference

The setting is stored in your settings file:

```json theme={null}
{
  "absolute_git_hook_path": true
}
```

## Agent Hook Configuration

Each agent stores its hook configuration in its own directory. When you run `entire enable`, hooks are installed in the appropriate location for each selected agent:

| Agent         | Hook Location                    | Format               |
| ------------- | -------------------------------- | -------------------- |
| Claude Code   | `.claude/settings.json`          | JSON hooks config    |
| Codex         | `.codex/hooks.json`              | JSON hooks config    |
| Copilot CLI   | `.github/hooks/entire.json`      | JSON hooks config    |
| Cursor        | `.cursor/hooks.json`             | JSON hooks config    |
| Gemini CLI    | `.gemini/settings.json`          | JSON hooks config    |
| OpenCode      | `.opencode/plugins/entire.ts`    | TypeScript plugin    |
| Factory Droid | `.factory/settings.json`         | JSON hooks config    |
| Pi            | `.pi/extensions/entire/index.ts` | TypeScript extension |

You can enable multiple agents at the same time — each agent's hooks are independent.

## Initializing Configuration

When you run `entire enable`, a `.entire` directory is created with default settings:

```
.entire/
├── settings.json        # Project settings (committed)
├── settings.local.json  # Local overrides (gitignored)
└── .gitignore          # Ensures local settings aren't committed
```

## Modifying Settings

### Via CLI

```bash theme={null}
# Enable telemetry
entire enable --telemetry
```

### Manually

Edit the JSON files directly:

```bash theme={null}
# Edit project settings
vim .entire/settings.json

# Edit local settings
vim .entire/settings.local.json
```

## Configuration Precedence Example

Given these configuration files:

**Global** (`~/.config/entire/settings.json`):

```json theme={null}
{
  "telemetry": true
}
```

**Project** (`.entire/settings.json`):

```json theme={null}
{
  "log_level": "info"
}
```

**Local** (`.entire/settings.local.json`):

```json theme={null}
{
  "log_level": "debug"
}
```

The effective configuration would be:

```json theme={null}
{
  "log_level": "debug",         // from local (overrides project)
  "telemetry": true             // from global
}
```

## Viewing Current Configuration

To see the effective configuration:

```bash theme={null}
entire status --detailed
```

This shows all settings and their sources.