# Architecture
Source: https://docs.entire.io/agents/agent-integration-protocol/architecture

How the Entire CLI discovers and communicates with agent integrations

Entire discovers agent integrations through executable naming and `$PATH` lookup:

1. You create an executable named `entire-agent-<name>`
2. Place it anywhere on your `$PATH`
3. The CLI discovers it at startup and registers it as a new agent

The integration communicates with the CLI through **subcommands** that read and write JSON over stdin and stdout. Each invocation is stateless.

Every subcommand invocation receives these environment variables:

| Variable                  | Description                              |
| ------------------------- | ---------------------------------------- |
| `ENTIRE_REPO_ROOT`        | Absolute path to the git repository root |
| `ENTIRE_PROTOCOL_VERSION` | Protocol version (currently `1`)         |

Entire runs every subcommand from the repository root.

The integration follows these conventions:

* **Output:** JSON on stdout (unless noted otherwise)
* **Errors:** Nonzero exit code and message on stderr
* **Stateless:** Each invocation is independent, no persistent connection


# Build an Agent Integration
Source: https://docs.entire.io/agents/agent-integration-protocol/build-an-agent-integration

Use the external-agents agent skill to add support for another coding agent

You can build an agent integration when you want Entire to support a coding agent that is not natively supported in the Entire CLI yet. The [external-agents repository](https://github.com/entireio/external-agents) includes an agent skill that does most of the work. The skill researches the target agent. Next, it creates the starter code for the binary and writes tests. Then it writes the code that follows the protocol. You can write an integration in any language. This guide uses the Go version in that repository and its skill.

For the protocol itself, see [Architecture](/agents/agent-integration-protocol/architecture), [Commands](/agents/agent-integration-protocol/commands), [Lifecycle](/agents/agent-integration-protocol/lifecycle), and [Data Model](/agents/agent-integration-protocol/data-model).

<Note>
  **Building a private or internal integration?** This guide is the upstream contribution path, which ends in a pull request to `external-agents`. For an integration you won't contribute back, skip the issue and PR steps and follow the protocol reference above.
</Note>

## Before You Start

Open an issue in [`entireio/external-agents`](https://github.com/entireio/external-agents) before writing code. Adding support for a new agent creates an ongoing support commitment, so align with maintainers first.

You need:

* The target agent CLI installed and authenticated
* [The Entire CLI installed](/installation)
* [Go](https://go.dev/doc/install) and [mise](https://mise.jdx.dev/getting-started.html)
* A target agent with lifecycle hooks or another reliable event mechanism
* Readable session or transcript data
* A stable session ID

## Clone the Repo

```bash theme={null}
git clone https://github.com/entireio/external-agents.git
cd external-agents
mise trust
mise install
```

New integrations live under `agents/entire-agent-<slug>`. Each integration is a standalone binary named `entire-agent-<slug>`.

## Run the Agent Skill

The repo includes an agent skill named `entire-external-agent`, and supported tools discover it automatically with no additional configuration. See the [repo instructions](https://github.com/entireio/external-agents?tab=readme-ov-file#getting-started--zero-setup) for the current supported tools.

Run the skill:

```text theme={null}
/entire-external-agent
```

When prompted, provide the target agent name and slug.

## What the Skill Does

The skill runs three phases:

| Phase         | What happens                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------------ |
| **Research**  | Finds the target agent's hooks, session IDs, transcript storage, CLI commands, and capabilities. |
| **Scaffold**  | Creates the integration structure, protocol stubs, and lifecycle test wiring.                    |
| **Implement** | Uses compliance and lifecycle failures to implement the integration and add tests.               |

You can also run a single phase when you need to restart or inspect part of the process.

```text theme={null}
/entire-external-agent research
/entire-external-agent write-tests
/entire-external-agent implement
```

## Reference Examples

The [external-agents repository](https://github.com/entireio/external-agents) contains working integrations you can inspect while building your own:

| Integration                                                                                             | Target agent | Notes                                                                                             |
| ------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
| [`entire-agent-amp`](https://github.com/entireio/external-agents/tree/main/agents/entire-agent-amp)     | Amp          | Agent integration with transcript preparation, token calculation, and compact transcript support. |
| [`entire-agent-goose`](https://github.com/entireio/external-agents/tree/main/agents/entire-agent-goose) | Goose        | Agent integration that exports Goose sessions from SQLite-backed storage.                         |
| [`entire-agent-kiro`](https://github.com/entireio/external-agents/tree/main/agents/entire-agent-kiro)   | Kiro         | Lifecycle hooks and transcript analysis for Kiro sessions.                                        |

For a minimal reference implementation outside the main examples repo, see [`roger-roger`](https://github.com/entireio/roger-roger).

## Review the Output

When the skill finishes, review:

* `agents/entire-agent-<slug>/AGENT.md`
* `agents/entire-agent-<slug>/README.md`
* The declared capabilities
* Protocol compliance results
* Lifecycle test results
* Any remaining gaps or local dependencies

Treat captured hook payloads and transcript fixtures as ground truth. Documentation can drift.

## Verify Locally

Build the binary, put it on your `PATH`, and enable it in a test repository:

```bash theme={null}
cd agents/entire-agent-<slug>
mise run build
export PATH="$PWD:$PATH"

cd /path/to/test-repo
entire enable --agent SLUG
```

Run the target agent and make a small file change. Then check that Entire captured the session:

```bash theme={null}
entire status
entire checkpoint list
entire checkpoint explain CHECKPOINT_ID --short
```

Look for a checkpoint with the expected session, transcript, and modified files.

## Open the PR

Reference the approved issue and include:

* Agent name and binary name
* Declared capabilities
* Protocol compliance status
* Lifecycle test status
* Unit test coverage
* Any local dependencies you could not test
* Known limitations

CI will build the agent and run the shared checks.


# Commands
Source: https://docs.entire.io/agents/agent-integration-protocol/commands

Required commands and optional capabilities for agent integrations

Every agent integration must implement these subcommands.

## Required Commands

### `info`

Returns metadata and declares which optional capabilities your integration supports.

```bash theme={null}
entire-agent-myagent info
```

```json theme={null}
{
  "protocol_version": 1,
  "name": "myagent",
  "type": "MyAgent",
  "description": "MyAgent - AI-powered code editor",
  "is_preview": true,
  "protected_dirs": [".myagent"],
  "hook_names": ["session-start", "session-end", "stop"],
  "capabilities": {
    "hooks": true,
    "transcript_analyzer": true,
    "transcript_preparer": false,
    "token_calculator": false,
    "text_generator": false,
    "hook_response_writer": false,
    "subagent_aware_extractor": false
  }
}
```

| Field              | Description                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| `protocol_version` | Must match the CLI's expected version (currently `1`)                       |
| `name`             | Registry name (must match the `<name>` in the binary name)                  |
| `type`             | Display name / type identifier                                              |
| `description`      | Description for readers                                                     |
| `is_preview`       | Whether the agent is in preview                                             |
| `protected_dirs`   | Directories the CLI should not modify (excluded from checkpoints and diffs) |
| `hook_names`       | Agent lifecycle hooks this integration handles                              |
| `capabilities`     | Object declaring which optional capabilities are supported                  |

### `detect`

Returns whether the agent is available in the current environment. Return `{"present": false}` if the agent's dependencies are not met. The CLI will skip enabling the agent.

```bash theme={null}
entire-agent-myagent detect
```

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

### `get-session-id`

Extracts a session ID from a hook input event.

**stdin:** [HookInput](/agents/agent-integration-protocol/data-model#hookinput) JSON

```json theme={null}
{"session_id": "abc123"}
```

### `get-session-dir --repo-path <path>`

Returns where agent sessions are stored.

```json theme={null}
{"session_dir": "/path/to/sessions"}
```

### `resolve-session-file --session-dir <dir> --session-id <id>`

Resolves the session file path from a session directory and ID.

```json theme={null}
{"session_file": "/path/to/session/file.jsonl"}
```

### `read-session`

Reads session data from a hook input event.

**stdin:** [HookInput](/agents/agent-integration-protocol/data-model#hookinput) JSON

**stdout:** [AgentSession](/agents/agent-integration-protocol/data-model#agentsession) JSON

### `write-session`

Persists session data to disk. The integration chooses the storage location and format.

**stdin:** [AgentSession](/agents/agent-integration-protocol/data-model#agentsession) JSON

Exit `0` on success.

### `read-transcript --session-ref <path>`

Reads a transcript file and returns its raw bytes on stdout.

### `chunk-transcript --max-size <n>`

Splits a transcript (raw bytes on stdin) into chunks.

```json theme={null}
{"chunks": ["<base64-encoded-chunk>", "..."]}
```

### `reassemble-transcript`

Reassembles chunks into a transcript when `entire session resume` restores stored session data.

**stdin:**

```json theme={null}
{"chunks": ["<base64-encoded-chunk>", "..."]}
```

**stdout:** Raw transcript bytes.

### `format-resume-command --session-id <id>`

Returns the command a user would run to resume a session.

```json theme={null}
{"command": "myagent --resume abc123"}
```

## Optional Capabilities

Set capabilities to `true` in your `info` response to enable these. The CLI will never call subcommands for capabilities you don't declare.

### `hooks`

Manage agent lifecycle hooks for Entire integration.

| Subcommand                              | Description                                                                                                                                                    |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parse-hook --hook <name>`              | Parse a raw hook payload (stdin) into an [Event](/agents/agent-integration-protocol/data-model#event). Return `null` if not relevant.                          |
| `install-hooks [--local-dev] [--force]` | Install hooks. `--local-dev` installs hooks pointing to a local development build. `--force` overwrites existing hook files. Returns `{"hooks_installed": 3}`. |
| `uninstall-hooks`                       | Remove installed hooks. Exit `0` on success.                                                                                                                   |
| `are-hooks-installed`                   | Check hook status. Returns `{"installed": true}`.                                                                                                              |

### `transcript_analyzer`

Extract data from agent transcripts.

| Subcommand                                          | Description                                            |
| --------------------------------------------------- | ------------------------------------------------------ |
| `get-transcript-position --path <path>`             | Returns `{"position": 12345}` (byte offset).           |
| `extract-modified-files --path <path> --offset <n>` | Returns `{"files": [...], "current_position": 12345}`. |
| `extract-prompts --session-ref <path> --offset <n>` | Returns `{"prompts": ["prompt text", ...]}`.           |
| `extract-summary --session-ref <path>`              | Returns `{"summary": "...", "has_summary": true}`.     |

### `transcript_preparer`

| Subcommand                                | Description                                     |
| ----------------------------------------- | ----------------------------------------------- |
| `prepare-transcript --session-ref <path>` | Prepare a transcript file. Exit `0` on success. |

### `token_calculator`

| Subcommand                      | Description                                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `calculate-tokens --offset <n>` | Calculate token usage from transcript bytes (stdin). `--offset` is the byte offset into the transcript to start counting from. |

Output:

```json theme={null}
{
  "input_tokens": 1500,
  "output_tokens": 500,
  "cache_creation_tokens": 0,
  "cache_read_tokens": 200,
  "api_call_count": 3
}
```

You must return `input_tokens` and `output_tokens`. The CLI uses `0` for fields you omit.

### `text_generator`

| Subcommand                      | Description                                                     |
| ------------------------------- | --------------------------------------------------------------- |
| `generate-text --model <model>` | Generate text from a prompt (stdin). Returns `{"text": "..."}`. |

### `hook_response_writer`

| Subcommand                            | Description                                                 |
| ------------------------------------- | ----------------------------------------------------------- |
| `write-hook-response --message <msg>` | Write a message in the agent's native hook format (stdout). |

### `subagent_aware_extractor`

For agents that spawn subagents.

| Subcommand                                                      | Description                                                                                                                                                           |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `extract-all-modified-files --offset <n> --subagents-dir <dir>` | Extract modified files from main + subagent transcripts (stdin: main transcript). Returns `{"files": [...]}`.                                                         |
| `calculate-total-tokens --offset <n> --subagents-dir <dir>`     | Calculate total tokens across main + subagent transcripts (stdin: main transcript). Same format as `calculate-tokens`, with optional `subagent_tokens` nested object. |


# Data Model
Source: https://docs.entire.io/agents/agent-integration-protocol/data-model

Data types exchanged between the Entire CLI and agent integrations

## HookInput

Entire passes `HookInput` via stdin to `get-session-id` and `read-session`.

```json theme={null}
{
  "hook_type": "stop",
  "session_id": "abc123",
  "session_ref": "/path/to/transcript.jsonl",
  "timestamp": "2026-01-13T12:00:00Z",
  "user_prompt": "Fix the login bug",
  "tool_name": "Write",
  "tool_use_id": "toolu_abc123",
  "tool_input": {"path": "/src/main.go"},
  "raw_data": {}
}
```

| Field         | Type   | Required | Description                                                                                   |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `hook_type`   | string | Yes      | `session_start`, `session_end`, `user_prompt_submit`, `stop`, `pre_tool_use`, `post_tool_use` |
| `session_id`  | string | Yes      | Agent session identifier                                                                      |
| `session_ref` | string | Yes      | Session reference specific to the agent, typically a file path                                |
| `timestamp`   | string | Yes      | RFC 3339 timestamp                                                                            |
| `user_prompt` | string | No       | User's prompt text                                                                            |
| `tool_name`   | string | No       | Tool name (from tool use hooks)                                                               |
| `tool_use_id` | string | No       | Tool invocation ID                                                                            |
| `tool_input`  | object | No       | Raw tool input JSON                                                                           |
| `raw_data`    | object | No       | Extension data specific to the agent                                                          |

## AgentSession

Entire passes `AgentSession` to `write-session` and receives it from `read-session`.

```json theme={null}
{
  "session_id": "abc123",
  "agent_name": "myagent",
  "repo_path": "/path/to/repo",
  "session_ref": "/path/to/transcript.jsonl",
  "start_time": "2026-01-13T12:00:00Z",
  "native_data": null,
  "modified_files": ["src/main.go"],
  "new_files": [],
  "deleted_files": []
}
```

| Field            | Type       | Description                                     |
| ---------------- | ---------- | ----------------------------------------------- |
| `session_id`     | string     | Agent session identifier                        |
| `agent_name`     | string     | Agent registry name                             |
| `repo_path`      | string     | Absolute path to the repository                 |
| `session_ref`    | string     | Path to session in agent's storage              |
| `start_time`     | string     | RFC 3339 timestamp                              |
| `native_data`    | bytes/null | Opaque session content in agent's native format |
| `modified_files` | string\[]  | Files modified during the session               |
| `new_files`      | string\[]  | Files created during the session                |
| `deleted_files`  | string\[]  | Files deleted during the session                |

## Event

The `parse-hook` subcommand returns this normalized lifecycle event.

```json theme={null}
{
  "type": 3,
  "session_id": "abc123",
  "session_ref": "/path/to/transcript.jsonl",
  "prompt": "Fix the login bug",
  "model": "claude-sonnet-4-20250514",
  "timestamp": "2026-01-13T12:00:00Z"
}
```

**Event types:**

| Value | Name          | Description                                                                 |
| ----- | ------------- | --------------------------------------------------------------------------- |
| 1     | SessionStart  | Agent began a session                                                       |
| 2     | TurnStart     | User submitted a prompt                                                     |
| 3     | TurnEnd       | Agent finished responding                                                   |
| 4     | Compaction    | Agent compressed its context window, which triggers a save and offset reset |
| 5     | SessionEnd    | Session ended                                                               |
| 6     | SubagentStart | Agent spawned a subagent                                                    |
| 7     | SubagentEnd   | Subagent completed its task                                                 |

**Optional event fields:** `previous_session_id`, `session_ref`, `prompt`, `model`, `timestamp`, `tool_use_id`, `subagent_id`, `tool_input`, `subagent_type`, `task_description`, `response_message`, `metadata`.

You must provide `type` and `session_id`.


# Lifecycle
Source: https://docs.entire.io/agents/agent-integration-protocol/lifecycle

When the Entire CLI calls each agent integration command

The CLI calls integration subcommands in five phases.

## Phase 1: Discovery (CLI Startup)

Every time the CLI starts, it scans `$PATH` for binaries matching `entire-agent-<name>`.

1. **`info`**: The CLI calls this command once per discovered binary. It reads your metadata, validates the protocol version, and registers the agent. If this fails, the CLI skips the agent.

## Phase 2: Enable (`entire enable`)

When a user enables your agent for a repository:

1. **`detect`**: The CLI calls this command to check whether your agent is available in the current environment.
2. **`install-hooks [--local-dev] [--force]`**: The CLI calls this command to install your hooks into the agent, such as by writing hook configuration files. It calls this command only when you declare the `hooks` capability.

## Phase 3: Agent Session (Hooks Firing)

After you enable the agent, its hooks fire during normal usage and the CLI processes them. This phase requires the `hooks` capability. Agents that don't declare it won't participate in the hook lifecycle.

Every hook invocation follows this flow:

```
Hook fires → parse-hook normalizes → CLI dispatches Event by type
```

1. **`parse-hook --hook <name>`**: The CLI calls this command on every hook invocation with the raw payload on stdin. Return a normalized [Event](/agents/agent-integration-protocol/data-model#event), or `null` if the hook has no lifecycle significance and the CLI should take no action.

The CLI then routes the event by type:

### SessionStart (Type 1)

The agent fires this event when it begins a new session.

1. **`get-session-id`**: Extract the session ID from the hook input (stdin).
2. **`get-session-dir --repo-path <path>`**: Return where sessions are stored.
3. **`resolve-session-file --session-dir <dir> --session-id <id>`**: Resolve the session file path.
4. **`read-session`**: Read existing session data (stdin: [HookInput](/agents/agent-integration-protocol/data-model#hookinput)).
5. **`write-session`**: Persist updated session data.
6. **`write-hook-response --message <msg>`**: *(optional, if `hook_response_writer` capability)* Write a startup message in your agent's native format.

### TurnStart (Type 2)

The agent fires this event when the user submits a new prompt.

1. **`extract-modified-files --path <path> --offset <n>`**: *(if `transcript_analyzer` capability)* Extract files changed since last checkpoint.
2. The CLI creates a git checkpoint of the current state.

### TurnEnd (Type 3)

The agent fires this event when it finishes responding.

1. **`prepare-transcript --session-ref <path>`**: *(if `transcript_preparer` capability)* Prepare the transcript.
2. **`read-transcript --session-ref <path>`**: Read the raw transcript bytes.
3. **`chunk-transcript --max-size <n>`**: Split large transcripts into storable chunks.
4. **`get-transcript-position --path <path>`**: *(if `transcript_analyzer` capability)* Get the current byte offset.
5. **`extract-modified-files --path <path> --offset <n>`**: *(if `transcript_analyzer` capability)* Extract newly modified files.
6. **`calculate-tokens --offset <n>`**: *(if `token_calculator` capability)* Calculate token usage.
7. The CLI stores a checkpoint in git history.

### Compaction (Type 4)

The agent fires this event when it compresses its context window. The CLI follows the same flow as **TurnEnd** and saves the checkpoint before resetting the offset.

### SessionEnd (Type 5)

The agent fires this event when the session ends. The CLI creates a final checkpoint and cleans up session state.

### SubagentStart / SubagentEnd (Types 6 and 7)

The agent fires these events when it spawns or completes a subagent. If you declare the `subagent_aware_extractor` capability, the CLI calls:

* **`extract-all-modified-files --offset <n> --subagents-dir <dir>`**
* **`calculate-total-tokens --offset <n> --subagents-dir <dir>`**

## Phase 4: User Commands

Some CLI commands invoke your integration outside the hook flow:

| Command                 | Subcommands called                                                                            |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `entire session resume` | `read-transcript`, `reassemble-transcript`, `extract-modified-files`, `format-resume-command` |
| `entire status`         | `get-transcript-position`                                                                     |

## Phase 5: Disable (`entire disable --uninstall`)

1. **`uninstall-hooks`**: The CLI calls this command to remove your installed hooks when you declare the `hooks` capability.

## Error Handling

* **Timeout:** Each subcommand has a default timeout of 30 seconds.
* **Output limits:** The CLI caps stdout and stderr at 10 MB each. Account for this limit when you implement `read-transcript` for large sessions.
* **No retries:** The CLI does not retry failed subcommand calls. It treats a nonzero exit code with a message on stderr as a failure.
* **Graceful degradation:** If `parse-hook` returns `null`, the CLI takes no action. If the repo has Entire disabled, hooks exit silently.


# Agent Integration Protocol
Source: https://docs.entire.io/agents/agent-integration-protocol/overview

Add support for an AI coding agent that Entire does not ship with

If your agent is not listed in our [native agent integrations](/agents/overview), you can still integrate it with Entire. This can be done with the Agent Integration Protocol by building an `entire-agent-<name>` executable and putting it on your `$PATH`. Entire discovers it there and registers it as an agent.

## Add an Agent Integration

After you put the executable on your `$PATH`, install its hooks in an existing Entire repository:

```bash theme={null}
entire agent add NAME
```

During initial setup, select it with:

```bash theme={null}
entire enable --agent NAME
```

See [`entire agent add`](/cli-reference/agent#agent-add) and [`entire enable --agent`](/cli-reference/enable) for their flags and setup behavior.

<Note>
  Selecting a discovered agent with `entire agent add` or `entire enable --agent` sets `external_agents` to `true`. If you install an integration executable after setup, run `entire agent add NAME` or add `"external_agents": true` to `.entire/settings.json`. The setting key keeps its original name.
</Note>

<Warning>
  Agent integrations receive repository paths and session data, and they run with the same filesystem access as the Entire CLI. Only install integrations you trust.
</Warning>

## Protocol Reference

<CardGroup>
  <Card title="Build an Agent Integration" icon="hammer" href="/agents/agent-integration-protocol/build-an-agent-integration">
    Scaffold an executable and implement the protocol with working examples.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/agents/agent-integration-protocol/architecture">
    See how the CLI discovers an integration and invokes it.
  </Card>

  <Card title="Lifecycle" icon="timeline" href="/agents/agent-integration-protocol/lifecycle">
    Follow the CLI calls through discovery, setup, sessions, and shutdown.
  </Card>

  <Card title="Commands" icon="terminal" href="/agents/agent-integration-protocol/commands">
    Implement each subcommand, input, and output.
  </Card>

  <Card title="Data Model" icon="brackets-curly" href="/agents/agent-integration-protocol/data-model">
    Use the JSON shapes that the protocol exchanges.
  </Card>
</CardGroup>


# Claude Code
Source: https://docs.entire.io/agents/claude-code

Capture Claude Code transcripts, file changes, tool calls, tokens, and subagent sessions with Entire

Claude Code is Entire's default integration and the only built-in integration marked stable. It captures the main session and nested subagent sessions.

Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps.

## Add Claude Code

```bash theme={null}
entire agent add claude-code
claude
```

Entire adds lifecycle hooks to `.claude/settings.json` and preserves unrelated Claude Code settings. The hooks capture session boundaries, prompts, completed turns, and task events. Entire reads the full conversation, file changes, tool calls, and token usage from Claude Code's JSONL transcripts.

## Subagent Capture

Claude Code exposes task lifecycle events and separate subagent transcripts. Entire records each task against the parent session, attributes its files and tokens to that session, and materializes its transcript into the parent's next checkpoint. The checkpoint then carries the subagent's work on its own, without reading back into Claude Code's transcript directory.

Entire records any subagent that changed files. It also keeps read-only subagents, such as reviewers and search agents, when you launch them with `run_in_background`. A background launch defers capture to subagent stop, which is where Entire materializes a transcript even though the subagent wrote nothing. Foreground subagents complete at launch time, so a read-only one there leaves no record.

Among the built-in integrations, Claude Code is the one that reaches read-only subagents.

## Resume and Import

`entire session resume BRANCH` restores the recorded session data when needed and prints a command in this form:

```bash theme={null}
claude -r SESSION_ID
```

Entire can also import existing Claude Code transcripts from the previous 30 days as read-only checkpoints.

See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior.


# Codex
Source: https://docs.entire.io/agents/codex

Capture Codex transcripts, file changes, tokens, and subagent sessions with Entire

The Codex integration uses Codex's project-level hook system and is in preview.

Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps.

## Add Codex

```bash theme={null}
entire agent add codex
codex
```

Entire writes `.codex/hooks.json`. Codex enables hooks by default beginning with version 0.124.0, so Entire does not create `.codex/config.toml` or set `codex_hooks = true`.

The hooks capture session boundaries, prompts, completed turns, file-changing tool calls, and subagent events. Entire reads the full conversation and token usage from Codex rollout files under `~/.codex/` or `CODEX_HOME`.

## Limitations

Ephemeral Codex runs may not provide a transcript path. Entire can process their hook events, but it cannot attach a full transcript without the rollout file.

Entire records the subagents that changed files, materializes their transcripts into the parent's next checkpoint, and attributes their files to the parent session. It skips a subagent that wrote nothing, and it does not yet roll subagent tokens up into the parent session's totals.

## Resume and Import

`entire session resume BRANCH` restores the recorded session data when needed and prints:

```bash theme={null}
codex resume SESSION_ID
```

Entire can import existing Codex transcripts from the previous 30 days as read-only checkpoints.

See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior.


# Copilot CLI
Source: https://docs.entire.io/agents/copilot-cli

Capture Copilot CLI transcripts, file changes, tool calls, and token usage with Entire

The Copilot CLI integration uses GitHub Copilot CLI's project-level hooks and is in preview.

Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps.

## Add Copilot CLI

```bash theme={null}
entire agent add copilot-cli
copilot
```

Entire writes its hook configuration to `.github/hooks/entire.json`. The hooks capture session boundaries, prompts, completed turns, tool activity, errors, and subagent completion. Entire reads the full conversation, file changes, and tool calls from Copilot CLI's JSONL transcript.

## Limitations

Copilot CLI reports aggregate token usage when the session ends. Token totals may remain incomplete during an active session.

Copilot CLI provides a subagent stop hook without a corresponding start hook. Entire records the completed subagent operation and uses the parent session's pre-prompt state instead of a subagent-specific pre-task snapshot.

## Resume and Import

`entire session resume BRANCH` restores the recorded session data when needed and prints:

```bash theme={null}
copilot --resume SESSION_ID
```

Entire can import existing Copilot CLI transcripts from the previous 30 days as read-only checkpoints.

See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior.


# Cursor
Source: https://docs.entire.io/agents/cursor

Capture Cursor IDE and CLI transcripts, file changes, tool calls, and subagent sessions with Entire

The Cursor integration supports Cursor IDE and Cursor CLI through project-level hooks. It is in preview.

Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps.

## Add Cursor

```bash theme={null}
entire agent add cursor
cursor
```

Use `agent` instead of `cursor` to start Cursor CLI.

Entire writes `.cursor/hooks.json`. The hooks capture session boundaries, prompts, completed turns, compaction, and subagent events. Entire reads the conversation and tool calls from Cursor's JSONL transcript. It identifies changed files from `Write` and `StrReplace` calls, hook payloads, and Git status.

## Limitations

Cursor transcripts do not provide token usage. Cursor also does not expose a command that resumes the recorded native session, so `entire session resume` opens the project without restoring the prior Cursor conversation.

Cursor CLI hook payloads may omit the transcript path. Entire resolves the transcript from Cursor's project session directory when this happens.

Entire records the subagents that changed files, materializes their transcripts into the parent's next checkpoint, and attributes their files to the parent session. It skips a subagent that wrote nothing.

## Import

Entire can import existing Cursor transcripts from the previous 30 days as read-only checkpoints.


# Factory
Source: https://docs.entire.io/agents/factory-droid

Capture Factory Droid transcripts, file changes, tool calls, tokens, and subagent sessions with Entire

The Factory integration uses Factory Droid's project-level hooks and is in preview.

Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps.

## Add Factory

```bash theme={null}
entire agent add factoryai-droid
droid
```

Entire adds lifecycle hooks to `.factory/settings.json` and preserves unrelated Factory settings. The hooks capture session boundaries, prompts, completed turns, compaction, and task tool calls. Entire reads the full conversation, file changes, tool calls, and token usage from Factory's JSONL transcripts.

## Subagent Capture

Factory exposes task tool events, and its Workers run as sessions of their own. Entire attributes a Worker's turn to the parent task invocation instead of minting a separate top-level session, rolls its files and tokens onto the parent session, and materializes its transcript into the parent's next checkpoint.

Entire records a Worker that changed files, along with its transcript and its tokens. Capture keys on those file changes, so a read-only Worker leaves no record.

## Resume and Import

`entire session resume BRANCH` restores the recorded session data when needed and prints:

```bash theme={null}
droid --session-id SESSION_ID
```

Entire can import existing Factory transcripts from the previous 30 days as read-only checkpoints.

See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior.


# Gemini CLI
Source: https://docs.entire.io/agents/gemini-cli

Capture Gemini CLI transcripts, file changes, tool calls, and available token usage with Entire

The Gemini CLI integration uses Gemini's project-level hook system and is in preview.

Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps.

## Add Gemini CLI

```bash theme={null}
entire agent add gemini
gemini
```

Entire adds hooks to `.gemini/settings.json` and preserves unrelated Gemini settings. The hooks capture session boundaries, prompts, completed turns, model changes, tool activity, and compaction. Entire reads the full conversation, file changes, and tool calls from Gemini's JSON transcript.

## Limitations

Gemini CLI does not expose subagent lifecycle events. Entire captures the main session.

Entire records input, output, and cached tokens when Gemini writes token counts into the transcript. Sessions without those fields do not have token totals.

## Resume and Import

`entire session resume BRANCH` restores the recorded session data when needed and prints:

```bash theme={null}
gemini --resume SESSION_ID
```

Entire can import existing Gemini CLI transcripts from the previous 30 days as read-only checkpoints.

See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior.


# OpenCode
Source: https://docs.entire.io/agents/opencode

Capture OpenCode transcripts, file changes, tool calls, and token usage with Entire

The OpenCode integration uses a project-level TypeScript plugin and is in preview.

Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps.

## Add OpenCode

```bash theme={null}
entire agent add opencode
opencode
```

Entire writes `.opencode/plugins/entire.ts`. The plugin captures session and turn events, then uses `opencode export` to materialize the full conversation, file changes, tool calls, and token usage.

OpenCode supports commits before a turn ends. Entire refreshes the exported transcript so a checkpoint created mid-turn includes the agent activity available at that point.

## Limitations

OpenCode does not expose subagent lifecycle events. Entire captures the main session. `entire import` cannot import existing OpenCode sessions.

## Resume

`entire session resume BRANCH` restores the recorded session data when needed and prints:

```bash theme={null}
opencode -s SESSION_ID
```

See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior.


# Agent Integrations
Source: https://docs.entire.io/agents/overview

Compare Entire's built-in AI coding agent integrations and their capabilities

Entire uses agent hooks to capture AI coding sessions and connect them to Git commits. Claude Code is the default integration. Choose another integration with its agent name.

## Compare Built-In Integrations

<div>
  <table>
    <colgroup>
      <col />

      <col />

      <col />

      <col />

      <col />

      <col />

      <col />

      <col />
    </colgroup>

    <thead>
      <tr>
        <th>Agent and CLI Name</th>
        <th>Hooks</th>
        <th>Transcript</th>
        <th>Tokens</th>
        <th>Subagents</th>
        <th>Resume</th>
        <th>Import</th>
        <th>Maturity</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td><a href="/agents/claude-code">Claude Code</a><br /><code>claude-code</code></td>
        <td>Native</td><td>Full</td><td>Yes</td><td>All</td><td>Yes</td><td>Yes</td><td>Stable</td>
      </tr>

      <tr>
        <td><a href="/agents/codex">Codex</a><br /><code>codex</code></td>
        <td>Native</td><td>Full</td><td>Yes</td><td>File changes</td><td>Yes</td><td>Yes</td><td>Preview</td>
      </tr>

      <tr>
        <td><a href="/agents/copilot-cli">Copilot CLI</a><br /><code>copilot-cli</code></td>
        <td>Native</td><td>Full</td><td>After session</td><td>Partial</td><td>Yes</td><td>Yes</td><td>Preview</td>
      </tr>

      <tr>
        <td><a href="/agents/cursor">Cursor</a><br /><code>cursor</code></td>
        <td>Native</td><td>Full</td><td>No</td><td>File changes</td><td>No</td><td>Yes</td><td>Preview</td>
      </tr>

      <tr>
        <td><a href="/agents/factory-droid">Factory</a><br /><code>factoryai-droid</code></td>
        <td>Native</td><td>Full</td><td>Yes</td><td>File changes</td><td>Yes</td><td>Yes</td><td>Preview</td>
      </tr>

      <tr>
        <td><a href="/agents/gemini-cli">Gemini CLI</a><br /><code>gemini</code></td>
        <td>Native</td><td>Full</td><td>When present</td><td>No</td><td>Yes</td><td>Yes</td><td>Preview</td>
      </tr>

      <tr>
        <td><a href="/agents/opencode">OpenCode</a><br /><code>opencode</code></td>
        <td>Plugin</td><td>Full</td><td>Yes</td><td>No</td><td>Yes</td><td>No</td><td>Preview</td>
      </tr>

      <tr>
        <td><a href="/agents/pi">Pi</a><br /><code>pi</code></td>
        <td>Extension</td><td>Full</td><td>Yes</td><td>No</td><td>Yes</td><td>Yes</td><td>Preview</td>
      </tr>
    </tbody>
  </table>
</div>

The Subagents column describes which subagents reach a checkpoint. "All" means Entire records every subagent that changed files, plus read-only subagents such as reviewers and search agents when you launch them with `run_in_background`. "File changes" means Entire records the subagents that changed files and skips a subagent that wrote nothing. "Partial" means Copilot CLI provides a subagent stop event without a corresponding start event. Entire notes that the subagent completed, but it cannot take a subagent-specific pre-task snapshot or attach the subagent's transcript.

Claude Code and Factory roll subagent tokens up into the parent session's totals. Codex and Cursor store the transcripts without aggregating their tokens yet. Gemini CLI transcripts include token counts when the agent writes them.

Whichever agent records the subagent, the parent's next checkpoint materializes the subagent's transcript alongside its own, so the checkpoint carries that work without reading back into the agent's transcript directory. entire.io does not browse these records yet.

<Card title="Set Up an Agent" icon="plug" href="/agents/setup">
  Install hooks, add CLI-managed skills, verify capture, and troubleshoot shared setup.
</Card>

<Card title="Agent Integration Protocol" icon="puzzle-piece" href="/agents/agent-integration-protocol/overview">
  Add an agent Entire does not ship with by writing an `entire-agent-<name>` executable. CLI plugins use `entire-<name>` instead and add commands rather than agent support. See working integrations at [github.com/entireio/external-agents](https://github.com/entireio/external-agents).
</Card>

## Agent Integrations

Entire can discover agent integrations from executables named `entire-agent-<name>` on your `$PATH`. Enable external agent discovery with the `external_agents` setting, then use the discovered name with commands such as `entire enable --agent <name>`.

Agent integrations declare their own hooks and capabilities, so their support varies by implementation. See the [Agent Integration Protocol](/agents/agent-integration-protocol/overview) for the protocol, setup, and security model.

## MCP Hosts

`entire mcp` runs a stdio MCP server that exposes Entire's `agent_help` and `status` tools. It gives an MCP host current CLI usage and repository status. It does not replace lifecycle hooks for session capture.


# Pi
Source: https://docs.entire.io/agents/pi

Capture Pi transcripts, file changes, tool calls, and token usage with Entire

The Pi integration uses a project-level TypeScript extension and is in preview.

Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps.

## Add Pi

```bash theme={null}
entire agent add pi
pi
```

Entire writes `.pi/extensions/entire/index.ts`. The extension captures session boundaries, prompts, and completed turns. Entire reads the full conversation, file changes, tool calls, and token usage from Pi's JSONL transcript.

<div>
  <iframe title="Enable Entire for Pi" />
</div>

## Limitations

Pi does not expose a subagent transcript tree. Entire captures the main session. Pi's `write` and `edit` tools provide file paths in the transcript; files changed through shell commands remain visible in the Git diff but may not appear as transcript tool edits.

## Resume and Import

`entire session resume BRANCH` restores the recorded session data when needed and prints:

```bash theme={null}
pi --session SESSION_ID
```

Entire can import existing Pi transcripts from the previous 30 days as read-only checkpoints.

See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior.


# Set Up an Agent
Source: https://docs.entire.io/agents/setup

Install, verify, update, and remove Entire agent hooks

Entire installs repository-level hooks for each AI coding agent you use. Agent hooks capture session events, while Entire's Git hooks connect the captured session to commits.

## Before You Start

Install the [Entire CLI](/installation) and your preferred [agent integration](/agents/overview). Run these commands from a Git repository after you enable Entire.

## Install Agent Hooks

Pass the integration's agent name to `entire agent add`:

```bash theme={null}
entire agent add AGENT_NAME
```

For example:

```bash theme={null}
entire agent add codex
```

You can install hooks for more than one agent in the same repository. Each integration keeps its configuration in the agent's project directory.

During initial Entire setup, select an agent with:

```bash theme={null}
entire enable --agent codex
```

## Agent Integrations

An agent integration adds support for a coding agent through an executable named `entire-agent-<name>`. A CLI plugin uses `entire-<name>` and adds a command instead. Add the agent integration executable to your `$PATH` and enable discovery in `.entire/settings.json`:

```json .entire/settings.json theme={null}
{
  "external_agents": true
}
```

Entire includes discovered integrations in `entire agent list`. During setup, pass the external agent's name without the `entire-agent-` prefix:

```bash theme={null}
entire enable --agent AGENT_NAME
```

See the [Agent Integration Protocol](/agents/agent-integration-protocol/overview) for the protocol and its security considerations.

## Install CLI-Managed Skills

`entire agent add` can also install two repository-level skills:

```bash theme={null}
entire agent add codex --agent-help-skill --search-skill
```

| Flag                 | Installs                                                                                       |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| `--agent-help-skill` | A skill that directs the agent to `entire agent-help` for usage that matches the installed CLI |
| `--search-skill`     | A skill that helps the agent run `entire search --json`                                        |

These flags install the CLI-managed helpers. See [Install Skills](/learn/skills-overview#install-skills) for the Entire Skills collection.

## Hook Locations

| Agent       | Project Configuration            |
| ----------- | -------------------------------- |
| Claude Code | `.claude/settings.json`          |
| Codex       | `.codex/hooks.json`              |
| Copilot CLI | `.github/hooks/entire.json`      |
| Cursor      | `.cursor/hooks.json`             |
| Factory     | `.factory/settings.json`         |
| Gemini CLI  | `.gemini/settings.json`          |
| OpenCode    | `.opencode/plugins/entire.ts`    |
| Pi          | `.pi/extensions/entire/index.ts` |

Entire preserves unrelated configuration when it adds JSON hooks. OpenCode and Pi use generated TypeScript files that Entire can reinstall when their templates change.

## Verify Capture

List the installed integrations and inspect the repository:

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

Start a new agent session from the repository after installing hooks. Existing agent processes do not load hooks added after they started.

Commit a file change to create a checkpoint, then inspect it:

```bash theme={null}
git add .
git commit -m "Describe the change"
entire checkpoint list
```

See [Session Storage](/guides/checkpoints/checkpoint-storage) for where Entire writes checkpoint data.

## Reinstall or Remove Hooks

Reinstall missing, stale, or modified hooks with:

```bash theme={null}
entire agent add AGENT_NAME --force
```

Remove Entire's hooks for one integration with:

```bash theme={null}
entire agent remove AGENT_NAME
```

Removing one integration leaves other agent hooks and Entire's Git hooks in place.

## Troubleshoot Capture

Run `entire doctor` when `entire status --detailed` does not show a session you started. Confirm that the integration's configuration file exists, restart the agent, and run it from inside the repository.

Each agent page documents limitations on transcript capture, token usage, subagent capture, session resume, and transcript import. Use the [capability matrix](/agents/overview#compare-built-in-integrations) to find the relevant page.


# activity
Source: https://docs.entire.io/cli-reference/activity

Show your Entire activity overview from your hosted Entire account.

Show your Entire activity overview from your hosted Entire account.

```bash theme={null}
entire activity [flags]
```

This command loads your activity from the last month from [entire.io](https://entire.io), including:

* Activity overview and aggregate stats
* Repository breakdown
* Recent sessions

| Flag        | Description                                    |
| ----------- | ---------------------------------------------- |
| `--commits` | Show recent commits instead of recent sessions |

If you are not logged in, authenticate first:

```bash theme={null}
entire login
```

When you run `entire activity` in an interactive terminal, it opens a richer terminal UI. In non-interactive contexts, such as piped output, or when accessibility mode is enabled with `ACCESSIBLE=1`, it falls back to a simpler static text view that works better with screen readers.

```bash theme={null}
# Open the interactive activity view
entire activity

# Show recent commits instead of recent sessions
entire activity --commits

# Use simpler static output for screen readers
ACCESSIBLE=1 entire activity
```

<Note>
  `entire activity` shows account-level activity from Entire, not just local repository state.
</Note>


# agent
Source: https://docs.entire.io/cli-reference/agent

Manage agent integrations in the current repository.

Manage agent integrations in the current repository.

```bash theme={null}
entire agent SUBCOMMAND
```

## agent list

List installed and available agents.

```bash theme={null}
entire agent list
```

## agent add

Install hooks for an agent.

```bash theme={null}
entire agent add AGENT_NAME [flags]
```

Use this command to add an agent included with Entire or an `entire-agent-<name>` executable that follows the [Agent Integration Protocol](/agents/agent-integration-protocol/overview). During initial repository setup, use [`entire enable --agent AGENT_NAME`](/cli-reference/enable) instead.

| Flag                 | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `--agent-help-skill` | Install the Entire agent-help skill for the selected agent |
| `--force`            | Reinstall hooks even if already present                    |
| `--search-skill`     | Install the Entire search skill for the selected agent     |

See [Set Up an Agent](/agents/setup) for shared setup, hook locations, verification, and troubleshooting.

## agent remove

Uninstall hooks for an agent.

```bash theme={null}
entire agent remove AGENT_NAME
```


# agent-help
Source: https://docs.entire.io/cli-reference/agent-help

Show agent-facing usage that matches the installed Entire CLI.

Show coding agents which Entire command to use and retrieve exact usage for the installed CLI.

Unlike static command documentation, `agent-help` generates its output from the installed Entire binary. This helps agents avoid guessing commands or flags that may differ between CLI versions.

```bash theme={null}
entire agent-help [COMMAND...] [flags]
```

With no command, `agent-help` prints a high-level map of available commands and when to use them:

```bash theme={null}
entire agent-help
```

The output also identifies the repository detected from the Git remote. You do not need to provide the repository name when working in the current repository.

## Get Help for a Command

Pass a command or nested command path to see its description, subcommands, and currently installed flags:

```bash theme={null}
entire agent-help status
entire agent-help checkpoint explain
entire agent-help session resume
```

The command map only includes commands available in the current installation and repository. Commands that are deprecated, internal, or unavailable for the repository are omitted.

## Get Structured Output

Use `--json` when an agent or script needs structured output:

```bash theme={null}
entire agent-help --json
entire agent-help checkpoint explain --json
```

The JSON response includes the command name, short and long descriptions, detected repository, subcommands, and flags when applicable.

## Flags

| Flag           | Description                          |
| -------------- | ------------------------------------ |
| `--json`       | Emit structured JSON instead of text |
| `--help`, `-h` | Show help for `agent-help`           |

<Note>
  `entire agent-help` describes the CLI installed on your machine. Use this command as the source of truth when its output differs from static documentation.
</Note>


# api
Source: https://docs.entire.io/cli-reference/api

Make an authenticated request to an Entire API and print the response.

Make an authenticated HTTP request to an Entire API and print the JSON response.

```bash theme={null}
entire api PATH [flags]
```

Entire selects the backend host and supplies the bearer token automatically.

<Warning>
  These internal endpoints may change without notice. Prefer dedicated CLI commands such as [`entire activity`](/cli-reference/activity), [`entire search`](/cli-reference/search), and [`entire repo`](/cli-reference/repo) when available.
</Warning>

## Choose a Backend

| Value       | Backend                                                                            |
| ----------- | ---------------------------------------------------------------------------------- |
| `--to core` | The control plane. This is the default: orgs, repos, mirrors, clusters, and `/me`. |
| `--to cell` | Your home `entire-api` cell: `/me/*` activity and repository aggregates.           |

Use `--jurisdiction SLUG` to reach a specific jurisdiction's cell instead of your home one. It implies `--to cell`. Find your home jurisdiction with [`entire auth status`](/cli-reference/auth#auth-status).

## Path Placeholders

`PATH` is the full path on the chosen host, such as `/api/v1/clusters`. These placeholders are filled from the current repository's `origin` remote:

| Placeholder | Value                                                             |
| ----------- | ----------------------------------------------------------------- |
| `{owner}`   | The GitHub owner                                                  |
| `{repo}`    | The GitHub repository name                                        |
| `{repo_id}` | The repository's Entire ULID, from its mirror. Cells key on this. |

## Flags

| Flag                        | Description                                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `-F, --field KEY=VALUE`     | Add a typed parameter. `true`, `false`, `null`, and numbers are converted. Repeatable.                       |
| `-H, --header KEY:VALUE`    | Add a request header. Repeatable.                                                                            |
| `-i, --include`             | Print the response status line and headers too.                                                              |
| `--input FILE`              | File containing the request body. Use `-` for standard input.                                                |
| `-j, --jurisdiction SLUG`   | Target a specific jurisdiction's cell, such as `us` or `eu`, instead of your home cell. Implies `--to cell`. |
| `-X, --method METHOD`       | HTTP method. Defaults to `GET`, or `POST` when a field or body is given.                                     |
| `-f, --raw-field KEY=VALUE` | Add a string parameter, with no type conversion. Repeatable.                                                 |
| `--to BACKEND`              | Which backend to call: `core` or `cell`. Defaults to `core`.                                                 |

## Examples

```bash theme={null}
# Control plane
entire api /api/v1/clusters

# Your home cell
entire api --to cell /api/v1/me/activity

# A specific jurisdiction's cell
entire api --jurisdiction eu /api/v1/me/activity

# Fill the current repository's ULID into the path
entire api --to cell "/api/v1/me/recap?repo={repo_id}"

# POST with a string field
entire api -X POST /api/v1/projects -f name=demo
```

## Continue With

<CardGroup>
  <Card title="auth token" icon="key" href="/cli-reference/auth#auth-token">
    Get the bearer token itself, for use with `curl`.
  </Card>

  <Card title="repo" icon="database" href="/cli-reference/repo">
    Use the purpose-built commands where they exist.
  </Card>
</CardGroup>


# auth
Source: https://docs.entire.io/cli-reference/auth

Manage authentication and saved login contexts.

Manage authentication and saved login contexts.

```bash theme={null}
entire auth SUBCOMMAND
```

## Login Contexts

A **context** is a saved login. Each one pairs a login server with an identity, and stores its tokens in your operating system's credential store. Contexts are recorded in `~/.config/entire/contexts.json`, or `$ENTIRE_CONFIG_DIR/contexts.json` when that variable is set.

One context is active at a time. The active context supplies the identity for every authenticated operation: `git clone entire://…`, the control-plane commands ([`org`](/cli-reference/org), [`project`](/cli-reference/project), [`repo`](/cli-reference/repo), [`grant`](/cli-reference/grant)), and the data commands ([`activity`](/cli-reference/activity), [`search`](/cli-reference/search), [`dispatch`](/cli-reference/dispatch)).

Entire names a new context after its login server's host. When you log in as a second identity on a host that already has a context, Entire names the new one `HANDLE@HOST` instead of replacing the first.

To act as a different context for a single command, use the [`--context` global flag](/cli-reference/global-flags) instead of switching.

## auth login

Authenticate with your Entire account. Equivalent to the top-level [`entire login`](/cli-reference/login).

```bash theme={null}
entire auth login [flags]
```

See [`entire login`](/cli-reference/login) for the `--device` and `--server` flags.

## auth logout

Sign out of your Entire account. Equivalent to the top-level [`entire logout`](/cli-reference/logout).

```bash theme={null}
entire auth logout [flags]
```

See [`entire logout`](/cli-reference/logout) for the `--all-contexts` and `--everywhere` flags.

## auth status

Show authentication status for the active context.

```bash theme={null}
entire auth status
```

The report covers your handle, display name, email, identity provider, home jurisdiction, the active context and how many contexts are saved, and the login sessions currently active on the login server.

Use it to find your home jurisdiction slug, which [`entire auth token`](#auth-token), [`entire api`](/cli-reference/api), and [`entire dispatch`](/cli-reference/dispatch) accept as `--jurisdiction`.

## auth contexts

List saved login contexts and mark the active one.

```bash theme={null}
entire auth contexts
```

The table shows each context's name, handle, and login server. An asterisk marks the active context. This command is local only and makes no network requests.

```text theme={null}
  CONTEXT              HANDLE        LOGIN SERVER
* auth.entire.io       octocat       https://auth.entire.io
  staging.entire.io    octocat       https://staging.entire.io
```

## auth use

Switch the active login context.

```bash theme={null}
entire auth use CONTEXT
```

The switch takes effect on the next operation. It is persistent and machine-wide: it changes the identity for every shell, worktree, and background Git hook until you switch back.

```bash theme={null}
entire auth use staging.entire.io
```

## auth token

Print an Entire bearer token for use in scripts and `curl` requests.

```bash theme={null}
entire auth token [flags]
```

By default this prints the control-plane bearer, the same token the CLI's own API client uses: `ENTIRE_TOKEN` verbatim when that variable is set, otherwise the active context's login JWT, refreshed if it is near expiry.

With `--jurisdiction SLUG`, Entire mints a jurisdictional identity token instead, for that jurisdiction's `entire-api` cells. Those cells reject the control-plane bearer. Find your jurisdiction with [`entire auth status`](#auth-status).

| Flag                      | Description                                                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `-j, --jurisdiction SLUG` | Mint a jurisdictional identity token for this jurisdiction, such as `us` or `eu`, for use against that jurisdiction's cells. |

```bash theme={null}
curl -H "Authorization: Bearer $(entire auth token)" \
  "https://us.console.entire.io/api/v1/clusters"

curl -H "Authorization: Bearer $(entire auth token --jurisdiction us)" \
  "https://aws-us-east-2.api.entire.io/api/v1/me/activity"
```

Only the token goes to standard output. Errors and the not-logged-in hint go to standard error, so command substitution stays clean.

<Warning>
  The output is a live credential. Treat it as a secret: do not log it, commit it, or paste it into a shared transcript.
</Warning>

## Continue With

<CardGroup>
  <Card title="Global Flags" icon="flag" href="/cli-reference/global-flags">
    Act as another login for a single command with `--context`.
  </Card>

  <Card title="api" icon="terminal" href="/cli-reference/api">
    Make authenticated requests without handling tokens yourself.
  </Card>
</CardGroup>


# blame
Source: https://docs.entire.io/cli-reference/blame

A git-blame-style command for viewing file history with checkpoint and session context.

`entire blame` is a git-blame-style command for viewing file history with checkpoint and session context.

```bash theme={null}
entire blame FILE[:LINE[-LINE]] [flags]
```

Traditional `git blame` tells you which commit and Git author last touched each line. But after agent-assisted work, the Git author is often not the whole story. `entire blame` starts from the same line history, then tells you the intent behind how the code was created: the prompt that asked for it, the session it came from, and the checkpoint that saved it.

<Frame>
  <div>
    <iframe title="Entire blame demo" />
  </div>
</Frame>

Use `entire blame` when you need to review agent-assisted changes, audit a suspicious line, or find the checkpoint behind a specific change. The command works in Entire-enabled repositories and supports JSON output for scripts and tooling.

## Try it

Run `entire blame` from an Entire-enabled repository, then pass the file you want to inspect.

```bash theme={null}
entire blame path/to/file.ts
entire blame path/to/file.ts --line 12-20
entire blame path/to/file.ts --long
entire blame path/to/file.ts --json
```

`FILE:12` and `FILE:12-20` are equivalent to passing `--line`.

## Attribution Tags

Each line shows the attribution status of the commit that introduced it. Tags are commit-level signals:

* `AI`: the commit was attributed to an AI agent session
* `MX`: the commit mixed AI-attributed and human-attributed work
* `HU`: the commit was made without AI-attributed checkpoint data
* `??`: the line is uncommitted

When available, the output also links lines to their Entire checkpoint metadata. A line never changes tag between `entire blame` and [`entire why`](/cli-reference/why).

See [What do `entire blame` and `entire why` actually tell me?](/faq#what-do-entire-blame-and-entire-why-actually-tell-me) for what these tags do and do not promise.

## Flags

| Flag                   | Description                                                                    |
| ---------------------- | ------------------------------------------------------------------------------ |
| `--line LINE_OR_RANGE` | Only show a line or range, for example `12` or `12-20`                         |
| `--long`               | Show the full attribution table with agent, model, author, and session columns |
| `--json`               | Output attribution as JSON                                                     |

## Continue With

<CardGroup>
  <Card title="Investigate Why Code Exists" icon="search-code" href="/learn/investigate-why-code-exists">
    Trace a surprising line from attribution to checkpoint context.
  </Card>

  <Card title="why" icon="terminal" href="/cli-reference/why">
    Explain the context behind a file or line.
  </Card>

  <Card title="Introducing entire blame" icon="newspaper" href="https://entire.io/blog/introducing-entire-blame">
    Read the launch post on the Entire blog.
  </Card>
</CardGroup>


# checkpoint
Source: https://docs.entire.io/cli-reference/checkpoint

List, explain, measure, and search checkpoints.

Work with checkpoints captured by Entire.

```bash theme={null}
entire checkpoint SUBCOMMAND
```

`entire checkpoint` is also available as `entire cp` and `entire checkpoints`.

## checkpoint list

List checkpoints on the current branch.

```bash theme={null}
entire checkpoint list [flags]
```

| Flag           | Description                                                                                                                                                                 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`       | Output as JSON instead of the human view                                                                                                                                    |
| `--no-pager`   | Disable pager output                                                                                                                                                        |
| `--pending`    | List the live session's shadow-branch rewind points, plus logs-only resume points recovered from commits whose logs are already condensed, instead of condensed checkpoints |
| `--session ID` | Filter checkpoints by session ID (or prefix). Not valid with `--pending`                                                                                                    |

## checkpoint explain

Show human-readable context for checkpoints, sessions, and commits. Add `--generate` for an AI-written summary.

```bash theme={null}
entire checkpoint explain [CHECKPOINT_ID | COMMIT_SHA] [flags]
```

| Flag                          | Description                                                                                                                                                             |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c, --checkpoint ID`         | Explain a specific checkpoint (ID or prefix)                                                                                                                            |
| `--commit SHA`                | Explain a specific commit (SHA or ref, "commit-ish")                                                                                                                    |
| `--force`                     | Regenerate summary even if one already exists (requires `--generate`)                                                                                                   |
| `--full`                      | Show full parsed transcript (all prompts/responses)                                                                                                                     |
| `--generate`                  | Generate an AI summary for the checkpoint                                                                                                                               |
| `--insecure-http-auth`        | Allow plain HTTP auth for `--repo`. Local development only.                                                                                                             |
| `--json`                      | Output metadata as JSON. See [Machine-Readable Output](#machine-readable-output).                                                                                       |
| `--limit N`                   | Cap the list view at N checkpoints. Defaults to `100`. Only meaningful with `--json`.                                                                                   |
| `--no-pager`                  | Disable pager output                                                                                                                                                    |
| `--raw-transcript`            | Show raw transcript file (JSONL format)                                                                                                                                 |
| `--repo OWNER/REPO`           | See [Explain a Checkpoint in Another Repository](#explain-a-checkpoint-in-another-repository).                                                                          |
| `--search-all`                | Search all commits (no branch/depth limit, may be slow)                                                                                                                 |
| `--session ID`                | Filter checkpoints by session ID (or prefix)                                                                                                                            |
| `--session-index N`           | Pick a session within a multi-session checkpoint, 0-based. Defaults to the latest. Only meaningful with `--transcript` or `--raw-transcript`.                           |
| `-s, --short`                 | Show summary only (omit prompts and files)                                                                                                                              |
| `--summary-timeout-seconds N` | Hard deadline in seconds for `--generate`. Overrides the `summary_timeout_seconds` setting. `0` uses the setting; if that is also unset, no automatic deadline applies. |
| `--transcript`                | Stream stored checkpoint transcript bytes (JSONL) to stdout                                                                                                             |

<Note>
  The `--generate` flag requires the configured provider CLI, such as Claude CLI, to be installed and authenticated.
</Note>

### Machine-Readable Output

`--json` emits metadata only. With no target it lists checkpoints; with a target it emits a single checkpoint envelope. Transcript bytes are never embedded in that envelope.

To get the transcript itself, use `--transcript`, which streams the stored checkpoint transcript bytes to standard output:

```bash theme={null}
entire checkpoint explain 01KVBJCW --json
entire checkpoint explain 01KVBJCW --transcript > session.jsonl
entire checkpoint explain 01KVBJCW --transcript --session-index 0 > first-session.jsonl
```

### Explain a Checkpoint in Another Repository

`--repo` reads a checkpoint owned by a different repository through that repository's Entire API. This is the drill-down for a cross-repo [`entire search`](/cli-reference/search) hit. Nothing is written to the current repository.

```bash theme={null}
entire checkpoint explain CHECKPOINT_ID --repo owner/name
```

This needs the full checkpoint ID, passed positionally or with `--checkpoint`, and a checkpoint that has been pushed.

## checkpoint tokens

Show token usage and optimization recommendations for a checkpoint.

```bash theme={null}
entire checkpoint tokens CHECKPOINT_ID [flags]
```

| Flag            | Description                                  |
| --------------- | -------------------------------------------- |
| `--agent-brief` | Output compact next-step guidance for agents |
| `--compare ID`  | Compare against a baseline checkpoint ID     |
| `--json`        | Output as JSON                               |

`--json` and `--agent-brief` are mutually exclusive.

The report resolves its target through the same path as `checkpoint explain`: an unambiguous checkpoint ID prefix, or a commit-ish carrying an `Entire-Checkpoint` trailer. Metadata missing locally is fetched from the checkpoint remote.

```bash theme={null}
entire checkpoint tokens 01KVBJCW
entire checkpoint tokens 01KVBJCW --compare 01KVBK7Q
entire checkpoint tokens 01KVBJCW --json
```

## checkpoint search

Search checkpoints using semantic and keyword matching.

```bash theme={null}
entire checkpoint search [QUERY] [flags]
```

`entire checkpoint search` is an alias for [`entire search`](/cli-reference/search). See that page for the [flags](/cli-reference/search#flags), inline filters, code search, and the interactive result view.

## checkpoint policy

Inspect and update this repository's checkpoint policy.

```bash theme={null}
entire checkpoint policy [flags]
```

| Flag                               | Description                                                        |
| ---------------------------------- | ------------------------------------------------------------------ |
| `--checkpoint-version VERSION`     | Set `checkpoint_version`. Use `""` to inherit the CLI default.     |
| `--checkpoint-min-version VERSION` | Set `checkpoint_min_version`. Use `""` to inherit the CLI default. |
| `--force`                          | Allow a checkpoint policy version downgrade                        |

`checkpoint_version` is a write guard on checkpoint data. When no policy is configured, Entire uses the CLI default. If another client configures a `checkpoint_version` your CLI cannot write, commands that create checkpoint data fail until you upgrade. Other commands warn and continue.

`checkpoint_min_version` is both an upgrade nudge and a write guard. Clients that cannot read that version warn users to upgrade, and commands that create checkpoint data fail until the CLI is upgraded. Other commands warn and continue.

Unsetting either field still applies the downgrade guard. If inheriting the default would lower the field's effective version, pass `--force` to allow it.

<Note>
  `entire checkpoint policy` is experimental. [`entire import`](/cli-reference/import) honors checkpoint policy before it scans transcripts, so an unsupported policy fails an import even under `--dry-run`.
</Note>


# clean
Source: https://docs.entire.io/cli-reference/clean

Clean up Entire session data.

Clean up Entire session data.

```bash theme={null}
entire clean [flags]
```

| Flag            | Description                                             |
| --------------- | ------------------------------------------------------- |
| `-a, --all`     | Clean all Entire session data across the repository     |
| `-d, --dry-run` | Show what would be cleaned without actually deleting    |
| `-f, --force`   | Skip confirmation and override the active-session guard |
| `--session ID`  | Clean a specific session by ID                          |

By default, `entire clean` removes session data for the current `HEAD` commit:

* Session state files for sessions based on the current commit
* The shadow branch for the current commit and worktree

Use `--session ID` to clean a single session. This removes the session state and deletes its shadow branch if no other session still needs it. File changes remain in your working directory.

Use `--all` to clean Entire session data across the repository:

* All session state files in `.git/entire-sessions/`
* All shadow branches
* Temporary files in `.entire/tmp/`

Committed checkpoint data is preserved: the refs under `refs/entire/checkpoints/`, or the `entire/checkpoints/v1` branch in repositories that use the legacy branch backend.

```bash theme={null}
# Preview cleanup for the current HEAD
entire clean --dry-run

# Clean one session
entire clean --session 2026-02-02-test123 --force

# Clean all session data in the repository
entire clean --all --force
```

<Note>
  `entire reset` has been removed. Use `entire clean` instead, or `entire clean --all` for repository-wide cleanup.
</Note>


# completion
Source: https://docs.entire.io/cli-reference/completion

Generate a shell completion script for the Entire CLI.

Generate the autocompletion script for `entire` for the specified shell.

```bash theme={null}
entire completion SHELL
```

| Shell      | Command                        |
| ---------- | ------------------------------ |
| Bash       | `entire completion bash`       |
| Zsh        | `entire completion zsh`        |
| Fish       | `entire completion fish`       |
| PowerShell | `entire completion powershell` |

Each subcommand prints a script to stdout. Run `entire completion SHELL --help` for the shell-specific instructions on where to load it. For Bash and Zsh, the quickest option is to source it from your shell profile:

```bash theme={null}
source <(entire completion zsh)
```

See [Shell Completion](/installation#shell-completion) in the installation guide for profile snippets.

## Continue With

<CardGroup>
  <Card title="Installation" icon="download" href="/installation">
    Install and update the Entire CLI.
  </Card>

  <Card title="Global Flags" icon="flag" href="/cli-reference/global-flags">
    Flags every command accepts.
  </Card>
</CardGroup>


# configure
Source: https://docs.entire.io/cli-reference/configure

Update non-agent Entire settings in the current repository, such as telemetry, Git hook installation mode, strategy options, and the summary provider.

Update non-agent Entire settings in the current repository: telemetry, Git hook installation mode, strategy options, and the summary provider. Agent hook installation is handled by [`entire agent`](/cli-reference/agent). Running `entire configure` with no flags prints its help.

```bash theme={null}
entire configure [flags]
```

| Flag                                      | Description                                                                                                                                                                 |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--absolute-git-hook-path`                | Embed full binary path in Git hooks. Required for GUI Git clients that don't source shell profiles. See [GUI Git Clients](/guides/configuration/git-hooks#gui-git-clients). |
| `--checkpoint-backend BACKEND`            | Set checkpoint storage to `refs` (one Git ref per checkpoint) or `branch` (one shared branch).                                                                              |
| `--checkpoint-remote PROVIDER:OWNER/REPO` | Push checkpoint data to a separate repository (e.g., `github:org/checkpoints-private`). See [Checkpoint Remote](/guides/checkpoints/store-checkpoints-in-another-repo).     |
| `-f, --force`                             | Force reinstall the Entire Git hook                                                                                                                                         |
| `--local`                                 | Write settings to `.entire/settings.local.json` instead of `.entire/settings.json`                                                                                          |
| `--project`                               | Write settings to `.entire/settings.json` even if it already exists                                                                                                         |
| `--skip-push-sessions`                    | Disable automatic pushing of session logs on Git push                                                                                                                       |
| `--summarize-model MODEL`                 | Set the model hint used by `checkpoint explain --generate`                                                                                                                  |
| `--summarize-provider PROVIDER`           | Set the provider used by `checkpoint explain --generate`. Requires an installed agent that supports text generation.                                                        |
| `--summarize-timeout-seconds N`           | Set the hard deadline in seconds for `checkpoint explain --generate`. `0` clears the setting, leaving summary generation unbounded.                                         |
| `--telemetry`                             | Enable anonymous usage analytics (default: true)                                                                                                                            |

Use `entire agent remove NAME` to uninstall hooks for a specific agent.


# disable
Source: https://docs.entire.io/cli-reference/disable

Remove Entire hooks from a repository. This stops session capture but preserves existing session data.

Remove Entire hooks from a repository. This stops session capture but preserves existing session data.

```bash theme={null}
entire disable [flags]
```

| Flag          | Description                                                             |
| ------------- | ----------------------------------------------------------------------- |
| `--force`     | Skip confirmation prompt (use with `--uninstall`)                       |
| `--local`     | Update `.entire/settings.local.json`. This is the default.              |
| `--project`   | Update `.entire/settings.json` instead of `.entire/settings.local.json` |
| `--uninstall` | Completely remove Entire from this repository                           |

<Note>
  Disabling Entire does not delete your session history. You can re-enable at any time with `entire enable`. Use `--uninstall` to completely remove Entire from the repository.
</Note>


# dispatch
Source: https://docs.entire.io/cli-reference/dispatch

Generate a dispatch summarizing recent agent work.

Generate a dispatch summarizing recent agent work.

```bash theme={null}
entire dispatch [flags]
```

`entire dispatch` has two modes:

* **Cloud mode** (default) generates a dispatch from Entire server data
* **Local mode** (`--local`) generates a dispatch from local repository data using your locally installed agent CLI

If you run `entire dispatch` with no flags in an interactive terminal, Entire launches a guided wizard. In non-interactive contexts, or whenever you provide flags, it prints markdown output directly.

| Flag                      | Description                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--local`                 | Generate via the locally installed agent CLI instead of the Entire server                                       |
| `--since TIME`            | Start of the time window. Accepts Go durations, relative times, or ISO dates. Defaults to `7d`.                 |
| `--until TIME`            | End of the time window. Defaults to now.                                                                        |
| `--all-branches`          | Include every existing local branch. Only valid with `--local`.                                                 |
| `--repos OWNER/REPO`      | Limit cloud dispatch to one or more repos. Accepts comma-separated GitHub repo slugs.                           |
| `--voice PRESET_OR_TEXT`  | Customize the dispatch tone with a preset such as `neutral` or `marvin`, or provide your own text.              |
| `--agent NAME`            | Local text-generation agent to use. Only valid with `--local`.                                                  |
| `-j, --jurisdiction SLUG` | Jurisdiction whose cell generates the cloud dispatch, such as `us` or `eu`. Defaults to your home jurisdiction. |

Use cloud mode when you want a dispatch from Entire-tracked repo data:

```bash theme={null}
# Default dispatch for recent work in the current repo
entire dispatch

# Limit cloud dispatch to specific repos
entire dispatch --repos entireio/cli,entireio/entire.io
```

Use local mode when you want a dispatch from local repository history:

```bash theme={null}
# Local dispatch from the current branch
entire dispatch --local

# Local dispatch across all local branches
entire dispatch --local --all-branches
```

You can also customize the dispatch voice:

```bash theme={null}
entire dispatch --voice neutral
```

<Note>
  `--repos` cannot be combined with `--local`, and `--all-branches` only applies to `--local`.
</Note>

<Note>
  Cloud dispatch supports up to 5 repos per request, and each repo must use `owner/repo` format.
</Note>

## Jurisdictions

A cloud dispatch covers repositories placed in exactly one jurisdiction, and is generated by that jurisdiction's cell. Without `--jurisdiction`, Entire uses your home jurisdiction, which [`entire auth status`](/cli-reference/auth#auth-status) reports.

A repository mirrored only elsewhere is reported as not found in your home jurisdiction. Pass `--jurisdiction SLUG` to target the jurisdiction the repository is actually placed in:

```bash theme={null}
entire dispatch --repos entirehq/ferrata --jurisdiction us
```


# doctor
Source: https://docs.entire.io/cli-reference/doctor

Diagnose session, log, and hook problems in a repository, and offer to fix them.

Diagnose problems in the current repository and offer to fix them.

```bash theme={null}
entire doctor [flags]
```

| Flag          | Description                                                                |
| ------------- | -------------------------------------------------------------------------- |
| `-f, --force` | Fix all issues without prompting (condense if possible, otherwise discard) |

## What Doctor Checks

| Check                          | What it reports                                                                                                                                            |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Disconnected metadata branches | The local and remote `entire/checkpoints/v1` branches share no common ancestor. Doctor fixes this by cherry-picking local checkpoints onto the remote tip. |
| Operational logs               | Entire cannot write to `.entire/logs`, so diagnostics may be missing.                                                                                      |
| Codex hook trust               | Installed Codex hooks lack a `trusted_hash` entry in your Codex config. Review and approve them with `/hooks` in Codex.                                    |
| Hook config drift              | Installed agent hooks differ from the current CLI configuration. Run `entire enable --force` to reinstall them.                                            |
| Stuck sessions                 | See [Stuck Sessions](#stuck-sessions) below.                                                                                                               |

## Stuck Sessions

A session is considered stuck if:

* It is in ACTIVE phase with no interaction for over 1 hour
* It is in ENDED phase with uncondensed checkpoint data on a shadow branch

For each stuck session, you can choose to:

* **Condense**: Save session data to permanent [checkpoint storage](/guides/checkpoints/checkpoint-storage)
* **Discard**: Remove the session state and shadow branch data
* **Skip**: Leave the session as-is

Without a terminal to prompt on, such as an agent or CI, `entire doctor` reports each issue and points at `--force` instead of prompting.

## doctor migrate-checkpoints

Convert the checkpoints on the `entire/checkpoints/v1` branch into per-checkpoint refs under `refs/entire/checkpoints/<shard>/<id>`, the layout the ref-based backend uses.

```bash theme={null}
entire doctor migrate-checkpoints [flags]
```

| Flag            | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `--dry-run`     | Report what would be migrated without writing refs                      |
| `--remote NAME` | Remote to push migrated refs to. Defaults to the checkpoint sync remote |

Each checkpoint keeps its 12-character hex ID as the ref name, and its current tree is wrapped in a fresh commit. The command does not remap the existing branch commits and does not delete the branch. It skips checkpoints it has already converted, so re-running it after more branch activity is safe.

Run it while the branch backend is still primary. Once `checkpoints.primary.type` is `git-refs`, the command reports that there is nothing to migrate and exits, because the refs are authoritative at that point.

New refs are queued for push. Run interactively, the command asks whether to push them now. Run without a terminal, it leaves them queued, and they flush on the next `git push` once the ref-based backend is primary.

<Note>
  Migration is optional. See [Both Backends Stay Readable](/guides/checkpoints/checkpoint-storage#both-backends-stay-readable) for how readers resolve branch-backed checkpoints after a switch.
</Note>

## doctor logs

Show recent operational logs.

```bash theme={null}
entire doctor logs [flags]
```

| Flag           | Description                                                |
| -------------- | ---------------------------------------------------------- |
| `-f, --follow` | Stream new log lines as they are written                   |
| `--tail N`     | Show the last N lines. Use `0` for all. Defaults to `100`. |

## doctor bundle

Produce a diagnostic bundle for bug reports.

```bash theme={null}
entire doctor bundle [flags]
```

| Flag             | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| `-o, --out PATH` | Path to write the bundle archive. Defaults to the OS temp directory.             |
| `--raw`          | Skip secret redaction. Use only when support has asked for an unredacted bundle. |

## doctor trace

Show hook performance traces for debugging slow Git operations.

```bash theme={null}
entire doctor trace [flags]
```

| Flag          | Description                                                                                                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `--hook TYPE` | Filter by hook type, such as `post-commit`, `prepare-commit-msg`, or `pre-push`                                                          |
| `--json`      | Output as JSON                                                                                                                           |
| `--last N`    | Show the last N hook invocations. Defaults to `1`.                                                                                       |
| `--slow`      | Only include traces flagged slow, meaning those logged at WARN                                                                           |
| `--summary`   | Aggregate across traces instead of showing each one, reporting which step dominates per hook. Uses `--last 200` unless you set `--last`. |

```bash theme={null}
# The most recent hook trace
entire doctor trace

# The last five post-commit traces
entire doctor trace --last 5 --hook post-commit

# Which step dominates, across the slow traces only
entire doctor trace --summary --slow
```

Hooks that take 1.5 seconds or longer are traced by default, at WARN level, so a slow hook records its own breakdown with no configuration. Set `ENTIRE_PERF_SLOW_MS=0` to turn that off. A `log_level` above WARN also hides them.

<Note>
  To trace every hook, including fast ones, raise verbosity: set `ENTIRE_LOG_LEVEL=DEBUG` in your shell profile, or add `"log_level": "DEBUG"` to `.entire/settings.json`.
</Note>


# enable
Source: https://docs.entire.io/cli-reference/enable

Initialize Entire in a Git repository. This installs the necessary Git hooks to capture AI coding sessions.

Initialize Entire in a Git repository. This installs the necessary Git hooks to capture AI coding sessions.

```bash theme={null}
entire enable [flags]
```

If Entire is not yet configured, this runs the full configuration flow. If Entire is already configured but disabled, this re-enables it. In a directory that is not a Git repository, see [Bootstrap a New Repository](#bootstrap-a-new-repository).

## Flags

| Flag                                      | Description                                                                                                                                                                                                                                                                         |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--absolute-git-hook-path`                | Embed full binary path in Git hooks. Required for GUI Git clients that don't source shell profiles. See [GUI Git Clients](/guides/configuration/git-hooks#gui-git-clients).                                                                                                         |
| `--agent NAME`                            | Agent to set up hooks for: `claude-code`, `codex`, `gemini`, `opencode`, `cursor`, `copilot-cli`, `factoryai-droid`, `pi`, or an `entire-agent-<name>` executable that follows the [Agent Integration Protocol](/agents/agent-integration-protocol/overview). Runs without prompts. |
| `--agent-help-skill`                      | Install the Entire agent-help Skill, which points agents at [`entire agent-help`](/cli-reference/agent-help), for the selected agents.                                                                                                                                              |
| `--checkpoint-backend BACKEND`            | Set checkpoint storage to `refs` (one Git ref per checkpoint) or `branch` (one shared branch). A first-time setup uses `refs` when you omit the flag.                                                                                                                               |
| `--checkpoint-remote PROVIDER:OWNER/REPO` | Push checkpoint data to a separate repository (e.g., `github:org/checkpoints-private`). See [Checkpoint Remote](/guides/checkpoints/store-checkpoints-in-another-repo).                                                                                                             |
| `-f, --force`                             | Force reinstall hooks (removes existing Entire hooks first)                                                                                                                                                                                                                         |
| `--import-history`                        | During first-time setup, import the selected agents' existing session history from the last 30 days without prompting. See [`entire import`](/cli-reference/import).                                                                                                                |
| `--local`                                 | Write settings to `.entire/settings.local.json` instead of `.entire/settings.json`.                                                                                                                                                                                                 |
| `--project`                               | Write settings to `.entire/settings.json` even if it already exists                                                                                                                                                                                                                 |
| `--search-skill`                          | Install the Entire search Skill for the selected agents. See [`entire search`](/cli-reference/search).                                                                                                                                                                              |
| `--skip-push-sessions`                    | Disable automatic pushing of session logs on Git push                                                                                                                                                                                                                               |
| `--telemetry`                             | Enable anonymous usage analytics (default: true)                                                                                                                                                                                                                                    |
| `-y, --yes`                               | Accept defaults without prompting. Useful for automation, CI, and bootstrap flows.                                                                                                                                                                                                  |

Use `--yes` for non-interactive setup flows:

```bash theme={null}
# Non-interactive setup for a specific agent
entire enable --yes --agent claude-code

# Non-interactive setup using default choices
entire enable --yes
```

To add another agent after initial setup, run [`entire agent add AGENT_NAME`](/cli-reference/agent#agent-add).

`--yes` is not just a confirmation bypass. It runs `entire enable` non-interactively with default choices. On a fresh repository, it enables the default setup without prompts. On an already configured repository, it follows the setup-management path. Outside a Git repository, it also accepts the bootstrap defaults to initialize Git, create a private GitHub repository through `gh`, create the initial commit, and push it.

Important behavior:

* If you also pass `--agent NAME`, that explicit agent selection takes precedence over the default multi-agent behavior.
* If you pass `--telemetry=false`, or set `ENTIRE_TELEMETRY_OPTOUT`, that explicit telemetry opt-out still overrides the `--yes` default.
* `--yes` does not import existing agent history. Add `--import-history` when you want the last 30 days of transcripts imported too.

<Note>
  The `--local` and `--project` flags control which Entire settings file is modified. Entire always modifies the agent's **project** settings (e.g., `.claude/settings.json`, `.gemini/settings.json`, `.opencode/plugins/entire.ts`, `.factory/settings.json`, or `.pi/extensions/entire/index.ts`).
</Note>

## Bootstrap a New Repository

When run outside a Git repository, `entire enable` offers to initialize one, create a matching GitHub repository through the `gh` CLI, and make the initial commit. Use these flags for non-interactive setup:

| Flag                               | Description                                                                                                                                  |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--init-repo`                      | Initialize a Git repository non-interactively when the directory is not one.                                                                 |
| `--no-init-repo`                   | Exit instead of prompting to initialize a repository.                                                                                        |
| `--no-github`                      | Initialize the local Git repository only, and skip creating a GitHub remote.                                                                 |
| `--repo-name NAME`                 | GitHub repository name for the new repository.                                                                                               |
| `--repo-owner LOGIN`               | GitHub user or organization login to own the new repository.                                                                                 |
| `--repo-visibility VISIBILITY`     | GitHub repository visibility: `public`, `private`, or `internal`.                                                                            |
| `--initial-commit-message MESSAGE` | Commit message for the initial commit.                                                                                                       |
| `--skip-initial-commit`            | Don't create the initial commit.                                                                                                             |
| `--push`                           | Push the initial commit to the created GitHub remote. This implies creating the remote; without it the repository is created but not pushed. |

```bash theme={null}
# Bootstrap a private GitHub repository and push the first commit
entire enable --init-repo --repo-owner my-org --repo-name my-service \
  --repo-visibility private --push --agent claude-code

# Local Git repository only, no GitHub remote
entire enable --init-repo --no-github --agent claude-code

# Fail rather than prompt when this isn't a repository
entire enable --no-init-repo
```


# experts
Source: https://docs.entire.io/cli-reference/experts

Rank agents, Skills, and tools by their contributions to a file, directory, or topic.

Rank agents, Skills, and tools by their contributions to a file, directory, or topic.

```bash theme={null}
entire experts [SCOPE_OR_QUERY] [flags]
```

`entire experts` is experimental and appears under [labs](/cli-reference/labs) while the workflow is still being refined.

## Inputs

The argument is either a single scope, meaning a file or directory path, or a natural-language query. One of the two is required unless you pass `--staged`, which uses your staged file paths as the scopes instead.

## Flags

| Flag                | Description                                                                             |
| ------------------- | --------------------------------------------------------------------------------------- |
| `--branch NAME`     | Branch to inspect.                                                                      |
| `--json`            | Print JSON.                                                                             |
| `--limit N`         | Maximum profiles to return, from 1 to 20. Values above 20 are clamped. Defaults to `8`. |
| `--repo OWNER/REPO` | Repository to inspect.                                                                  |
| `--staged`          | Use staged file paths as the scopes.                                                    |
| `--tui`             | Browse provenance in an interactive viewer. Requires a terminal.                        |

## Examples

```bash theme={null}
# Provenance for a directory
entire experts src/payments --json

# Provenance for a natural-language query
entire experts "who owns token refresh"

# Provenance for what you are about to commit
entire experts --staged
```

<Note>
  The repository must be [mirrored](/guides/repositories/mirrors).
</Note>

## Continue With

<CardGroup>
  <Card title="blame" icon="terminal" href="/cli-reference/blame">
    See per-line attribution for a single file.
  </Card>

  <Card title="why" icon="circle-question" href="/cli-reference/why">
    Explain the context behind a file or line.
  </Card>
</CardGroup>


# Global Flags
Source: https://docs.entire.io/cli-reference/global-flags

Shared flags and environment variables, plus the root-only version flag.

These flags are available on the root command and on every subcommand:

| Flag             | Description                                                                                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--context NAME` | Act as this saved login for this command only, instead of the active context. Run [`entire auth contexts`](/cli-reference/auth#auth-contexts) to list the names. |
| `--help`, `-h`   | Show help for `entire` or any subcommand                                                                                                                         |

```bash theme={null}
# Run one command as another saved login
entire --context staging activity
```

`--context` does not change the active context. To switch it persistently, use [`entire auth use`](/cli-reference/auth#auth-use).

## Version Flag

`--version` (`-v`) is available only on the root command. Use `entire --version` or [`entire version`](/cli-reference/version) to show build information.

## Environment Variables

| Variable         | Description                                                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACCESSIBLE`     | Set to any value to enable accessibility mode. Entire uses simpler text prompts instead of interactive terminal UI, which works better with screen readers. |
| `ENTIRE_CONTEXT` | Act as this saved login for a shell or a single Git operation. The environment-variable equivalent of `--context`.                                          |

```bash theme={null}
# Use a saved login for one Git operation
ENTIRE_CONTEXT=staging git push

# Use simpler static output for screen readers
ACCESSIBLE=1 entire activity
```

See [Logging and Diagnostics](/guides/configuration/logging-and-diagnostics) for the variables that control log level and diagnostics.


# grant
Source: https://docs.entire.io/cli-reference/grant

Manage Entire access grants and organization membership.

Manage Entire access grants and organization membership.

```bash theme={null}
entire grant COMMAND
```

Grants are managed at three levels: membership in an [organization](/cli-reference/org), access to a [project](/cli-reference/project), and access to a [repository](/cli-reference/repo).

A **grantee** is addressed as a provider-qualified handle, such as `github:alice`, or as an account ULID. Orgs, projects, and repositories are addressed by name or ULID.

Every subcommand except `remove` accepts `--json` to print raw JSON instead of a table. Under `grant repo`, every subcommand also accepts `--project PROJECT` (the owning project by name or ULID). This flag is required whenever `REPO` is a name.

<Note>
  Access to a [GitHub mirror](/guides/repositories/mirrors) follows GitHub collaborator permissions and syncs hourly, rather than being managed with `entire grant`. See [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions).
</Note>

## grant org

Manage organization membership.

### `entire grant org add`

Add a member to an org.

```bash theme={null}
entire grant org add ORG GRANTEE [flags]
```

| Flag          | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `--role ROLE` | Org role: `owner`, `admin`, or `member`. Defaults to `member`. |

```bash theme={null}
entire grant org add acme github:alice --role admin
```

### `entire grant org list`

List org members.

```bash theme={null}
entire grant org list ORG [flags]
```

### `entire grant org remove`

Remove a member from an org.

```bash theme={null}
entire grant org remove ORG GRANTEE
```

```bash theme={null}
entire grant org remove acme github:alice
```

## grant project

Manage project access.

### `entire grant project add`

Grant a user access to a project.

```bash theme={null}
entire grant project add PROJECT GRANTEE --role ROLE [flags]
```

| Flag          | Description                                             |
| ------------- | ------------------------------------------------------- |
| `--role ROLE` | Project role: `reader`, `writer`, or `admin`. Required. |

```bash theme={null}
entire grant project add widgets github:alice --role writer
```

### `entire grant project list`

List project members.

```bash theme={null}
entire grant project list PROJECT [flags]
```

### `entire grant project remove`

Revoke a grantee's access to a project.

```bash theme={null}
entire grant project remove PROJECT GRANTEE
```

```bash theme={null}
entire grant project remove widgets github:alice
```

## grant repo

Manage repository access.

### `entire grant repo add`

Grant a user access to a repository.

```bash theme={null}
entire grant repo add REPO GRANTEE --role ROLE [flags]
```

| Flag          | Description                                          |
| ------------- | ---------------------------------------------------- |
| `--role ROLE` | Repo role: `reader`, `writer`, or `admin`. Required. |

```bash theme={null}
entire grant repo add web github:alice --project acme --role writer
```

### `entire grant repo list`

List repository grants.

```bash theme={null}
entire grant repo list REPO [flags]
```

### `entire grant repo remove`

Revoke a grantee's access to a repository.

```bash theme={null}
entire grant repo remove REPO GRANTEE [flags]
```

```bash theme={null}
entire grant repo remove web github:alice --project acme
```

## Continue With

<CardGroup>
  <Card title="repo visibility" icon="eye" href="/cli-reference/repo#entire-repo-visibility-set">
    Make a repository readable by all authenticated Entire users.
  </Card>

  <Card title="Mirror Access and Permissions" icon="lock" href="/guides/repositories/mirror-access-and-permissions">
    Understand GitHub-synced access for mirrors.
  </Card>
</CardGroup>


# entire-graph
Source: https://docs.entire.io/cli-reference/graph

Search and analyze your codebase from the Entire CLI.

entire-graph is an installable [plugin](/cli-reference/plugin) for the [Entire CLI](/cli-reference) that gives your coding agent a map of your codebase. It helps your agent find the right code, understand how it connects, and see what a change could affect before it starts editing.

Install entire-graph before running `entire graph`:

```bash theme={null}
entire plugin install graph
```

Then run entire-graph commands with:

```bash theme={null}
entire graph COMMAND [flags]
```

Run `entire graph help` to see every command in your installed version, and `entire graph COMMAND --help` for command-specific flags.

Pass `--repo .` when you run these outside an Entire session.

## graph init-agents

Write `.entire/graph-agent.md` and add managed blocks to `AGENTS.md` and `CLAUDE.md`.

```bash theme={null}
entire graph init-agents [--repo PATH]
```

See [Install and Enable entire-graph](/guides/graph/set-up-graph) for the complete setup workflow.

## graph agent-guide

Print the coding-agent guide that `init-agents` installs.

```bash theme={null}
entire graph agent-guide
```

## graph index

Build a committed-tree cache before running a batch of `--head` queries. The default profile is `full`.

```bash theme={null}
entire graph index --repo . [flags]
```

## graph capabilities

Report supported languages, parsing coverage, relation types, and features as JSON.

```bash theme={null}
entire graph capabilities --json
```

## graph search

Return ranked source regions for a plain-language description of a task or bug.

```bash theme={null}
entire graph search --repo . --profile full --query "token refresh returns 401"
```

Search reads the working tree by default, so results include uncommitted changes. Use `--head` to search the committed tree instead.

Results fit within a byte budget. Top results include full function bodies, while later results may contain only locations. Use `--max-context-bytes` to change the total.

| Flag                                 | Description                                                                                                      |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `--query TEXT`                       | The task or bug in one plain sentence. Required.                                                                 |
| `--top-k N`                          | Number of results. Default is `10`.                                                                              |
| `--format text\|json\|ndjson\|agent` | Default is `json`. `text` is tiered for reading, `agent` is compact.                                             |
| `--profile syntax-only\|fast\|full`  | Parsing depth. Default is `fast`, but the installed agent guide asks for `full`, which activates the call graph. |
| `--deep`                             | Also run the exhaustive BM25 pass and fuse it in. Slower, and reads every eligible file.                         |
| `--head`                             | Search the committed tree instead of the working tree.                                                           |
| `--max-context-bytes N`              | Output byte budget. `0` removes the bound. Default is `24576`.                                                   |

Each result includes a `signals` array that explains why it ranked, such as `path`, `body`, `symbol-name`, or `graph:callers`.

## graph impact

Show callers, callees, type consumers, data flows, related files, and same-container symbols for one symbol.

```bash theme={null}
entire graph impact --repo . --symbol Router.Match
```

Impact reads the working tree by default. Use `--head` to inspect the committed tree instead.

```text theme={null}
Index: cache-hit (64ms) | Query: 0ms | Total: 64ms
Impact: Router.Match (mux.go:151) def=151 span=151-182 [method in Router]
Blast radius: 1 caller (1 direct, 0 transitive), 0 callees, 3 type consumers,
  1 data flow, 7 co-change files, 29 siblings.
Callers (1 direct, 0 transitive; who breaks if behavior changes):
- Router.ServeHTTP (mux.go:203, def :188)
```

| Flag                         | Description                               |
| ---------------------------- | ----------------------------------------- |
| `--symbol NAME\|FILE:LINE`   | Symbol to analyze. Required.              |
| `--depth 1\|2`               | Caller traversal depth. Default is `2`.   |
| `--limit N`                  | Max entries per section. Default is `15`. |
| `--exclude-tests`            | Drop test-only entries.                   |
| `--file`, `--line`, `--kind` | Disambiguate an ambiguous name.           |

Text output begins with `Index: cache-hit` or `Index: cache-miss`.

## graph neighbors

Show direct relationships for one symbol, filtered by relation and direction.

```bash theme={null}
entire graph neighbors --repo . --symbol validateToken --relation CALLS --direction in
```

Neighbors reads the working tree by default. Use `--head` to inspect the committed tree instead.

| Flag                        | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| `--symbol NAME\|FILE:LINE`  | Symbol to inspect. Required.                          |
| `--relation TYPE`           | Relation family to follow. Default is `CALLS`.        |
| `--direction both\|in\|out` | `in` is callers, `out` is callees. Default is `both`. |
| `--depth 1\|2`              | Hops to traverse. Default is `1`.                     |
| `--limit N`                 | Max neighbors per direction. Default is `20`.         |
| `--internal-only`           | Drop unresolved external endpoints.                   |

Text output begins with `Index: cache-hit` or `Index: cache-miss`.

## graph def

Show a symbol's declaration. For a type, include its fields, methods, and implementations.

```bash theme={null}
entire graph def RouteMatch --repo .
```

This command reads the working tree by default. Use `--head` to inspect the committed tree instead.

## graph explain

Read a build or test failure from standard input and append the declarations of the symbols it names.

```bash theme={null}
go test ./... 2>&1 | entire graph explain --repo .
```

Explain reads the working tree by default, so its declarations match the code that produced the failure. Use `--head` to inspect the committed tree instead.

## graph commit

List entity-level changes in a commit relative to its first parent, including added, removed, renamed, signature-changed, and body-changed symbols.

```bash theme={null}
entire graph commit [REV] [flags]
```

Each change includes an estimated dependent count.

## graph diff

List entity-level changes between two Git references. `analyze` is an alias for this command.

```bash theme={null}
entire graph diff --base BASE --head HEAD [flags]
```

## graph checkpoint

Analyze the commit associated with an [Entire checkpoint](/guides/sessions/overview#what-is-a-checkpoint).

```bash theme={null}
entire graph checkpoint CHECKPOINT_ID [flags]
```

## graph verify

Run a test command and report which tests changed state.

```bash theme={null}
entire graph verify --repo . --test "COMMAND" [flags]
```

<Warning>
  `entire graph verify` executes the command you give it, with your privileges. So does `--setup`. Pass only commands you would run yourself.
</Warning>

Record a baseline on a clean tree to distinguish existing failures from failures introduced by a change:

```bash theme={null}
entire graph verify --repo . --test "pytest tests/" --record-baseline /tmp/base.json
# make your edit
entire graph verify --repo . --test "pytest tests/" --pre-edit-baseline /tmp/base.json
```

## graph snapshot

Export the complete graph as NDJSON, including files, external endpoints, symbols, relations, and a summary.

```bash theme={null}
entire graph snapshot --repo . --format ndjson [flags]
```

Snapshot reads the committed tree by default. Use `--worktree` to include uncommitted changes. It also supports `--format compact-ndjson`.

## graph symbols

Export symbol records as NDJSON.

```bash theme={null}
entire graph symbols --repo . --format ndjson [flags]
```

Symbols reads the committed tree by default. Use `--worktree` to include uncommitted changes. Use `search` or `def` for targeted lookups because this command does not filter by name.

## graph edges

Export relation records as NDJSON. Filter the output with `--to`, `--from`, and `--relation`.

```bash theme={null}
entire graph edges --repo . --format ndjson [flags]
```

Edges reads the committed tree by default. Use `--worktree` to include uncommitted changes.

## graph snapshot-query

Query a saved compact snapshot without rebuilding the graph.

```bash theme={null}
entire graph snapshot --repo . --format compact-ndjson > graph.compact.ndjson
entire graph snapshot-query --input graph.compact.ndjson --symbol Cache.Refresh
```

## graph doctor

Report the resolved repository, Entire environment variables, plugin data directory access, and whether network access is disabled.

```bash theme={null}
entire graph doctor [--json]
```

`doctor --assert` is a preflight. It parses a command line against your installed binary and tells you whether it would be rejected, without running anything:

```bash theme={null}
entire graph doctor --assert "search --profile full --top-k 10 --format text"
```

## graph version

Print the installed entire-graph plugin version. Add `--json` to include the provider name.

```bash theme={null}
entire graph version [--json]
```

## graph stats

Compare entire-graph usage with grep and file reads in local coding-agent transcripts, including an estimated token saving.

```bash theme={null}
entire graph stats [flags]
```

<Note>
  `stats` reads local coding-agent session transcripts from disk. It is for humans, not part of the agent workflow, and the installed guide tells agents not to run it unless asked.
</Note>

## Continue with

<CardGroup>
  <Card title="Use entire-graph with Your Coding Agent" icon="robot" href="/guides/graph/use-graph">
    Learn what to ask and what happens after you prompt your agent.
  </Card>

  <Card title="Install and Enable entire-graph" icon="wrench" href="/guides/graph/set-up-graph">
    Install the plugin and turn it on for a repository.
  </Card>

  <Card title="entire-graph Troubleshooting" icon="stethoscope" href="/guides/graph/troubleshooting">
    Fix install, adoption, and cache problems.
  </Card>

  <Card title="entire-graph Overview" icon="chart-network" href="/guides/graph/overview">
    Understand what entire-graph is for.
  </Card>

  <Card title="entire-graph Repository" icon="github" href="https://github.com/entireio/entire-graph">
    Browse the source and the full reference docs.
  </Card>
</CardGroup>


# help
Source: https://docs.entire.io/cli-reference/help

Display help information about any command.

Display help information about any command.

```bash theme={null}
entire help [COMMAND]
```

| Argument  | Description                            |
| --------- | -------------------------------------- |
| `command` | Optional. The command to get help for. |

```bash theme={null}
# Show general help
entire help

# Get help for a specific command
entire help enable
entire enable --help
```

## Print the Command Tree

Pass `-t` to print every command and subcommand as a tree, with its one-line description:

```bash theme={null}
entire help -t
```

```text theme={null}
entire
├── activity - Show your activity overview
├── agent - Manage agent integrations (add, remove, list)
│   ├── add - Install hooks for an agent
│   ├── list - List installed and available agents
│   └── remove - Uninstall hooks for an agent
...
```

<Note>
  For output aimed at coding agents rather than people, use [`entire agent-help`](/cli-reference/agent-help), which generates its command map from the installed binary and supports `--json`.
</Note>


# import
Source: https://docs.entire.io/cli-reference/import

Import pre-existing local agent transcripts as read-only checkpoints.

Import pre-existing local agent transcripts for the current repository as read-only checkpoints.

```bash theme={null}
entire import AGENT [flags]
```

<Note>
  `entire import` is experimental. It appears under **Experimental commands** in developer and nightly builds, but is hidden from top-level help in stable releases. It remains runnable in all builds and appears in [`entire labs`](/cli-reference/labs). Run `entire import --help` to see supported agents.
</Note>

## Supported Agents

| Agent       | Command                         |
| ----------- | ------------------------------- |
| Claude Code | `entire import claude-code`     |
| Codex       | `entire import codex`           |
| Copilot CLI | `entire import copilot-cli`     |
| Cursor      | `entire import cursor`          |
| Factory     | `entire import factoryai-droid` |
| Gemini CLI  | `entire import gemini`          |
| Pi          | `entire import pi`              |

## Flags

| Flag               | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `--dry-run`        | Report what would be imported without writing checkpoints |
| `--path DIRECTORY` | Override the transcript directory to import from          |
| `--session ID`     | Import only this session ID. Repeatable.                  |

## Examples

Check what would be imported:

```bash theme={null}
entire import claude-code --dry-run
```

Import Claude Code transcript history:

```bash theme={null}
entire import claude-code
```

Import a specific Codex session:

```bash theme={null}
entire import codex --session SESSION_ID
```

Import from a custom transcript directory:

```bash theme={null}
entire import claude-code --path TRANSCRIPT_DIRECTORY
```

## Behavior

`entire import` scans the agent's local transcript store for the current repository and imports history from the past month.

Import honors [checkpoint policy](/cli-reference/checkpoint#checkpoint-policy) before it scans transcripts. If the configured `checkpoint_version` or `checkpoint_min_version` is unsupported by your CLI, import fails, including under `--dry-run`.

Imported checkpoints are:

* read-only
* searchable
* explainable
* idempotent, so already-imported turns are skipped
* not rewindable
* not linked to a Git commit

## Continue With

<CardGroup>
  <Card title="Import Past Sessions" icon="terminal" href="/guides/sessions/import-past-agent-history">
    Follow the guide for importing past local agent sessions.
  </Card>

  <Card title="Search" icon="sparkles" href="/cli-reference/search">
    Search imported checkpoints and other Entire history.
  </Card>
</CardGroup>


# investigate
Source: https://docs.entire.io/cli-reference/investigate

Run a multi-agent investigation from a prompt, seed document, issue, or PR.

Run a multi-agent investigation. Agents take turns appending findings, evidence, and analysis to a shared findings document until quorum is reached.

```bash theme={null}
entire investigate [SEED_DOC] [flags]
entire investigate SUBCOMMAND
```

`entire investigate` is experimental and appears under labs while the workflow is still being refined.

## Inputs

Use one of these inputs:

| Input              | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `SEED_DOC`         | Path to a starting findings file                       |
| `--issue-link URL` | GitHub issue or pull request URL resolved through `gh` |

When neither input is supplied and the multi-agent picker opens, the picker collects an investigation prompt that becomes the topic for the run.

## Flags

| Flag                     | Description                                                                                                       |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `--agents AGENTS`        | Override configured agents with a comma-separated list                                                            |
| `--max-turns N`          | Per-agent turn budget. Defaults to `2`.                                                                           |
| `--quorum N`             | Approvals needed to terminate. `0` means all agents.                                                              |
| `--continue RUN_ID`      | Resume an existing run                                                                                            |
| `--edit`                 | Re-open the investigate config picker                                                                             |
| `--findings`             | Browse local investigation manifests                                                                              |
| `--allow-untrusted-seed` | Required for non-interactive `--issue-link` investigations because the seed is attacker-influenced GitHub content |

## Subcommands

| Subcommand     | Description                                                                  |
| -------------- | ---------------------------------------------------------------------------- |
| `show RUN_ID`  | Print a saved investigation's summary and findings                           |
| `fix RUN_ID`   | Launch a coding agent with the run's findings as grounded context            |
| `clean RUN_ID` | Delete a saved investigation. Add `--force` to skip the confirmation prompt. |
| `clean --all`  | Delete all saved investigation artifacts                                     |

## Examples

```bash theme={null}
entire investigate leaderboard-route-investigation.md --max-turns 1
entire investigate --findings
entire investigate show RUN_ID
entire investigate fix RUN_ID
entire investigate clean RUN_ID
```

## Continue With

<CardGroup>
  <Card title="Investigate Why Code Exists" icon="search-code" href="/learn/investigate-why-code-exists">
    Walk through a complete provenance investigation.
  </Card>

  <Card title="labs" icon="flask-conical" href="/cli-reference/labs">
    See experimental Entire workflows.
  </Card>
</CardGroup>


# labs
Source: https://docs.entire.io/cli-reference/labs

Explore experimental Entire workflows.

Explore experimental Entire workflows.

```bash theme={null}
entire labs
```

This command lists newer Entire workflows that are available to try while they are still being refined. Use it to discover experimental commands and see where to find their command-specific help. The set changes as workflows graduate, so run `entire labs` for what your installed CLI offers.

| Command                                                          | Purpose                                                             |
| ---------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`entire review`](/cli-reference/review)                         | Run a multi-agent review against a branch                           |
| [`entire investigate`](/cli-reference/investigate)               | Run a multi-agent investigation against a topic, issue, or seed doc |
| [`entire import claude-code`](/cli-reference/import)             | Import existing Claude Code transcripts as local, read-only history |
| [`entire tokens`](/cli-reference/tokens)                         | Analyze token usage diagnostics                                     |
| [`entire tokens profile`](/cli-reference/tokens#tokens-profile)  | Aggregate token usage across committed checkpoints                  |
| [`entire session tokens`](/cli-reference/session#session-tokens) | Show token usage and recommendations for a session                  |
| [`entire blame`](/cli-reference/blame)                           | Show which lines came from Entire checkpoints                       |
| [`entire why`](/cli-reference/why)                               | Show why a line exists                                              |
| [`entire experts`](/cli-reference/experts)                       | Show agent, Skill, and tool provenance for files or topics          |

```bash theme={null}
# List experimental workflows
entire labs

# Open help for one of them
entire review --help
```

<Note>
  `entire labs` is a discovery command. It does not run the listed workflows as nested subcommands. For example, use `entire review --help`, not `entire labs review --help`.
</Note>


# login
Source: https://docs.entire.io/cli-reference/login

Log in to Entire.

Log in to Entire.

```bash theme={null}
entire login [flags]
```

By default this opens a browser redirect flow. If Entire is running interactively, it prompts before opening the approval URL automatically. In non-interactive environments, it prints the approval URL so you can open it manually.

Use `--device` when a browser redirect is not practical, such as on a remote host or in a container. The device-code flow prints a code and asks you to enter it in a browser on another machine.

| Flag           | Description                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--device`     | Use the device-code flow, entering a code in your browser, instead of the default browser redirect.                                  |
| `--server URL` | Login server to authenticate against. Rarely needed; the default serves all standard accounts. Defaults to `https://auth.entire.io`. |

```bash theme={null}
# Device-code flow, for a remote host or container
entire login --device
```

<Note>
  A completed login is saved as a [context](/cli-reference/auth#login-contexts): a named pairing of login server and identity, with its tokens in your operating system's credential store. Logging in again as the same identity updates that context in place. Run [`entire auth contexts`](/cli-reference/auth#auth-contexts) to see them all.
</Note>


# logout
Source: https://docs.entire.io/cli-reference/logout

Log out of Entire.

Log out of Entire.

```bash theme={null}
entire logout [flags]
```

By default, this revokes the active session and removes its saved login from this machine. Other saved [contexts](/cli-reference/auth#login-contexts) remain available. The next saved context becomes active.

| Flag             | Description                                                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--all-contexts` | Log out of every saved context at once. Each context's session is revoked server-side and its login is removed from this machine. |
| `--everywhere`   | Revoke every session on the login server, across all your devices, not just the current one.                                      |

```bash theme={null}
# Revoke every session on every context's login server
entire logout --all-contexts --everywhere
```


# org
Source: https://docs.entire.io/cli-reference/org

Manage Entire organizations.

Manage Entire organizations.

```bash theme={null}
entire org COMMAND
```

An organization owns [projects](/cli-reference/project), which in turn own [repositories](/cli-reference/repo). To manage who belongs to an org, use [`entire grant org`](/cli-reference/grant#grant-org).

Use an organization's name or ULID with `get` and `delete`. Every subcommand except `delete` accepts `--json` to print raw JSON instead of a table.

## `entire org create`

Create an organization.

```bash theme={null}
entire org create NAME [flags]
```

| Flag            | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| `--region SLUG` | Jurisdiction slug. Defaults to the server's home jurisdiction. |

```bash theme={null}
entire org create acme
entire org create acme --region eu
```

## `entire org list`

List organizations you can see.

```bash theme={null}
entire org list [flags]
```

## `entire org get`

Show an organization by name or ULID.

```bash theme={null}
entire org get ORG [flags]
```

## `entire org delete`

Delete an organization by name or ULID.

```bash theme={null}
entire org delete ORG [flags]
```

| Flag          | Description                                        |
| ------------- | -------------------------------------------------- |
| `-f, --force` | Skip the confirmation prompt.                      |
| `-y, --yes`   | Skip the confirmation prompt. Alias for `--force`. |

## Continue With

<CardGroup>
  <Card title="project" icon="folder" href="/cli-reference/project">
    Create and manage the projects an org owns.
  </Card>

  <Card title="grant" icon="key" href="/cli-reference/grant">
    Manage org membership and access.
  </Card>
</CardGroup>


# plugin
Source: https://docs.entire.io/cli-reference/plugin

Discover, install, inspect, update, and troubleshoot commands that extend the Entire CLI.

CLI plugins are executables named `entire-<name>` that add commands to Entire. For example, an executable named `entire-graph` runs when you enter `entire graph`. This system is separate from the [Agent Integration Protocol](/agents/agent-integration-protocol/overview), which uses `entire-agent-<name>` executables to integrate coding agents.

```bash theme={null}
entire plugin COMMAND
```

<Warning>
  A CLI plugin is a native executable that runs with your user account's filesystem, network, and process permissions. Entire filters the environment passed to plugins, but it does not sandbox them. Install plugins only from sources you trust.
</Warning>

## Command Tree

| Command                                 | Purpose                                                                                 |
| --------------------------------------- | --------------------------------------------------------------------------------------- |
| `entire plugin browse`                  | Interactively browse the plugin index and install a selection.                          |
| `entire plugin doctor`                  | Check managed plugins for broken entries, integrity problems, and missing dependencies. |
| `entire plugin index update`            | Force a refresh of the synced plugin index.                                             |
| `entire plugin info NAME`               | Show index and install details for a plugin.                                            |
| `entire plugin install NAME\|URL\|PATH` | Install from the index, a repository, or a local executable.                            |
| `entire plugin list`                    | List plugins installed in the managed directory.                                        |
| `entire plugin remove NAME`             | Remove a managed plugin.                                                                |
| `entire plugin search [TERM]`           | Search the plugin index.                                                                |
| `entire plugin upgrade [NAME]`          | Upgrade one or all plugins installed from remote repositories.                          |

## Discovery and Precedence

When you run a command such as `entire graph build`, Entire:

1. Checks whether `graph` is a command included with Entire.
2. Looks for an executable named `entire-graph` on `$PATH`.
3. Runs that executable with `build` as its argument and passes stdin, stdout, stderr, and its exit code through unchanged.

Commands included with Entire take precedence. If you install `entire-version`, for example, `entire version` still runs the command included with Entire.

Entire temporarily prepends the managed plugin directory to `$PATH` during plugin discovery. Therefore, a managed plugin takes precedence over an `entire-<name>` executable with the same name elsewhere on your shell's `$PATH`. Entire keeps the managed directory on `$PATH` while a plugin runs so it can invoke other managed plugins.

Entire reserves names beginning with `entire-agent-` for agent integrations and does not dispatch them as CLI commands. Follow the [Agent Integration Protocol](/agents/agent-integration-protocol/overview) to build or install one.

### Run an Unmanaged Plugin

You do not need `entire plugin install` to run a plugin. Make the binary executable and place it anywhere on your `$PATH`:

```bash theme={null}
chmod +x /path/to/entire-example
entire example --help
```

Unmanaged plugins do not appear in `entire plugin list`. `entire plugin upgrade` does not update them, and you must remove them from `$PATH` manually.

## Managed Directory

`entire plugin install` uses the first managed root that applies:

| Environment     | Managed Root                                                         |
| --------------- | -------------------------------------------------------------------- |
| Override        | `$ENTIRE_PLUGIN_DIR`                                                 |
| Linux and macOS | `$XDG_DATA_HOME/entire/plugins`, or `~/.local/share/entire/plugins`  |
| Windows         | `%LOCALAPPDATA%\entire\plugins`, or `~\AppData\Local\entire\plugins` |

`ENTIRE_PLUGIN_DIR` must be an absolute path. Under the root, Entire uses this layout:

```text theme={null}
<managed-root>/
├── bin/                    # Executables discovered as entire-<name>
├── data/<name>/            # Durable storage available to the plugin
└── pkg/<name>/
    ├── entire-<name>       # Binary from a remote install
    └── manifest.yml        # Version, source, checksum, and dependencies
```

Remote installs store the downloaded binary and its provenance under `pkg/`, then link the binary into `bin/`. Local path installs link the source executable directly into `bin/`, so rebuilding the source normally updates the command immediately. When symbolic links are unavailable, Entire falls back to a hard link and then a copy.

Each plugin receives:

| Variable                 | Value                                                                            |
| ------------------------ | -------------------------------------------------------------------------------- |
| `ENTIRE_CLI_VERSION`     | The version of the Entire CLI that launched it.                                  |
| `ENTIRE_REPO_ROOT`       | The repository root, when the command runs inside a repository.                  |
| `ENTIRE_PLUGIN_DATA_DIR` | The plugin's durable `data/<name>` directory. The plugin creates it when needed. |

Entire passes common operating system, terminal, locale, CI, proxy, SSH agent, `ENTIRE_*`, `LC_*`, and `XDG_*` variables. Entire excludes other variables by default to reduce accidental credential exposure. You can explicitly pass additional names or prefixes with `ENTIRE_PLUGIN_ENV`, for example:

```bash theme={null}
ENTIRE_PLUGIN_ENV='AWS_*,GH_TOKEN' entire example
```

This filtering is defense in depth, not a security boundary: a malicious plugin can still read files and credentials available to your user account.

## Install a Plugin

Install a plugin from the synced index, a git repository URL, or a local executable.

```bash theme={null}
entire plugin install NAME|URL|PATH [flags]
```

| Source         | Example                                                        | Behavior                                                                                     |
| -------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Index name     | `entire plugin install run`                                    | Resolves the name through the synced plugin index.                                           |
| Repository URL | `entire plugin install https://github.com/entireio/entire-run` | Resolves a release from the repository. A URL not listed in the index requires confirmation. |
| Local path     | `entire plugin install ./dist/entire-run`                      | Links an existing executable into the managed directory.                                     |

Local paths must be explicit: include a directory separator or begin with `./`. The executable's basename must be `entire-<name>` so Entire can derive the command name.

For a remote install, Entire:

1. Uses the tag supplied with `--pin`, or tries the newest stable semantic version tag. Without `--pin`, Entire tries up to two older stable tags when newer tags lack a compatible release asset.
2. Reads `entire-plugin.yml` from that tag when the repository provides it.
3. Downloads the matching release asset over HTTPS.
4. Verifies the asset against the release's checksum manifest.
5. Stores the binary and install manifest in the managed directory.
6. Resolves and offers to install declared dependencies.

Installing from a URL that is not in the plugin index asks for confirmation. Pass `--yes` to skip the prompt; a run without a terminal requires this flag for an unlisted URL.

### Checksum Verification

Remote installation looks for `checksums.txt` or a supported plugin checksum filename in the release. When the manifest covers the release asset, Entire computes its SHA-256 digest and refuses the install if it does not match. Entire also records a digest of the installed binary so `entire plugin doctor` can detect later changes.

If the release asset has no published checksum covering your platform, installation stops. `--allow-unverified` bypasses that requirement and records the install as unverified; `plugin doctor` continues to report it. Future upgrades preserve the original choice: a verified install cannot silently become unverified, while an unverified install remains allowed to upgrade without a new flag.

<Warning>
  A matching checksum proves that the downloaded bytes match the checksum published with that release. It does not prove that the repository owner, release process, or plugin code is trustworthy. Use `--allow-unverified` only after you have independently decided to trust the source and accept that the download is not authenticated by a published checksum.
</Warning>

### Dependencies

A plugin repository can declare runtime dependencies in `entire-plugin.yml`:

```yaml theme={null}
name: example
description: Example Entire CLI plugin
requires:
  - name: graph
    min_version: v0.4.0
```

`min_version` accepts an optional minimum semantic version. Entire does not support version ranges. Entire resolves dependencies by name through the plugin index, including transitive dependencies. A plugin author cannot supply a dependency repository URL in `entire-plugin.yml`.

Entire shows the dependencies it plans to install or upgrade and asks once for confirmation. Use `--yes` in a run without a terminal or `--no-deps` to install only the requested plugin. If a dependency already comes from a local path or your shell's `$PATH`, Entire treats it as present but cannot verify its minimum version. Run `entire plugin doctor` to inspect the resulting state.

| Flag                 | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `--allow-unverified` | Install when no published checksum covers the release asset.     |
| `--force`            | Replace an existing managed entry with the same name.            |
| `--index URL`        | Use a different plugin index for this command.                   |
| `--no-deps`          | Do not install declared dependencies.                            |
| `--pin TAG`          | Install exactly this tag and skip the plugin during upgrades.    |
| `--yes`              | Skip confirmation prompts for unlisted sources and dependencies. |

## List Managed Plugins

List plugins installed in the managed directory.

```bash theme={null}
entire plugin list
```

```text theme={null}
Managed plugin directory: /Users/you/.local/share/entire/plugins/bin

  run                  v0.1.0             → /Users/you/.local/share/entire/plugins/pkg/run/entire-run
```

This command does not list unmanaged `entire-<name>` executables elsewhere on `$PATH`.

## Search the Plugin Index

Search the synced plugin index. Run the command without a term to list everything available. A `*` marks a managed plugin that is already installed.

```bash theme={null}
entire plugin search [TERM] [flags]
```

```text theme={null}
* run                  Launch one of the agents enabled for Entire in the current repository [official]
  upgrade              Upgrade the system-installed Entire binary [official]
```

Entire caches the Git repository that contains the index. On the next index operation after the cached copy is 24 hours old, Entire attempts a refresh. If a refresh fails while you are offline, Entire uses the existing cached copy. The index URL resolves in this order: `--index`, `ENTIRE_PLUGIN_INDEX_URL`, then Entire's default index.

| Flag          | Description                                    |
| ------------- | ---------------------------------------------- |
| `--index URL` | Use a different plugin index for this command. |

## Inspect a Plugin

Show index metadata and managed install details for a plugin, including its repository, version, pin, and dependencies.

```bash theme={null}
entire plugin info NAME [flags]
```

```text theme={null}
Name:        run
Description: Launch one of the agents enabled for Entire in the current repository
Repository:  https://github.com/entireio/entire-run
Official:    true
Installed:   v0.1.0 (from https://github.com/entireio/entire-run)
```

| Flag          | Description                                    |
| ------------- | ---------------------------------------------- |
| `--index URL` | Use a different plugin index for this command. |

## Browse the Plugin Index

Browse the plugin index in an interactive picker and install a selection.

```bash theme={null}
entire plugin browse [flags]
```

The picker shows each plugin's name and description. Before downloading anything, Entire shows the repository that provides the binary and asks you to confirm.

<Note>
  This command needs a terminal. Use `entire plugin search` and `entire plugin install NAME` in scripts and runs without a terminal.
</Note>

| Flag          | Description                                    |
| ------------- | ---------------------------------------------- |
| `--index URL` | Use a different plugin index for this command. |

## Upgrade Plugins

Upgrade one plugin installed from a remote repository, or use `--all` to upgrade every eligible plugin. Entire tries the newest stable semantic version first and uses the same release asset fallback as installation.

```bash theme={null}
entire plugin upgrade NAME
entire plugin upgrade --all
```

Entire cannot upgrade local path installs because they have no remote install manifest. Pinned plugins stay at their selected version until you reinstall them without `--pin`.

| Flag    | Description                                                       |
| ------- | ----------------------------------------------------------------- |
| `--all` | Upgrade every eligible plugin installed from a remote repository. |

## Remove a Plugin

Remove a plugin from the managed directory.

```bash theme={null}
entire plugin remove NAME [flags]
```

If another managed plugin declares the target as a dependency, Entire refuses removal unless you pass `--force`. This command does not remove unmanaged executables elsewhere on `$PATH`.

| Flag      | Description                                                   |
| --------- | ------------------------------------------------------------- |
| `--force` | Remove a plugin even when other managed plugins depend on it. |

## Diagnose Plugin Problems

Check managed plugins for:

* broken managed entries
* dangling links to local paths
* missing or outdated dependencies
* unverified installs
* changes to a binary installed from a remote repository
* the macOS quarantine attribute

```bash theme={null}
entire plugin doctor
```

```text theme={null}
All plugins healthy.
```

The command prints a suggested fix for each actionable problem and exits unsuccessfully when it finds issues.

## Update the Plugin Index

Force a refresh of the plugin index from its Git repository.

```bash theme={null}
entire plugin index update [flags]
```

Use this command when `plugin search` does not show a newly published plugin or when you need to refresh the index before the cached copy becomes stale.

| Flag          | Description                       |
| ------------- | --------------------------------- |
| `--index URL` | Refresh a different plugin index. |

## Troubleshooting

### `entire NAME` Reports an Unknown Command

1. Confirm the executable is named `entire-NAME`, including the `entire-` prefix.
2. Run `entire plugin list` for a managed install.
3. For an unmanaged install, run `command -v entire-NAME` on Linux or macOS, or `where entire-NAME` on Windows.
4. On Linux or macOS, make the file executable with `chmod +x /path/to/entire-NAME`.
5. Run `entire plugin doctor` to check managed entries.

### The Wrong Copy Runs

Entire prepends the managed `bin/` directory during discovery, so it wins over matching executables elsewhere on `$PATH`. Run `entire plugin list` to see the managed entry. Remove it with `entire plugin remove NAME` if you intend to use the copy from your shell's `$PATH`.

If the name matches a command included with Entire, Entire runs that command. Rename the plugin executable and invoke it under the new name.

### A Plugin Is Missing from Search

Refresh and search the index:

```bash theme={null}
entire plugin index update
entire plugin search NAME
```

If the plugin is not indexed, install its repository URL directly. Review the repository before accepting the unlisted source prompt.

### Installation Needs a Terminal

An unlisted repository URL and dependency installation require confirmation. In CI or another environment without a terminal, review the source and its `entire-plugin.yml` dependencies first, then add `--yes`.

### Checksum Verification Fails

Do not bypass a checksum mismatch. A mismatch means the downloaded asset differs from the published digest. If no checksum covers your platform, ask the plugin author to publish one. `--allow-unverified` is an explicit choice for a missing checksum, not a remedy for a mismatch.

### A Local Plugin Does Not Update

Local installs use a symbolic link when the platform allows it, so rebuilding the source updates the command. On systems that require the hard link or copy fallback, reinstall with `--force` after rebuilding:

```bash theme={null}
entire plugin install ./dist/entire-example --force
```

### Dependencies Are Missing or Outdated

Run `entire plugin doctor` and follow its suggested install or upgrade commands. Reinstall the parent plugin without `--no-deps` if you want Entire to plan the transitive dependency set again.


# project
Source: https://docs.entire.io/cli-reference/project

Manage Entire projects.

Manage Entire projects.

```bash theme={null}
entire project COMMAND
```

A project is owned by an [organization](/cli-reference/org) or by an account, and in turn owns [repositories](/cli-reference/repo). To manage who can reach a project, use [`entire grant project`](/cli-reference/grant#grant-project).

Use a project's name or ULID with `get` and `delete`. Every subcommand except `delete` accepts `--json` to print raw JSON instead of a table.

## `entire project create`

Create a project owned by an org or an account.

```bash theme={null}
entire project create NAME --owner OWNER [flags]
```

`--owner` names the owning org (by name or ULID) or account (as `github:handle`, or by ULID). `--owner-type` selects which of the two you mean.

| Flag                | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `--owner OWNER`     | Owning org (name or ULID), or account (`github:handle` or ULID). Required. |
| `--owner-type TYPE` | Owner kind: `org` or `account`. Defaults to `org`.                         |
| `--region SLUG`     | Jurisdiction slug. Defaults to the server's home jurisdiction.             |

```bash theme={null}
# Project under an org, by name
entire project create widgets --owner acme --owner-type org

# Project owned by an account, by handle
entire project create widgets --owner github:alice --owner-type account
```

## `entire project list`

List projects you can see.

```bash theme={null}
entire project list [flags]
```

| Flag          | Description                                       |
| ------------- | ------------------------------------------------- |
| `--name NAME` | Filter by exact project name.                     |
| `--org ORG`   | List projects owned by this org, by name or ULID. |

## `entire project get`

Show a project by name or ULID.

```bash theme={null}
entire project get PROJECT [flags]
```

## `entire project delete`

Delete a project by name or ULID.

```bash theme={null}
entire project delete PROJECT [flags]
```

| Flag          | Description                                        |
| ------------- | -------------------------------------------------- |
| `-f, --force` | Skip the confirmation prompt.                      |
| `-y, --yes`   | Skip the confirmation prompt. Alias for `--force`. |

## Continue With

<CardGroup>
  <Card title="repo" icon="database" href="/cli-reference/repo">
    Create and manage the repositories a project owns.
  </Card>

  <Card title="grant" icon="key" href="/cli-reference/grant">
    Grant and revoke project access.
  </Card>
</CardGroup>


# recap
Source: https://docs.entire.io/cli-reference/recap

Summarize recent checkpoint activity.

Summarize recent checkpoint activity.

```bash theme={null}
entire recap [flags]
```

`entire recap` shows a time-based summary of agent and checkpoint activity. By default, it opens the interactive recap view for today.

Use `--static` when you want plain terminal output, such as in a script, transcript, or docs example:

```bash theme={null}
entire recap --static
```

## Time Windows

Choose the range you want to summarize:

```bash theme={null}
# Today only
entire recap --day

# Last 7 days
entire recap --week

# This calendar month
entire recap --month

# Rolling 90 days
entire recap --90
```

## Views

Limit recap to one agent:

```bash theme={null}
entire recap --agent codex
```

Choose which columns to show:

```bash theme={null}
entire recap --view you
entire recap --view team
entire recap --view both
```

## Flags

| Flag                   | Description                                                                 |
| ---------------------- | --------------------------------------------------------------------------- |
| `--90`                 | Show the rolling 90-day window.                                             |
| `--agent ID`           | Show activity for one agent, or use `all`. Defaults to `all`.               |
| `--color MODE`         | Set color output to `auto`, `always`, or `never`. Defaults to `auto`.       |
| `--day`                | Show today only. This is the default time window.                           |
| `--insecure-http-auth` | Allow plain HTTP auth. Local development only.                              |
| `--month`              | Show this calendar month.                                                   |
| `--static`             | Print static output instead of opening the interactive recap.               |
| `--view VIEW`          | Choose which columns to show: `you`, `team`, or `both`. Defaults to `both`. |
| `--week`               | Show the last 7 days.                                                       |
| `-h, --help`           | Show help for `entire recap`.                                               |

## Examples

```bash theme={null}
# Open the interactive recap for today
entire recap

# Print a static recap for today
entire recap --static

# Print the last 7 days without color
entire recap --week --static --color never

# Show only your activity
entire recap --view you

# Show one agent's activity
entire recap --agent codex --static
```


# repo
Source: https://docs.entire.io/cli-reference/repo

Manage Entire Repositories and GitHub mirror placements.

Manage Entire Repositories.

```bash theme={null}
entire repo COMMAND
```

## `entire repo create`

Create a repository in a project.

```bash theme={null}
entire repo create NAME [flags]
```

| Flag                     | Description                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------ |
| `--cluster-host HOST`    | Public host of the cluster to pin the repo to. Defaults to the jurisdiction default. |
| `--json`                 | Output raw JSON instead of a table.                                                  |
| `--object-format FORMAT` | Git object format: `sha1` or `sha256`. Defaults to the server default.               |
| `--project PROJECT`      | Owning project name or ULID. Required.                                               |

## `entire repo list`

List repositories in a project, addressed by name or ULID.

```bash theme={null}
entire repo list PROJECT [flags]
```

By default at most 1,000 repositories are fetched, and a note on standard error says so when the project has more. Rows come in server order; this list has no local filters or sort. With `--json`, a paged response wraps rows in an `{items, nextPageToken}` envelope.

| Flag                 | Description                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `--all`              | Fetch every repository instead of the first 1,000. Slower on large projects.                                        |
| `--json`             | Output raw JSON instead of a table.                                                                                 |
| `--limit N`          | Fetch and show only the first N repositories. `0` uses the default fetch budget.                                    |
| `--no-pager`         | Print directly to standard output instead of a pager.                                                               |
| `--page-size N`      | Fetch a single page of at most N entries, from 1 to 500, and print the resume cursor. The server may cap N further. |
| `--page-token TOKEN` | Fetch the single page at this cursor, from a previous run's `nextPageToken`.                                        |

## `entire repo get`

Show a repository by name or ULID.

```bash theme={null}
entire repo get REPO [flags]
```

| Flag                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--json`            | Output raw JSON instead of a table.                          |
| `--project PROJECT` | Owning project name or ULID. Required when `REPO` is a name. |

## `entire repo clone`

Clone an Entire-native repository, a GitHub mirror, or a full `entire://` clone URL.

```bash theme={null}
entire repo clone REPO [TARGET_DIR] [flags]
```

`REPO` takes one of three forms:

| Form                             | Behavior                                                                                                                                                                                                                |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/et/PROJECT/REPO`               | An Entire-native repository. Entire resolves its home cluster and clones from there. `--cluster` does not apply.                                                                                                        |
| `/gh/OWNER/REPO`                 | A GitHub mirror. Entire looks up where the repository is mirrored. With one placement, it clones directly. With several, an interactive terminal prompts you to choose, and a non-interactive run requires `--cluster`. |
| `entire://CLUSTER/gh/OWNER/REPO` | A full clone URL, which already names the cluster. Entire passes it straight to `git clone` with no lookup, and `--cluster` is ignored.                                                                                 |

The optional `TARGET_DIR` is passed through to `git clone` in every case.

Examples:

```bash theme={null}
entire repo clone /et/my-project/example
entire repo clone /gh/octocat/hello-world
entire repo clone /gh/octocat/hello-world ./hello-world
entire repo clone /gh/octocat/hello-world --cluster aws-us-east-2.entire.io
entire repo clone entire://aws-us-east-2.entire.io/gh/octocat/hello-world
```

| Flag             | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `--cluster HOST` | Cluster to use when the repository has several placements. |

## `entire repo delete`

Delete a repository by name or ULID.

```bash theme={null}
entire repo delete REPO [flags]
```

| Flag                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `-f, --force`       | Skip the confirmation prompt.                                |
| `--project PROJECT` | Owning project name or ULID. Required when `REPO` is a name. |
| `-y, --yes`         | Skip the confirmation prompt. Alias for `--force`.           |

## `entire repo mirror create`

Create a mirror placement for an existing GitHub repository.

```bash theme={null}
entire repo mirror create [GITHUB_URL] [CLUSTER_HOST] [flags]
```

With no arguments, `entire repo mirror create` opens an interactive wizard to choose repositories and regions.

With a GitHub URL, the command registers a mirror for that repository on the target cluster, then waits for the initial GitHub-to-Entire clone to finish. If you omit the cluster, an interactive terminal prompts when several clusters are available. A non-interactive run defaults to `aws-us-east-2.entire.io`.

Examples:

```bash theme={null}
entire repo mirror create
entire repo mirror create github.com/octocat/hello-world
entire repo mirror create github.com/octocat/hello-world aws-us-east-2.entire.io
```

| Flag                      | Description                                                                                                                                                                               |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--no-wait`               | Return once the mirror is registered, without waiting for the initial clone.                                                                                                              |
| `--wait-timeout DURATION` | How long to wait. Defaults to `30m0s`. Asynchronous mode applies one deadline to request submission, placement, and clone readiness; synchronous mode applies it only to clone readiness. |

Mirror creation uses the asynchronous request route by default. Set `async_mirror_requests` to `false` in your Entire settings to use the synchronous route.

## `entire repo mirror list`

List existing mirrors and GitHub repositories that you can onboard.

```bash theme={null}
entire repo mirror list [flags]
```

Existing mirrors appear once per repository, with their clusters and status. Available GitHub repositories show access and availability instead of placement details. Use `entire repo mirror get OWNER/REPO` for per-cluster clone URLs.

| Flag                 | Description                                                            |
| -------------------- | ---------------------------------------------------------------------- |
| `--access ACCESS`    | Filter available repositories by `read`, `write`, or `admin`.          |
| `--all`              | Fetch the complete directory instead of the first 1,000 entries.       |
| `--available`        | Show GitHub repositories that can be onboarded.                        |
| `--cluster CLUSTER`  | Show repositories mirrored on a cluster slug or public host.           |
| `--json`             | Output raw JSON instead of a table.                                    |
| `--limit N`          | Show at most `N` rows after filters and sorting.                       |
| `--mirrored`         | Show repositories with mirror placements.                              |
| `--name NAME`        | Filter the `owner/repo` name, case-insensitively.                      |
| `--no-pager`         | Print directly to standard output.                                     |
| `--owner OWNER`      | Filter by upstream owner.                                              |
| `--page-size N`      | Fetch one page of `N` entries, from 1 to 500.                          |
| `--page-token TOKEN` | Fetch one page from a previous response cursor.                        |
| `--private[=false]`  | Show private repositories, or public repositories when set to `false`. |
| `--sort KEY`         | Sort by a column key. Prefix the key with `-` for descending order.    |
| `--status STATUS`    | Filter by mirror or onboarding status.                                 |

## `entire repo mirror get`

Show a mirror placement or every placement for a repository.

```bash theme={null}
entire repo mirror get MIRROR [flags]
```

`MIRROR` can be an `owner/repo` name, a mirror ULID, or a full `entire://` clone URL. An `owner/repo` name shows the repository's visibility and access, followed by each cluster, clone URL, and status.

Examples:

```bash theme={null}
entire repo mirror get octocat/hello-world
entire repo mirror get 01KS6KFJR2XS6PZ188MVYE07AN
entire repo mirror get entire://aws-us-east-2.entire.io/gh/octocat/hello-world
```

| Flag     | Description                         |
| -------- | ----------------------------------- |
| `--json` | Output raw JSON instead of a table. |

## `entire repo mirror use`

Point a remote in the current checkout at an Entire mirror.

```bash theme={null}
entire repo mirror use [GITHUB_URL] [CLUSTER_HOST] [flags]
```

With no arguments, the command resolves the repository from `origin`. With one placement, Entire selects it directly. With several, an interactive terminal prompts you to choose, while a non-interactive run requires `--cluster`. In an interactive terminal, the command then asks whether to repoint `origin` or add a separate remote.

When Entire repoints `origin`, it preserves the previous URL as `upstream` if that remote name is available. If `upstream` already exists, Entire leaves it unchanged and warns that it did not save the previous URL. Choose another name with `--upstream NAME`.

In a non-interactive run, the command repoints `origin` unless you select another remote. It only edits local Git configuration and requires an existing mirror placement.

Examples:

```bash theme={null}
entire repo mirror use
entire repo mirror use --cluster aws-us-east-2.entire.io
entire repo mirror use github.com/octocat/hello-world
entire repo mirror use --remote entire
entire repo mirror use --upstream ''
```

| Flag              | Description                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `--cluster HOST`  | Cluster to use when the repository has several placements.                                   |
| `--remote NAME`   | Remote to point at the mirror. Defaults to `origin`.                                         |
| `--upstream NAME` | Remote name for the replaced URL. Defaults to `upstream`; pass an empty value to discard it. |

## `entire repo mirror remove`

Remove a mirror placement for a GitHub repository from the target cluster.

```bash theme={null}
entire repo mirror remove GITHUB_URL [CLUSTER_HOST] [flags]
```

The default cluster host is `aws-us-east-2.entire.io`. Removing a mirror placement does not delete or rewrite the upstream GitHub repository.

Example:

```bash theme={null}
entire repo mirror remove github.com/octocat/hello-world
```

## `entire repo mirror collaborators list`

List users with access to a mirror.

```bash theme={null}
entire repo mirror collaborators list GITHUB_URL [CLUSTER_HOST] [flags]
```

This command is read-only. Mirror access follows GitHub collaborator permissions and syncs hourly. The caller must be a live GitHub admin of the upstream organization repository, or the owner of a user-owned repository.

Example:

```bash theme={null}
entire repo mirror collaborators list github.com/acme/widget
```

| Flag     | Description                         |
| -------- | ----------------------------------- |
| `--json` | Output raw JSON instead of a table. |

## `entire repo visibility get`

Show whether an Entire repository is public or private.

```bash theme={null}
entire repo visibility get REPO [flags]
```

| Flag                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--json`            | Output raw JSON instead of a table.                          |
| `--project PROJECT` | Owning project name or ULID. Required when `REPO` is a name. |

## `entire repo visibility set`

Set an Entire repository's visibility.

```bash theme={null}
entire repo visibility set REPO VISIBILITY [flags]
```

`VISIBILITY` accepts `public` or `private`. `public` grants read-only access to authenticated Entire users. Push and repository management remain restricted to grantees. `private` restricts access to explicit grantees. The caller needs manage permission on the repository.

| Flag                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--json`            | Output raw JSON instead of a table.                          |
| `--project PROJECT` | Owning project name or ULID. Required when `REPO` is a name. |

## Continue With

<CardGroup>
  <Card title="Mirror a GitHub Repository" icon="clone" href="/learn/mirror-a-github-repository">
    Create a mirror and use it from Git.
  </Card>

  <Card title="Mirror Access and Permissions" icon="lock" href="/guides/repositories/mirror-access-and-permissions">
    Understand GitHub-synced access, hourly collaborator sync, and offboarding.
  </Card>

  <Card title="project" icon="folder" href="/cli-reference/project">
    Manage the projects that own repositories.
  </Card>

  <Card title="grant" icon="key" href="/cli-reference/grant">
    Grant and revoke repository access.
  </Card>
</CardGroup>


# review
Source: https://docs.entire.io/cli-reference/review

Run a multi-agent review against a branch and consolidate the results into a final verdict.

Run a multi-agent review against the current branch, or against another branch with `--target`.

```bash theme={null}
entire review [PROFILE] [flags]
```

`entire review` starts reviewer agents in parallel, then uses a judge agent to consolidate their reports into a final verdict.

Reviews are saved as named profiles in Entire settings. On first run, guided setup writes a profile and asks before starting agents.

## Configure a Review Profile

Open the review setup flow:

```bash theme={null}
entire review --configure
```

Use non-interactive flags when you want to create or update a profile from a script:

```bash theme={null}
entire review --configure \
  --set-agents codex,claude-code \
  --set-judge codex \
  --set-output local
```

This creates the default `general` profile unless you choose another profile name in the interactive setup.

## Run a Review

Run a named profile:

```bash theme={null}
entire review general
```

You can also select a profile with `--profile`:

```bash theme={null}
entire review --profile general
```

Scope the review against a specific base branch:

```bash theme={null}
entire review general --base origin/main
```

Add one-off instructions for a single run:

```bash theme={null}
entire review general --prompt "Focus on auth, error handling, and missing tests."
```

Run only one reviewer from the selected profile:

```bash theme={null}
entire review general --agent codex
```

Review a branch other than the one you are on, without switching your checkout. Entire checks it out in a worktree and reviews it there:

```bash theme={null}
entire review general --target feature/token-refresh --cleanup-worktree
```

## Flags

| Flag                        | Description                                                                                                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--configure`               | Set up a review profile. Shows available agents and profiles unless paired with `--set-*` flags.                                                                                    |
| `--set-agents AGENTS`       | With `--configure`, set comma-separated reviewer agents for the profile.                                                                                                            |
| `--set-judge AGENT[=MODEL]` | With `--configure`, set the consolidating judge.                                                                                                                                    |
| `--set-output MODE`         | With `--configure`, set where the verdict is delivered: `local` or `trail`. Defaults to `local`.                                                                                    |
| `--local`                   | With `--configure`, save to `.entire/settings.local.json` instead of shared `.entire/settings.json`.                                                                                |
| `--set-task TEXT`           | With `--configure`, set the profile's canonical task text.                                                                                                                          |
| `--set-model AGENT=MODEL`   | With `--configure`, set a model for a reviewer agent. Repeatable.                                                                                                                   |
| `--set-slot AGENT[=MODEL]`  | With `--configure`, set one reviewer slot. Repeatable; the same agent or model can appear more than once.                                                                           |
| `--edit`                    | Reopen the advanced review profile skill picker.                                                                                                                                    |
| `--findings [HANDLE]`       | Browse local review findings. Pass a handle to print one saved run.                                                                                                                 |
| `--agent NAME`              | Run one reviewer from the selected profile.                                                                                                                                         |
| `--agents`                  | List reviewer agents available for the selected profile.                                                                                                                            |
| `--model NAME`              | Override the model for the selected `--agent` reviewer. Requires `--agent`.                                                                                                         |
| `--models`                  | List the models each review agent advertises. Optionally combine with `--agent NAME`.                                                                                               |
| `--profile NAME`            | Select a review profile. You can also pass the profile name as the positional argument.                                                                                             |
| `--prompt TEXT`             | Add one-off instructions for this review run.                                                                                                                                       |
| `--timeout DURATION`        | Time limit for each reviewer and the judge. By default, reviewers have no timeout and the judge has a 20-minute timeout.                                                            |
| `--base REF`                | Scope the review against a Git ref instead of the default mainline ref. Defaults to the first existing ref from `origin/HEAD`, `origin/main`, `origin/master`, `main`, or `master`. |
| `--target REF`              | Check out a branch in a worktree and run the review there. Accepts a branch name, a trail ID, or an Entire trail URL.                                                               |
| `--cleanup-worktree`        | Remove a newly created `--target` worktree after a successful review. Interactive runs ask when you omit this flag.                                                                 |
| `--list`                    | List configured review profiles with their reviewers and judge.                                                                                                                     |
| `-h, --help`                | Show help for `entire review`.                                                                                                                                                      |

A reviewer that exceeds the timeout is canceled and marked failed; the other reviewers and the judge continue. If the judge times out or fails, the review ends without a verdict.

<Note>
  `entire review --findings` only browses local findings. It does not apply fixes.
</Note>

## Attach an Existing Review

To tag an already-finished session as a review, use [`entire session attach`](/cli-reference/session#session-attach) with `--review`:

```bash theme={null}
entire session attach SESSION_ID --review
```

## Examples

```bash theme={null}
# Configure a review profile
entire review --configure

# Configure a profile without the interactive setup
entire review --configure --set-agents codex,claude-code --set-judge codex --set-output local

# Run the general profile
entire review general

# Review a stacked branch against its parent
entire review general --base origin/my-parent-branch

# Run one configured reviewer
entire review general --agent codex

# Browse local findings
entire review --findings

# List configured profiles
entire review --list
```

## Continue with

<CardGroup>
  <Card title="Review and Recap Agent Work" icon="graduation-cap" href="/learn/review-and-recap-agent-work">
    Configure reviewers, run a review, and inspect recent activity in one tutorial.
  </Card>

  <Card title="Review Profiles" icon="sliders" href="/guides/configuration/review-profiles">
    Configure shared and local review behavior.
  </Card>
</CardGroup>


# runner
Source: https://docs.entire.io/cli-reference/runner

Set up and tune this repository's trail runners.

Manage the trail runner configs in `.entire/runners/`.

```bash theme={null}
entire runner SUBCOMMAND
```

`entire runner` is experimental and is hidden from the top-level help. A [runner](/glossary#runner) scores and reviews a branch's changes; this command manages the per-repository set: risk, confidence, drift, security, review, and others.

## runner setup

Create and tailor this repository's trail runners.

```bash theme={null}
entire runner setup [RUNNER] [flags]
```

`setup` creates the default runner set in a repository that has none, then tailors the generic templates to this repository using gathered signal: its documentation and structure, merged pull requests and issues, checkpoint churn hotspots, and past trail findings. Run it again in a repository that already has runners and it offers to re-tune them.

By default, `setup` prints the tailoring prompt to stdout, ready to paste into any agent. Pass `--run` to have your configured summary provider run the prompt headlessly and rewrite the runner files in place.

Pass a runner name, such as `risk`, to tailor only that runner.

| Flag                    | Description                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `--debug-dir DIRECTORY` | Write the assembled prompt as `prompt.txt` and, with `--run`, the raw model response as `response.txt`, to this directory. |
| `--limit N`             | How many recent pull requests, issues, and trails to sample. Defaults to `20`.                                             |
| `--run`                 | Run the configured summary provider headlessly to rewrite the runner files in place, instead of printing the prompt.       |
| `--sources SOURCES`     | Comma-separated data sources to gather: `repo`, `prs`, `checkpoints`, `trails`, or `all`. Defaults to `all`.               |
| `-y, --yes`             | Skip the confirmation when creating the default runner set in a repository that has none.                                  |

```bash theme={null}
# Print the tailoring prompt for every runner
entire runner setup

# Create the default runners without a confirmation prompt, then rewrite them with your summary provider
entire runner setup --yes --run

# Tailor only the risk runner using repository data
entire runner setup risk --run --sources repo
```

<Warning>
  `--run` rewrites files in `.entire/runners/`. Review changes with `git diff -- .entire/runners/` before committing.
</Warning>

## Continue With

<CardGroup>
  <Card title="review" icon="code-review" href="/cli-reference/review">
    Run a multi-agent review against a branch.
  </Card>

  <Card title="Glossary" icon="book" href="/glossary#runner">
    See how runners and trails fit together.
  </Card>
</CardGroup>


# search
Source: https://docs.entire.io/cli-reference/search

Search checkpoints, commits, and sessions with hybrid semantic and keyword matching, or search code content with --code.

Search indexed Entire history from the CLI. Add `--code` to search code content instead.

```bash theme={null}
entire search [QUERY] [flags]
```

`entire checkpoint search` is an equivalent alias. In CLI versions 0.9.0 and earlier, `entire search` was hidden from `entire --help` but remained runnable.

By default, search is scoped to the current repository. Use `--repo`, `--all-repos`, or `repo:*` to change the scope.

Run without arguments to open interactive search. Use `--json` for machine-readable output.

## Examples

```bash theme={null}
entire search "auth token refresh"
entire search "auth token refresh" --repo entireio/cli
entire search "repo:* auth token refresh"
entire search "retry logic" author:alex branch:main date:month
entire search "auth token refresh" --json
entire search "auth token refresh" --compact --limit 5
```

## Flags

| Flag                | Description                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `--all-repos`       | Search all accessible repositories instead of only the current repository.                                                                 |
| `--author NAME`     | Filter by author name.                                                                                                                     |
| `--branch NAME`     | Filter by branch name.                                                                                                                     |
| `--case-sensitive`  | Reserved for future case-sensitive code search. Only valid with `--code`; currently does not change backend matching.                      |
| `--code`            | Search code content across repositories instead of checkpoints, commits, and sessions.                                                     |
| `--compact`         | Return trimmed JSON for agents. Implies `--json` and cannot be combined with `--code`.                                                     |
| `--date PERIOD`     | Filter by time period. Use `week` or `month`.                                                                                              |
| `--json`            | Output as JSON.                                                                                                                            |
| `--limit N`         | Maximum number of results per page, or total results with `--code`. Default is `10`.                                                       |
| `--page N`          | Page number, 1-based. Default is `1`.                                                                                                      |
| `--repo REPOSITORY` | Filter by repository. Accepts `gh/owner/repo`, `et/project/repo`, `owner/repo`, a repository ULID, or `*`; repeatable and comma-separated. |

## Inline Filters

CLI queries also support inline filters:

```bash theme={null}
entire search "retry logic author:alex date:month branch:main repo:entireio/cli"
```

Supported inline filters are:

* `author:NAME`
* `date:week|month`
* `branch:NAME`
* `repo:OWNER/NAME`
* `repo:*`

## Compact Output for Agents

Use `--compact` to omit full prompts and return a smaller semantic-search response:

```bash theme={null}
entire search "auth token refresh" --compact --limit 5
```

Each result includes its identifiers, type, ranking metadata, and a truncated title. Repository, branch, author, date, files touched, and match snippets appear when available. `--compact` implies `--json`. It cannot be combined with `--code`.

For semantic search, `--limit` sets the maximum results per page. For Code Search, it sets the maximum total results.

## Code Search

Use `--code` to search code content instead of checkpoints, commits, and sessions. Results are grouped under a `repo:path` heading with line-numbered matches beneath it.

```bash theme={null}
entire search --code "refreshAccessToken"
entire search --code "refreshAccessToken" --repo entireio/cli
entire search --code "repo:* refreshAccessToken"
entire search --code "refreshAccessToken" --json
```

Code search matches exact text and is currently case-insensitive. The CLI accepts `--case-sensitive`, but the search backend does not yet apply it. In `--code` mode, `repo:` is the only supported inline filter. The `author:`, `branch:`, and `date:` tokens are treated as literal query text, and the `--author`, `--branch`, `--date`, and `--page` flags do not apply.

In interactive search, press `3` to switch to the **Code** tab. The other tabs are **Commits** (`1`) and **Sessions** (`2`). Checkpoint matches fold into their owning sessions. Use `entire checkpoint explain CHECKPOINT_ID` to open a checkpoint directly.

## Continue With

<CardGroup>
  <Card title="Search" icon="magnifying-glass" href="/guides/search/overview">
    Compare semantic and keyword search with literal code search.
  </Card>

  <Card title="Search in the CLI" icon="terminal" href="/guides/search/search-in-cli">
    Use both search modes from your terminal.
  </Card>

  <Card title="Search Past Work and Code" icon="route" href="/learn/search-past-agent-work">
    Practice search with a guided tutorial.
  </Card>

  <Card title="What Is Indexed and When" icon="database" href="/guides/search/what-is-indexed">
    Check availability, timing, and repository scope.
  </Card>
</CardGroup>


# session
Source: https://docs.entire.io/cli-reference/session

View and manage agent sessions tracked by Entire.

View and manage agent sessions tracked by Entire.

```bash theme={null}
entire session SUBCOMMAND
```

`entire session` is also available as `entire sessions`.

## Session Lifecycle

```mermaid theme={null}
flowchart LR
    start["Agent starts"] --> active["Active"]
    active -->|"tracking lingers after the agent exits"| stale["Stale"]
    active -->|"session stop"| stopped["Stopped"]
    stale -->|"session stop --force"| stopped
    stopped -->|"session resume"| resumed["Resumed"]
    resumed -->|"start agent"| active

    elsewhere["Active in another worktree"] -->|"session adopt"| adopted["Adopted"]
    adopted --> active

    transcript["Existing transcript"] -->|"session attach"| attached["Attached"]
    attached --> checkpoint["Checkpoint linked to latest commit"]

    history["Past local transcript"] -->|"entire import"| imported["Imported"]
    imported --> archive["Checkpoint for inspection only"]
```

The diagram shows the paths through a session workflow. `entire session info` reports live sessions as active or ended. Stale, resumed, adopted, attached, and imported describe a session's condition or how its context entered Entire:

| State or Outcome | Meaning                                                                                                                             |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Active           | Entire is tracking the agent session.                                                                                               |
| Stale            | The agent has stopped, but its tracking state still appears active. Stop it to clear the live state.                                |
| Stopped          | `entire session stop` marked the session as ended.                                                                                  |
| Resumed          | `entire session resume` checked out the branch and restored the session log. Starting the agent returns the session to active work. |
| Adopted          | `entire session adopt` moved an active session from another worktree into the current repository.                                   |
| Attached         | `entire session attach` linked an existing transcript to the latest commit and checkpoint.                                          |
| Imported         | `entire import` stored past transcript history as a checkpoint for inspection only, with no commit link.                            |

## session current

Show the most recently active session for the current worktree.

```bash theme={null}
entire session current [flags]
```

| Flag           | Description                                 |
| -------------- | ------------------------------------------- |
| `--json`       | Output as JSON                              |
| `--transcript` | Stream raw agent transcript bytes to stdout |

## session list

List all sessions tracked by Entire, including ended sessions.

```bash theme={null}
entire session list [flags]
```

For active sessions only, use [`entire status`](/cli-reference/status).

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

## session info

Show detailed information for a specific session.

`entire session info` shows agent, model, status, worktree, timing, token usage, checkpoint linkage, and files touched.

```bash theme={null}
entire session info SESSION_ID [flags]
```

| Flag           | Description                                 |
| -------------- | ------------------------------------------- |
| `--json`       | Output as JSON                              |
| `--transcript` | Stream raw agent transcript bytes to stdout |

## session tokens

Show token usage and optimization recommendations for a session.

```bash theme={null}
entire session tokens [SESSION_ID] [flags]
```

When you omit the session ID, Entire reports on the most recently active session, preferring the current worktree and falling back to the newest session when none matches this worktree.

| Flag            | Description                                       |
| --------------- | ------------------------------------------------- |
| `--agent-brief` | Give agents compact guidance for the next step    |
| `--current`     | Prefer the current worktree's most recent session |
| `--json`        | Output as JSON                                    |

## session stop

Stop one or more active sessions.

```bash theme={null}
entire session stop [SESSION_ID] [flags]
```

| Flag          | Description                  |
| ------------- | ---------------------------- |
| `--all`       | Stop all active sessions     |
| `-f, --force` | Skip the confirmation prompt |

`entire session stop` marks sessions as ended. It does not create a checkpoint or flush pending work. Commit first when you want Entire to link session context to code changes.

```bash theme={null}
# Stop a specific session without confirmation
entire session stop SESSION_ID --force

# Stop all active sessions without confirmation
entire session stop --all --force
```

## session attach

Attach an existing agent session that Entire did not capture automatically.

```bash theme={null}
entire session attach SESSION_ID [flags]
```

This command reads the session transcript, creates or updates a checkpoint, and links it to the latest commit. Use it if you started the session before installing hooks, the hooks did not fire, or you want to preserve a research session.

If the latest commit already has an `Entire-Checkpoint` trailer, Entire adds the session to that checkpoint. Otherwise, Entire creates a checkpoint and offers to amend the commit with the trailer.

| Flag               | Description                                                                                                                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a, --agent NAME` | Agent that created the session. Defaults to `claude-code`. Run `entire agent list` to see registered agents, including discovered [agent integrations](/agents/agent-integration-protocol/overview). |
| `-f, --force`      | Skip confirmation and amend the latest commit with the checkpoint trailer                                                                                                                            |
| `--review`         | Tag the attached session as an agent review                                                                                                                                                          |
| `--skills SKILL`   | Declare a review Skill that ran. Repeat the flag for multiple Skills. Only used with `--review`.                                                                                                     |

```bash theme={null}
# Attach a Codex session and amend HEAD automatically
entire session attach SESSION_ID --agent codex --force

# Attach a session as a review
entire session attach SESSION_ID --agent codex --review

# Record multiple Skills used during a review
entire session attach SESSION_ID --review --skills review --skills security
```

<Note>
  `entire session attach` requires at least one commit in the repository. If Entire cannot locate the transcript for the selected agent, it tries to detect the agent from known transcript locations.
</Note>

## session adopt

Adopt an active session from another worktree into the current repository.

```bash theme={null}
entire session adopt [SESSION_ID] --from SOURCE_WORKTREE [flags]
```

Use this command when an agent starts in one repository or worktree, then moves and makes changes in another.

| Flag          | Description                                                              |
| ------------- | ------------------------------------------------------------------------ |
| `--from PATH` | Source worktree that already tracks the session                          |
| `--force`     | Replace an existing local state file for the same session                |
| `--yes`       | Confirm adoption and replacement within the same store without prompting |

## session resume

Resume an agent session from a branch or interactive picker.

```bash theme={null}
entire session resume [BRANCH] [flags]
```

With no argument, Entire opens an interactive picker of stopped sessions across all worktrees. After you select a session, Entire checks out its branch, restores the session log, and asks whether to start the agent.

With a branch argument, Entire:

1. Checks out the specified branch.
2. Finds the session ID from commits unique to the branch.
3. Restores the session log if it does not exist locally.
4. Asks whether to start the agent in an interactive terminal or prints the resume command in a terminal without interactive input.

| Argument | Description                                         |
| -------- | --------------------------------------------------- |
| `BRANCH` | Optional branch that contains the session to resume |

| Flag          | Description                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| `-f, --force` | Resume from an older checkpoint without confirmation and overwrite the local session log from that checkpoint |

```bash theme={null}
# Select a stopped session interactively
entire session resume

# Resume the session associated with a branch
entire session resume BRANCH

# Resume from an older checkpoint without confirmation
entire session resume BRANCH --force
```

<Note>
  If the branch exists on the remote but not locally, Entire prompts you to fetch it.
</Note>

<Warning>
  If the branch contains newer commits without checkpoints, Entire can reset Git state to the most recent commit with a checkpoint. Entire prompts before continuing unless you use `--force`.
</Warning>


# status
Source: https://docs.entire.io/cli-reference/status

Show the current Entire status for this repository.

Show whether Entire is currently enabled or disabled for this repository.

```bash theme={null}
entire status [flags]
```

| Flag         | Description                                 |
| ------------ | ------------------------------------------- |
| `--detailed` | Show detailed status for each settings file |
| `--json`     | Output as JSON                              |

For all sessions, including ended ones, use [`entire session list`](/cli-reference/session#session-list).


# tokens
Source: https://docs.entire.io/cli-reference/tokens

Analyze token usage across sessions and checkpoints.

Analyze token usage across sessions and checkpoints.

```bash theme={null}
entire tokens SUBCOMMAND
```

`entire tokens` is experimental and appears under [labs](/cli-reference/labs) while the workflow is still being refined.

Three commands report on token usage, at different scopes:

| Command                                                                   | Scope                        |
| ------------------------------------------------------------------------- | ---------------------------- |
| [`entire session tokens`](/cli-reference/session#session-tokens)          | One session                  |
| [`entire checkpoint tokens`](/cli-reference/checkpoint#checkpoint-tokens) | One checkpoint               |
| `entire tokens profile`                                                   | Committed checkpoint history |

## tokens profile

Aggregate token usage and recommendations across committed checkpoint history.

```bash theme={null}
entire tokens profile [flags]
```

| Flag        | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `--all`     | Analyze all committed checkpoints.                          |
| `--json`    | Output as JSON.                                             |
| `--limit N` | Maximum committed checkpoints to analyze. Defaults to `50`. |

```bash theme={null}
entire tokens profile
entire tokens profile --all
entire tokens profile --limit 200 --json
```

The profile reads committed checkpoint metadata only. It does not inspect transcripts or source files, so it is deterministic and adds no token cost while you diagnose token usage. By default it scans the latest 50 committed checkpoints.

## Continue With

<CardGroup>
  <Card title="session tokens" icon="terminal" href="/cli-reference/session#session-tokens">
    Token usage and recommendations for one session.
  </Card>

  <Card title="checkpoint tokens" icon="terminal" href="/cli-reference/checkpoint#checkpoint-tokens">
    Token usage and recommendations for one checkpoint.
  </Card>
</CardGroup>


# version
Source: https://docs.entire.io/cli-reference/version

Show build information including the CLI version, Go version, and OS/architecture.

Show build information including the CLI version, Go version, and OS/architecture.

```bash theme={null}
entire version
```

You can also use the `--version` flag on the root command:

```bash theme={null}
entire --version
```

Both produce the same three lines: the CLI version, the Go version the release was built with, and your platform. See [Verify the Install](/installation#verify-the-installation) for a worked example.

<Note>
  Nightly and development builds report a longer version string that encodes the build date and commit. Include the whole line when you file a bug report.
</Note>


# why
Source: https://docs.entire.io/cli-reference/why

Explain the commit, checkpoint, prompt, and session behind a file or line.

Explain the captured context behind a file or line.

```bash theme={null}
entire why FILE[:LINE] [flags]
```

Use `entire why` when you want to jump from a file or specific line to the commit, checkpoint, prompt, and session behind it.

## Flags

| Flag          | Description                                                               |
| ------------- | ------------------------------------------------------------------------- |
| `--line LINE` | Explain a specific line, for example `12`. This is the same as `FILE:12`. |
| `--json`      | Output explanation as JSON                                                |

## Examples

```bash theme={null}
entire why overview.mdx
entire why overview.mdx:12
entire why overview.mdx --line 12
entire why overview.mdx:12 --json
```

## Continue With

<CardGroup>
  <Card title="Investigate Why Code Exists" icon="search-code" href="/learn/investigate-why-code-exists">
    Use `entire why` in a full provenance investigation.
  </Card>

  <Card title="checkpoint explain" icon="terminal" href="/cli-reference/checkpoint#checkpoint-explain">
    Inspect the full checkpoint context.
  </Card>
</CardGroup>


# Delete Your Account
Source: https://docs.entire.io/delete-account

Permanently delete your Entire account, and cancel during the 7-day cooldown

You can permanently delete your Entire account from [entire.io](https://entire.io) at any time. This page covers what gets deleted, the 7-day cooldown, how to cancel, and what happens when deletion completes.

This is how you exercise your **right to erasure** (the "right to be forgotten") under the GDPR and similar laws. For what data we hold and how long we keep it, see the [Privacy Policy](https://entire.io/privacy).

## Before You Start

When you open the delete dialog, Entire shows you a preview of exactly what will happen to your account. Review it before you confirm.

* **Permanently deleted**: your Entire account, your profile data, and the repositories connected to your personal account.
* **Access you'll lose**: your memberships in other organizations and any roles granted to you. You are removed from those organizations; the organizations themselves and their repositories are not deleted.

Your Git repositories are not touched. Checkpoint data lives in your own repository, either as one Git ref per checkpoint under `refs/entire/checkpoints/` or on the `entire/checkpoints/v1` branch, so deleting your Entire account does not erase it. Delete those refs yourself if you want the transcripts gone. See [Where your data lives](/security#where-your-data-lives).

<Warning>
  You can't delete your account while you **own an organization**. Transfer
  ownership or delete each organization you own first, then delete your account.
  The dialog lists the organizations you still own.
</Warning>

## Delete Your Account

<Steps>
  <Step title="Open Account Settings">
    Sign in to [entire.io](https://entire.io), open your **Account** settings, and
    find the **Danger zone**.
  </Step>

  <Step title="Start the Deletion">
    Click **Delete account**. Entire loads a preview of what will be deleted and
    which access you'll lose.
  </Step>

  <Step title="Confirm">
    Type your GitHub username to confirm, then click **Delete my account**. If you
    still own an organization, resolve the blockers listed in the dialog first.
  </Step>

  <Step title="You're Signed Out">
    Your account is scheduled for deletion and you're signed out everywhere
    immediately. A 7-day cooldown begins.
  </Step>
</Steps>

## 7-Day Cooldown

Deletion is not immediate. Your account enters a **7-day cooldown** during which nothing is erased yet and you can still change your mind.

While the cooldown is running:

* You're signed out, and your access tokens stop working, so you can't push new work or use the API.
* You can sign back in to cancel. Signing in **does not** cancel the deletion on its own. You have to click **Cancel deletion**.

### Cancel a Pending Deletion

<Steps>
  <Step title="Sign Back In">
    Return to [entire.io](https://entire.io) and sign in. You'll see a banner:
    *"Your account is scheduled for deletion on \[date]."*
  </Step>

  <Step title="Cancel">
    Click **Cancel deletion**. Your account is no longer scheduled for deletion and
    full access is restored right away.
  </Step>
</Steps>

<Warning>
  Once the 7-day cooldown ends, deletion is **permanent and cannot be undone**.
  Erased data cannot be recovered.
</Warning>

## What Happens When Deletion Completes

When the cooldown ends, Entire permanently erases your account and personal data across every region where we store it. We also ask the third-party services we use, such as our analytics and CRM providers, to erase your personal data. Those providers are listed on our [Subprocessors](https://entire.io/subprocessors) page.

## What We Keep After Deletion

We keep a small amount of information after deletion where the law requires it: tax, accounting, and security records. The [Privacy Policy](https://entire.io/privacy) lists what and for how long.

Repository content follows the repository, not your account: it is retained for as long as the repository exists on our services and is deleted when the repository (or the relevant history) is deleted.

## Other Data Requests

Deleting your account is the fastest way to erase your personal data yourself. To ask for a copy of your data, correct it, or move it somewhere else, email us.

<Card title="Email legal@entire.io" icon="envelope" href="mailto:legal@entire.io">
  Reach us for privacy questions and requests about your data. The [Privacy
  Policy](https://entire.io/privacy) lists your rights in full.
</Card>


# Frequently Asked Questions
Source: https://docs.entire.io/faq

Answers to common questions about checkpoints and attribution.

## Checkpoints

### Why Does Entire Use Commit Trailers Instead of Git Notes?

Entire links commits to checkpoints with an `Entire-Checkpoint` trailer:

```text theme={null}
Entire-Checkpoint: a3b2c4d5e6f7
```

The trailer points to checkpoint metadata stored in your repository: one Git ref per checkpoint under `refs/entire/checkpoints/` by default, or the shared `entire/checkpoints/v1` branch in repositories that use the legacy branch backend. Entire uses this approach because commit trailers survive common Git workflows better than metadata attached only to a commit SHA.

Git notes have a few practical limitations:

* Normal Git pushes skip them unless you configure note refs separately
* They attach to commit SHAs, which change during rebases, amends, and cherry-picks
* Hosted Git platforms do not consistently support them in review and merge workflows

By storing the stable checkpoint ID in the commit message, Entire keeps the link with the commit itself. That is more reliable for teams that rebase, amend, cherry-pick, use hosted merge flows, or have contributors using different Git clients.

## Attribution

### What Do `entire blame` and `entire why` Actually Tell Me?

Both commands answer questions about a line of code, and both answer them at the level of the commit that introduced the line, not the line itself.

[`entire blame`](/cli-reference/blame) shows git-blame-style output with the attribution status of each line's introducing commit:

* `AI`: Entire attributed the commit to an AI agent session
* `MX`: the commit mixed AI-attributed and human-attributed work
* `HU`: the commit carries no AI-attributed checkpoint data
* `??`: the line is uncommitted

[`entire why`](/cli-reference/why) takes a line and returns the commit, checkpoint, prompt, and session behind it.

What they promise:

* The commit that introduced the line as Git currently records it
* Whether that commit carried agent-attributed checkpoint data
* The session and prompt behind that commit, when a checkpoint is linked

What they do not promise:

* That a given line was written by a specific agent or person. The tag describes the whole commit, so a line hand-edited inside an `AI` commit still reads as `AI`.
* That the answer survives history rewriting. Both commands follow Git blame, so a rebase, squash, or manual conflict resolution reattributes the line to whichever commit Git now credits.
* Line-level counts. `--long` adds agent, model, author, and session columns, all still commit-level.

<Note>
  `entire blame` and `entire why` are [labs commands](/cli-reference/labs). They work today, and their output may change.
</Note>

### Why Doesn't Entire Provide Durable Line-Level AI Attribution?

Entire preserves durable session and commit provenance.

That means Entire can reliably answer questions like:

* Which session produced this commit?
* Which prompts and transcript led to this change?
* Which checkpoint is linked to this commit?

Entire can calculate attribution for a session or commit, such as how many changed lines came from an agent versus a human. That is different from assigning a permanent owner to every line of code as it moves through Git history.

Durable line-level attribution is much harder. In normal team workflows, line-level metadata becomes fragile when:

* Commits are rebased, amended, cherry-picked, or squashed
* Merge conflicts are resolved manually
* Merges happen in hosted Git UIs
* Human edits are mixed into a manual commit before commit time

The core issue is that lines move. A line can shift, split, merge with nearby edits, or be rewritten later. Keeping per-line attribution correct across those changes requires repair logic that runs everywhere history changes.

Entire currently prioritizes a more durable record:

* Preserve the full session transcript
* Link commits to stable checkpoint IDs
* Keep commit-level provenance intact across common Git workflows

## Continue With

<CardGroup>
  <Card title="Investigate Why Code Exists" icon="magnifying-glass" href="/learn/investigate-why-code-exists">
    Trace a surprising line from attribution to the checkpoint context behind it.
  </Card>

  <Card title="Glossary" icon="book" href="/glossary">
    Definitions for checkpoints, sessions, trails, runners, and the rest of Entire's vocabulary.
  </Card>
</CardGroup>


# Glossary
Source: https://docs.entire.io/glossary

The vocabulary Entire uses across the CLI, the web interface, and this documentation.

<div>
  <input aria-label="Filter glossary terms" placeholder="Filter glossary terms..." type="search" />

  <span>
    38 terms
  </span>
</div>

| Glossary term                          | Definition                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span />**Agent**                      | An AI coding assistant connected to Entire, such as [Claude Code](/agents/claude-code), [Codex](/agents/codex), [Cursor](/agents/cursor), [Factory](/agents/factory-droid), [Gemini CLI](/agents/gemini-cli), [GitHub Copilot CLI](/agents/copilot-cli), [OpenCode](/agents/opencode), or [Pi](/agents/pi).                                     |
| <span />**Agent run**                  | One execution of an agent inside a session. Entire compares your work before each run with the agent's changes so line attribution can stay accurate.                                                                                                                                                                                           |
| <span />**Checkpoint**                 | A save point for your work. Entire creates checkpoints around agent activity and links committed ones to Git commits.                                                                                                                                                                                                                           |
| <span />**Checkpoint ID**              | The identifier for a checkpoint, shown in the CLI and entire.io. The format follows the [storage backend](#checkpoint-storage-backend): ref-based storage, the default, uses a 26-character time-sortable ULID such as `01KVBJCWYA4YW6J5M9GP655HZN`; branch-based storage uses 12 hexadecimal characters such as `8a513f56ed70`.                |
| <span />**Checkpoint linking**         | The connection between a Git commit and the Entire checkpoint that captured the session context behind it.                                                                                                                                                                                                                                      |
| <span />**Checkpoint ref**             | The Git ref that holds one checkpoint under the ref-based backend, at `refs/entire/checkpoints/<shard>/<id>`. List them with `git for-each-ref refs/entire/checkpoints/`.                                                                                                                                                                       |
| <span />**Checkpoint remote**          | A Git remote that holds checkpoint metadata separately from your code remote. By default, Entire pushes checkpoint metadata to your code remote.                                                                                                                                                                                                |
| <span />**Checkpoint storage backend** | How Git organizes checkpoints in your repository. `git-refs` writes one [checkpoint ref](#checkpoint-ref) per checkpoint and is the default for repositories enabled with CLI 0.10.0 or later. `git-branch` writes all of them to the [checkpoints branch](#checkpoints-branch). See [Session Storage](/guides/checkpoints/checkpoint-storage). |
| <span />**Checkpoints branch**         | The Git branch where Entire stores checkpoint and session metadata under the branch-based backend. Entire names the branch `entire/checkpoints/v1`.                                                                                                                                                                                             |
| <span />**Code Search**                | A literal search over the text of tracked files on a repository's indexed branch, returning the files and lines that contain a match. Run `entire search --code`, or open the **Code** tab in entire.io.                                                                                                                                        |
| <span />**Commit trailer**             | Structured metadata that Entire appends to a Git commit message, such as `Entire-Checkpoint` and `Entire-Attribution`.                                                                                                                                                                                                                          |
| <span />**Committed checkpoint**       | A checkpoint that Entire has linked to a Git commit and written to checkpoint storage.                                                                                                                                                                                                                                                          |
| <span />**Dispatch**                   | A markdown summary of recent agent work across one or more repositories, branches, and time windows.                                                                                                                                                                                                                                            |
| <span />**Entire CLI**                 | The command line tool that records sessions, creates checkpoints, links commits, and syncs metadata.                                                                                                                                                                                                                                            |
| <span />**entire.io**                  | The web interface for searching and browsing repositories, sessions, checkpoints, dispatches, and agent activity captured by Entire.                                                                                                                                                                                                            |
| <span />**Entire Repository**          | A Git repository that EntireDB serves. Entire can host the repository or connect it to an upstream GitHub repository through one or more mirror placements.                                                                                                                                                                                     |
| <span />**Entire-Attribution**         | A commit trailer that records how much of a commit came from the agent versus a human.                                                                                                                                                                                                                                                          |
| <span />**Entire-Checkpoint**          | A commit trailer that records the checkpoint ID associated with a commit.                                                                                                                                                                                                                                                                       |
| <span />**Finding**                    | A single issue a review [runner](/glossary#runner) raises against a branch or [trail](/glossary#trail), such as a bug, a regression, or a missing test. Open findings block the trail from merging until you resolve or dismiss each one.                                                                                                       |
| <span />**Line attribution**           | Entire's calculation of how many changed lines in a commit came from the agent and how many came from a human.                                                                                                                                                                                                                                  |
| <span />**Metadata**                   | Structured data Entire records about sessions and checkpoints, including timestamps, agent type, token usage, attribution, and configuration.                                                                                                                                                                                                   |
| <span />**Mirror**                     | A connection between a GitHub repository and Entire. GitHub remains the upstream repository, while Entire serves Git traffic through one or more regional mirror placements.                                                                                                                                                                    |
| <span />**Mirror placement**           | A copy of a GitHub-backed repository on one EntireDB cluster. Each placement has its own cluster, status, and `entire://` URL.                                                                                                                                                                                                                  |
| <span />**Nested session**             | A child session created when an agent spawns another agent or sub-agent during the same body of work.                                                                                                                                                                                                                                           |
| <span />**Plugin**                     | An executable named `entire-<name>` on your `$PATH` that adds a command to the Entire CLI. Running `entire <name>` dispatches to it. Distinct from a [skill](/glossary#skill), which teaches an agent to use Entire in natural language.                                                                                                        |
| <span />**Repository object**          | The control-plane record that identifies an Entire Repository and stores metadata such as its owning project, visibility, and placement information. The `entire repo` commands manage these objects.                                                                                                                                           |
| <span />**Runner**                     | A config-driven job that runs an AI coding agent in an isolated cloud sandbox against a branch or [trail](/glossary#trail). You define runners per repository in `.entire/runners/`. They produce Entire's automated review signals, including review comments, summaries, and scores for risk, drift, confidence, and security.                |
| <span />**Search**                     | Entire's search over every indexed repository you can access, covering both [semantic search](#semantic-search) and [Code Search](#code-search) so one query returns the code and the work behind it. See the [Search overview](/guides/search/overview).                                                                                       |
| <span />**Semantic search**            | A search over indexed Entire history that matches by phrase, meaning, or agent context rather than by exact words, returning related commits and sessions. Its literal counterpart is [Code Search](#code-search).                                                                                                                              |
| <span />**Session**                    | A complete interaction with an AI coding agent from start to finish. Sessions include prompts, responses, code changes, checkpoints, token usage, metadata, and line attribution.                                                                                                                                                               |
| <span />**Session branch**             | A Git branch that holds captured session data without adding commits to your working branch.                                                                                                                                                                                                                                                    |
| <span />**Session context**            | The prompts, responses, tool activity, code changes, and metadata that explain what happened during a session.                                                                                                                                                                                                                                  |
| <span />**Shadow branch**              | A temporary local branch that holds checkpoints during active sessions. Entire names shadow branches like `entire/<commit>-<worktree>` and does not push them to remote repositories.                                                                                                                                                           |
| <span />**Skill**                      | A reusable workflow that helps an agent use Entire history, checkpoints, and session context for a specific task.                                                                                                                                                                                                                               |
| <span />**Token usage**                | Counts of input tokens, output tokens, cache creation tokens, cache reads, and API calls recorded for a checkpoint or session.                                                                                                                                                                                                                  |
| <span />**Trail**                      | Entire's unit of work, covering one branch and one pull request from one intent to shipped code. A trail groups that intent, the [checkpoints](/glossary#checkpoint) recorded along the way, and a rolled-up summary and report. Teams review the trail instead of the raw diff.                                                                |
| <span />**Worktree ID**                | An opaque identifier Entire puts in a shadow branch name to tell active worktrees apart.                                                                                                                                                                                                                                                        |

<p>
  No glossary terms match your filter.
</p>


# Capture Sessions and Their Checkpoints
Source: https://docs.entire.io/guides/checkpoints/capture-checkpoints

Learn how Entire captures agent sessions and turns them into committed checkpoints.

Entire captures session context while you work, then creates a committed checkpoint when that context is linked to a Git commit.

## How Capture Works

Checkpoint capture has two parts:

1. [Agent hooks](/agents/overview) collect session context, including prompts, transcript, tool activity, changed files, and token usage when available.
2. Git hooks link that captured context to a commit by adding an [`Entire-Checkpoint` trailer](/glossary#entire-checkpoint).

After the commit, Entire stores checkpoint metadata in your repository, in [its own Git ref or on the checkpoints branch](/security#where-your-data-lives) depending on the [storage backend](/guides/checkpoints/checkpoint-storage). Your working branch stays clean.

## Set Up Capture for an Agent

For a new repository, enable Entire with the agent you use:

```bash theme={null}
entire enable --agent AGENT
```

For a repository where Entire is already enabled, add another agent:

```bash theme={null}
entire agent add AGENT
```

You can see the supported built-in agents in [Agents](/agents/overview), or run:

```bash theme={null}
entire agent list
```

## Commit After Agent Work

To capture agent-assisted work in a checkpoint:

1. Start your agent from an Entire-enabled repository.
2. Ask the agent to make a change.
3. Stage and commit the change with Git.

```bash theme={null}
git add .
git commit -m "Describe the change"
```

If Entire detects recent agent work, it may ask whether to link the commit to the session context. Choose `yes` to create the checkpoint. Choose `always` if you want Entire to remember that preference for future matching commits.

```text theme={null}
Entire: Active Codex session detected
  Last prompt: Add a user settings page...

Link this commit to session context?
  [Y]es / [n]o / [a]lways (remember my choice):
```

## Link Future Commits Automatically

When the "Link this commit to session context?" prompt appears during `git commit`, choosing `yes` or `no` only applies to that one commit.

To link future matching commits in this repository without being prompted during `git commit`, set `commit_linking` to `always`.

Set `commit_linking` in one of these files:

* `.entire/settings.local.json` if this preference should only apply to you
* `.entire/settings.json` if this should be the team setting for the repository

```json theme={null}
{
  "commit_linking": "always"
}
```

## Let the Agent Commit

Your agent can also create commits for you. For example, you might ask it to make a focused change and commit when it is done.

Entire still uses the Git hooks to link the commit to the captured session context. If the agent makes several commits in one session, each commit gets its own checkpoint.

## Capture Multiple Commits from One Session

A single agent session can produce multiple checkpoints. This happens when a long session creates several commits, or when you split the agent's work into smaller commits yourself.

Each commit gets its own checkpoint ID. The checkpoints can share the same session context so you can still inspect the prompts, transcript, and work that led to each commit.

## Capture One Checkpoint from Multiple Sessions

One checkpoint can also include more than one session. This happens when several agent sessions contribute to the work before you make a single commit.

In entire.io, those sessions appear together inside the checkpoint's Sessions tab. The checkpoint diff shows the combined change, while [session details](/guides/sessions/sessions-in-entire-io) show the context behind each contribution.

## What Does Not Create a Checkpoint

Entire needs captured session context and a Git commit to create a normal committed checkpoint.

A checkpoint may not appear when:

* Entire has not been enabled in the repository
* agent hooks were not installed for the agent you used
* the agent did not change files in the repository
* no commit was created
* a GUI Git client could not find the `entire` command from its Git hooks

If a checkpoint is missing or did not link where you expected, see [Troubleshooting](/guides/sessions/troubleshooting).


# Session Storage
Source: https://docs.entire.io/guides/checkpoints/checkpoint-storage

Where Entire stores your session and the checkpoints that are linked with your commits.

Entire stores checkpoints inside your own Git repository, separate from your source branches. Your code stays on your source branches, while prompts, transcripts, session context, and checkpoint metadata live in checkpoint storage. Most of this happens behind the scenes, so your workflow stays the same: you create, search, explain, and resume checkpoints with the same Entire commands regardless of how they are stored.

<Note>
  We verified this page against **Entire CLI 0.10.2**. Run `entire version` to check what you have installed.
</Note>

## Store Checkpoints with Your Code

This is the default and needs no configuration. Entire stores checkpoint data in the same Git repository as your code and pushes it when you push, which keeps the commit, the checkpoint, and the agent context together while leaving your normal Git history clean.

In a repository with several remotes, Entire elects one checkpoint sync remote rather than copying checkpoints everywhere you push. `entire status` names the destination and counts checkpoints that have not reached it.

This can be changed if you want your checkpoint and session storage history to reside elsewhere:

* [**Push checkpoints to a separate repository**](/guides/checkpoints/store-checkpoints-in-another-repo)
* [**Keep checkpoints local on your machine**](/guides/checkpoints/keep-checkpoints-local)

## The Two Storage Backends

The backend controls how Git organizes checkpoint data. It is a separate question from which repository receives that data.

### Ref-Based Storage

Ref-based storage (`git-refs`) is the default. It gives each new checkpoint its own Git ref, a named pointer inside your repository that Entire creates and manages for you. Each ref lives at `refs/entire/checkpoints/<shard>/<id>`, and Entire saves and retrieves each checkpoint independently.

**The benefit:** With ref-based storage, pushes and reads stay fast even as your repository accumulates more agent history. Multiple agents can also save their work at the same time without competing to update a shared branch.

Ref-based checkpoints use 26-character, time-sortable ULIDs, such as `01KVBJCWYA4YW6J5M9GP655HZN`.

Ref-based storage first shipped as an opt-in option in Entire CLI 0.8.42 and became the default in 0.10.0, where `entire enable` writes it during a first-time setup and no longer asks you to choose.

### Branch-Based Storage

Branch-based storage (`git-branch`) keeps every checkpoint on a shared Git branch called [`entire/checkpoints/v1`](/glossary#checkpoints-branch). Each checkpoint sits at `<first two characters of the ID>/<rest of the ID>/` in the branch tree.

**The benefit:** All checkpoint history lives on one branch you can check out, browse, or clone like any other branch.

Branch-based checkpoints use 12-character hexadecimal IDs, such as `a3b2c4d5e6f7`.

A repository you enabled before Entire CLI 0.10.0 uses branch-based storage and stays on it until you [switch backends](#switch-backends).

<span />

## Find Which Backend a Repository Uses

The backend is named by `checkpoints.primary.type` in `.entire/settings.json`, or in `.entire/settings.local.json` when someone set it for their clone alone. An absent `checkpoints` block resolves to `git-branch`, which is why a pre-0.10.0 repository keeps branch storage without any setting naming it.

Checkpoint storage is ordinary Git, so Git reads it without Entire installed. List the per-checkpoint refs:

```bash theme={null}
git for-each-ref refs/entire/checkpoints/
```

Each line names one checkpoint, where `<shard>` is the last two characters of the ID and `<id>` is always the leaf. Check for branch-backed checkpoints too:

```bash theme={null}
git show-ref entire/checkpoints/v1
```

Output from both means the repository holds checkpoints in both formats, which is the expected state after a backend switch. To confirm what reached the remote, run `git ls-remote origin 'refs/entire/checkpoints/*'`.

## Both Backends Stay Readable

Every reader routes by ID format, so one repository can hold both formats at once. This holds for the CLI, entire.io, and the Entire API.

| Checkpoint ID             | Where the read goes                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| ULID                      | Refs only. ULIDs are minted only under ref-based storage                                   |
| Hex, branch-based backend | The `entire/checkpoints/v1` branch                                                         |
| Hex, ref-based backend    | Refs first, then the branch, since a hex checkpoint may still sit on the pre-switch branch |

`entire checkpoint list` merges both backends and de-duplicates by ID. A new checkpoint goes to the configured backend, while a backfill that adds a transcript, summary, or attribution to an existing checkpoint lands in whichever backend already holds it.

## Switch Backends

To enable ref-based storage in a new repository, run:

```bash theme={null}
entire enable --checkpoint-backend refs
```

To enable it in an existing Entire-enabled repository, run:

```bash theme={null}
entire configure --checkpoint-backend refs
```

Both commands accept `refs` and `branch`, plus the canonical `git-refs` and `git-branch` that settings store. Add `--local` when the choice should apply only to your clone.

A switch applies to new checkpoints. Checkpoints written before the switch stay exactly where they are and keep resolving through the routing above, so `entire checkpoint list`, `entire checkpoint explain`, attribution, and entire.io continue to serve them. Entire deletes nothing during a switch, and your commands and commit workflow do not change.

Two things do change after a switch to ref-based storage. New checkpoint IDs become ULIDs instead of hex, and the pre-push hook starts pushing queued per-checkpoint refs instead of the `entire/checkpoints/v1` branch. Leave that branch on the remote: it is where readers find every checkpoint captured before the switch.

## Migrate Existing Checkpoints into Refs

Migration is optional, since the routing above already resolves branch-backed checkpoints under a ref-based backend. Migrate when you want the whole history in one format, or when you want to stop carrying the v1 branch.

<Warning>
  Run the migration **before** you switch the backend to refs. The command refuses to run once ref-based storage is primary, because the refs are authoritative at that point and re-importing branch snapshots could only move them backwards.
</Warning>

```bash theme={null}
entire doctor migrate-checkpoints --dry-run
entire doctor migrate-checkpoints
```

The command wraps each checkpoint's current tree in a fresh commit and points its ref at it, keeping the hex ID as the ref name. It does not rewrite the branch commits, and it does not delete the branch. It skips checkpoints it has already converted, so you can re-run it after more branch activity.

| Flag            | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `--dry-run`     | Report what would be migrated without writing refs                      |
| `--remote NAME` | Push migrated refs to this remote instead of the checkpoint sync remote |

Migrated refs are queued for push. Run interactively, the command asks whether to push them now. Run without a terminal, it leaves them queued, and they flush on the next `git push` once ref-based storage is primary. Then switch and push:

```bash theme={null}
entire configure --checkpoint-backend refs
git push
```

<span />

## Auto-Generate Checkpoint Summaries

Checkpoint metadata can carry a summary generated at commit time. Enable it with `strategy_options.summarize.enabled`:

```json .entire/settings.json theme={null}
{
  "strategy_options": {
    "summarize": {
      "enabled": true
    }
  }
}
```

Then choose the provider and model:

```bash theme={null}
entire configure --summarize-provider PROVIDER
entire configure --summarize-model MODEL
```

## Where Storage Settings Are Saved

`entire configure` writes to `.entire/settings.json` by default, so the repository shares the setting. Add `--local` to write `.entire/settings.local.json` instead, which applies only to your clone and takes precedence over project settings.

The `checkpoints` block is a selection, not a merged document: a `checkpoints` block in `.entire/settings.local.json` replaces the one in `.entire/settings.json` outright. The `strategy_options` keys merge by layer as usual. See [Local, Project, and Global Settings](/guides/configuration/settings-layers) for the full table.

## Continue With

<CardGroup>
  <Card title="Store Checkpoints in Another Repository" icon="database" href="/guides/checkpoints/store-checkpoints-in-another-repo">
    Push checkpoint history to a repository separate from your code.
  </Card>

  <Card title="Keep Checkpoints Local" icon="laptop" href="/guides/checkpoints/keep-checkpoints-local">
    Capture checkpoints without pushing them anywhere.
  </Card>

  <Card title="Security and Privacy" icon="shield" href="/security#where-your-data-lives">
    See every location Entire writes to and what redaction covers.
  </Card>

  <Card title="Checkpoint Troubleshooting" icon="wrench" href="/guides/sessions/troubleshooting">
    Fix checkpoints that did not sync or landed in the wrong place.
  </Card>
</CardGroup>


# Inspect Checkpoints
Source: https://docs.entire.io/guides/checkpoints/inspect-checkpoints

Choose how to inspect checkpoint context in entire.io or the Entire CLI.

Use this page when you want to see what happened behind a checkpoint: the commit, prompt, transcript, sessions, files, token usage, and attribution.

<Note>
  Inspecting a checkpoint reads history that Entire already captured. [`entire review`](/cli-reference/review) is a different command: it runs a multi-agent review against your current branch.
</Note>

## Choose a Surface

| Use this                                                  | When you want to                                                                                                       |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [**entire.io**](/guides/checkpoints/inspect-in-entire-io) | Browse checkpoints by repository and branch, inspect sessions visually, read file diffs, or share context with a team. |
| [**Entire CLI**](/guides/checkpoints/inspect-in-cli)      | Work from a terminal, explain a checkpoint or commit, read transcript output, compare token usage, or export JSON.     |

## What to Look For

When you open a checkpoint, check:

* the original prompt or task
* the transcript and tool calls
* files changed by the agent
* file diffs and line attribution
* token usage and session metadata
* whether the checkpoint is linked to the commit you expected

## Continue With

<CardGroup>
  <Card title="Inspect in entire.io" icon="browser" href="/guides/checkpoints/inspect-in-entire-io">
    Open checkpoint details, sessions, and file diffs visually.
  </Card>

  <Card title="Inspect in the CLI" icon="terminal" href="/guides/checkpoints/inspect-in-cli">
    List, explain, and measure checkpoints locally.
  </Card>

  <Card title="Sessions in entire.io" icon="message" href="/guides/sessions/sessions-in-entire-io">
    See the transcript and tool calls behind a checkpoint.
  </Card>

  <Card title="Search Past Work and Code" icon="magnifying-glass" href="/learn/search-past-agent-work">
    Find previous checkpoints, sessions, and commits by meaning.
  </Card>
</CardGroup>


# Inspect Checkpoints in CLI
Source: https://docs.entire.io/guides/checkpoints/inspect-in-cli

List, explain, and measure checkpoints from a terminal.

Use the Entire CLI when you want to work from a terminal, explain a checkpoint or commit, read transcript output, compare token usage, or export checkpoint data as JSON.

## Find a Checkpoint

List checkpoints on the current branch:

```bash theme={null}
entire checkpoint list
```

Add `--json` for a machine-readable listing, or `--session ID` to narrow the list to one session.

When you do not know which checkpoint you want, search by phrase, meaning, or context:

```bash theme={null}
entire checkpoint search "what changed"
```

## Explain a Checkpoint or Commit

Explain a checkpoint by ID, or by an unambiguous prefix of one:

```bash theme={null}
entire checkpoint explain CHECKPOINT_ID
```

A commit-ish works too, and resolves through the commit's `Entire-Checkpoint` trailer:

```bash theme={null}
entire checkpoint explain HEAD~3
```

Add `--full` for the whole parsed transcript, `--raw-transcript` for the JSONL file, or `--short` for the summary alone.

## Generate a Summary

Generate an AI summary for the checkpoint:

```bash theme={null}
entire checkpoint explain CHECKPOINT_ID --generate
```

The `--generate` flag requires the configured provider CLI to be installed and authenticated.

## Measure Token Usage

Report token usage and optimization recommendations for a checkpoint:

```bash theme={null}
entire checkpoint tokens CHECKPOINT_ID
```

The report names the checkpoint, the sessions and agents behind it, the models they used, and the branch, followed by the usage breakdown and the recommendations drawn from it. It reads committed checkpoint metadata through the same resolution path as `entire checkpoint explain`, so an ID prefix or a commit-ish works here as well, and metadata missing locally is fetched from the checkpoint remote.

Compare a checkpoint against an earlier one to see how usage moved:

```bash theme={null}
entire checkpoint tokens CHECKPOINT_ID --compare BASELINE_ID
```

The comparison reports total tokens, input, cache and context replay, cache write, output, and API calls as a delta against the baseline, and qualifies whether the change counts as an observed reduction or increase.

| Flag            | Description                                   |
| --------------- | --------------------------------------------- |
| `--json`        | Output the full report as JSON                |
| `--compare ID`  | Compare against a baseline checkpoint         |
| `--agent-brief` | Print compact next-step guidance for an agent |

`--json` and `--agent-brief` are mutually exclusive.

## Continue With

<CardGroup>
  <Card title="Inspect in entire.io" icon="browser" href="/guides/checkpoints/inspect-in-entire-io">
    Open checkpoint details, sessions, and file diffs visually.
  </Card>

  <Card title="checkpoint" icon="terminal" href="/cli-reference/checkpoint">
    See the full checkpoint command reference.
  </Card>
</CardGroup>


# Inspect Checkpoints in entire.io
Source: https://docs.entire.io/guides/checkpoints/inspect-in-entire-io

Open checkpoint details, sessions, and file diffs in entire.io.

Use entire.io when you want to browse checkpoints visually, inspect sessions, read diffs, or share checkpoint context with a team.

Open [entire.io](https://entire.io), then open the repository that contains the checkpoint.

<Frame>
  <video>
    <source type="video/mp4" />
  </video>
</Frame>

## Open a Checkpoint

1. Choose the branch you want to inspect.
2. Find the commit with the checkpoint.
3. Open the checkpoint detail view.
4. Use **Sessions** to inspect the prompt, transcript, tool activity, and session metadata.
5. Use **Changes** to read the files and diff connected to the checkpoint.

## Branch View

Open a repository to see its branch list. Each branch shows recent commits grouped by day, with checkpoints captured on each commit.

Each checkpoint row shows:

* commit SHA
* commit message
* agent
* code changes
* checkpoint count, when more than one checkpoint is attached
* author

## Checkpoint Detail

Open a checkpoint to inspect the detail view.

<Frame>
  <img alt="Checkpoint detail view in entire.io" />
</Frame>

The header shows the commit SHA, branch, author, agent, file count, AI percentage, and token usage when available.

The detail view has two main tabs:

* **Sessions**: prompts, transcript, tool activity, session metadata, and any sessions that contributed to the checkpoint
* **Changes**: modified files, with a file tree and diff view

Use **Alt + Left Arrow** and **Alt + Right Arrow** to move to the previous or next checkpoint on the same branch.

## Open from a Commit

You can open a checkpoint from a commit URL:

```text theme={null}
https://entire.io/gh/<org>/<repo>/commit/<commit-sha>
```

When a commit has an `Entire-Checkpoint` trailer, the checkpoint ID also appears in the commit message:

```text theme={null}
fix: handle empty repos in dispatch generation

Entire-Checkpoint: 01KVBJCWYA4YW6J5M9GP655HZN
```

You can also open a checkpoint from a session when that session produced or contributed to the checkpoint.

## Continue With

<CardGroup>
  <Card title="Inspect in the CLI" icon="terminal" href="/guides/checkpoints/inspect-in-cli">
    List, explain, and measure checkpoints locally.
  </Card>

  <Card title="Sessions in entire.io" icon="message" href="/guides/sessions/sessions-in-entire-io">
    See the transcript and tool calls behind a checkpoint.
  </Card>
</CardGroup>


# Keep Checkpoints Local
Source: https://docs.entire.io/guides/checkpoints/keep-checkpoints-local

Capture checkpoint history without pushing it to a remote repository.

When checkpoint history should stay on the machine that captured it, turn off automatic checkpoint pushes. Entire keeps capturing checkpoint data and stops sending it to GitHub or another remote.

Use this for local experiments, or for repositories where you do not need checkpoint history available from another device. The tradeoff is that teammates cannot open a local-only checkpoint, and neither can you from another machine.

## Just Your Clone

Write the setting to local settings:

```bash theme={null}
entire configure --local --skip-push-sessions
```

This writes `push_sessions: false` to `.entire/settings.local.json`:

```json .entire/settings.local.json theme={null}
{
  "strategy_options": {
    "push_sessions": false
  }
}
```

`.entire/settings.local.json` is gitignored and takes precedence over project settings, so nobody else in the repository is affected.

## The Whole Repository

To disable checkpoint pushes for everyone working in the repository, use project settings instead:

```bash theme={null}
entire configure --project --skip-push-sessions
```

This writes the same setting to `.entire/settings.json`. Commit that file when the behavior should apply to the whole project. See [Local, Project, and Global Settings](/guides/configuration/settings-layers) for how the layers resolve.

## Turn Pushing Back On

`--skip-push-sessions` only sets the flag; there is no flag that clears it. Set `push_sessions` back to `true` in the settings file you wrote it to, or delete the key to fall back to the default:

```json .entire/settings.local.json theme={null}
{
  "strategy_options": {
    "push_sessions": true
  }
}
```

`entire status` then names the checkpoint sync destination and counts the checkpoints waiting to reach it.


# Store Checkpoints in Another Repository
Source: https://docs.entire.io/guides/checkpoints/store-checkpoints-in-another-repo

Push checkpoint history to a repository separate from your source code.

Configure a [checkpoint remote](/glossary#checkpoint-remote) when checkpoint history should follow a different sharing boundary than your source code, such as keeping agent transcripts private for a public project. Your code continues to live in the main repository, and Entire pushes checkpoint data to the separate one.

## Configure the Checkpoint Remote

Create a separate, empty repository for checkpoint data, then run this from your project:

```bash theme={null}
entire configure --checkpoint-remote github:owner/repo
```

The value uses the format `provider:owner/repo`. Currently, `github` is the supported provider. This writes:

```json .entire/settings.json theme={null}
{
  "strategy_options": {
    "checkpoint_remote": {
      "provider": "github",
      "repo": "owner/repo"
    }
  }
}
```

Commit and push `.entire/settings.json` when the checkpoint remote should apply to the whole project. That setting is what entire.io reads to locate checkpoint data.

## Keep Checkpoints under the Same Owner

Use a checkpoint repository with the same owner or organization as your code repository. Code at `github.com/acme/app` pairs with `github:acme/app-checkpoints`, because `acme` owns both.

Entire won't push checkpoint data to a repository under a different owner. That is intentional: it protects forks, keeping fork contributors from needing write access to the upstream project's checkpoint repository.

## Push Behavior

When you push code, Entire pushes the configured checkpoint data to the checkpoint repository separately, using the same protocol as your Git remote.

If the checkpoint repository cannot be reached, your main Git push still succeeds. Entire keeps the checkpoint data locally and warns that it could not sync.


# Entire-Generated Files
Source: https://docs.entire.io/guides/configuration/entire-files

Decide which Entire-generated files belong in Git and which should stay on your machine.

Entire creates a small set of repository files for configuration, redaction rules, diagnostics, and local runtime state.

Commit files that define shared project behavior. Keep personal overrides, logs, temporary files, and machine-local state out of Git.

## Commit or Keep Local

| Path                          | Commit?                                 | Use for                                                                                                    |
| ----------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `.entire/settings.json`       | Yes, when Entire is part of the project | Shared project settings, such as checkpoint storage, team redaction rules, and default repository behavior |
| `.entire/.gitignore`          | Yes                                     | Keeping local Entire files out of normal commits                                                           |
| `.entire/redactors/`          | Yes, for shared rule packs              | Team redaction rules that should apply to everyone working in the repository                               |
| `.entire/settings.local.json` | No                                      | Personal overrides, debug logging, private rules, and machine-specific settings                            |
| `.entire/redactors/local/`    | No                                      | Personal redaction rule packs                                                                              |
| `.entire/logs/`               | No                                      | Local diagnostic logs                                                                                      |
| `.entire/tmp/`                | No                                      | Temporary runtime files                                                                                    |
| `.entire/metadata/`           | No                                      | Local metadata generated while Entire runs                                                                 |
| `.entire/current_session`     | No                                      | Pointer to your current local session                                                                      |

If you are trying Entire locally before adopting it for the project, keep `.entire/settings.json` local until the team decides to share Entire configuration.

## Files Stored Elsewhere

Checkpoint data is not committed from your working tree. Entire stores checkpoint metadata in Git refs under `refs/entire/checkpoints/`, or on the `entire/checkpoints/v1` branch for repositories on the branch backend, in your code repository or in a configured checkpoint remote. See [Where your data lives](/security#where-your-data-lives).

Global settings live at `~/.config/entire/settings.json`.

Agent hook files live in agent-specific folders, such as `.claude/`, `.codex/`, `.cursor/`, and `.gemini/`.


# Git Hooks
Source: https://docs.entire.io/guides/configuration/git-hooks

Configure the Git hooks Entire uses to capture and sync checkpoint data.

Use this page when `git commit` or `git push` is not creating, linking, or syncing checkpoint data.

Entire uses Git hooks to run during normal Git commands:

* `git commit` links captured agent work to the commit and creates an `Entire-Checkpoint` trailer.
* `git push` syncs checkpoint data after your code push.

If those behaviors do not happen, Git may not be running Entire's hooks, or the hook may not be able to find the `entire` command.

## Start Here If

* a commit did not create a checkpoint
* a commit is missing an `Entire-Checkpoint` trailer
* checkpoint data is not syncing after `git push`
* commits work from Terminal, but not from a GUI Git client
* Git says it cannot find the `entire` command
* hooks were removed, overwritten, or need to be reinstalled
* the `entire` binary moved on your machine
* setup needs to run without prompts

<Note>
  Git hooks are different from [agent hooks](/agents/setup).
  Agent hooks capture the AI session while you work; Git hooks connect that
  captured session to commits and pushes.
</Note>

## Install Git Hooks

For a new repository, run `entire enable` to install the Git hooks Entire needs for commit and push behavior:

```bash theme={null}
entire enable
```

## Reinstall Git Hooks

If hooks were removed, overwritten, or stopped running, reinstall them with:

```bash theme={null}
entire configure --force
```

## GUI Git Clients

Terminal commits can work while GUI commits fail because apps like Xcode, Tower, GitKraken, and Sourcetree may not load your shell `$PATH`.

Configure hooks with the full `entire` binary path:

```bash theme={null}
entire configure --local --absolute-git-hook-path
```

During initial setup, use the same option with `entire enable`:

```bash theme={null}
entire enable --local --absolute-git-hook-path
```

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

```sh theme={null}
# Default
entire hooks git post-commit

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

The setting is written to `.entire/settings.local.json` when you pass `--local`:

```json .entire/settings.local.json theme={null}
{
  "absolute_git_hook_path": true
}
```

Absolute Git hook paths are machine-specific. If you move the `entire` binary, rerun:

```bash theme={null}
entire configure --local --absolute-git-hook-path
```

## Use Non-Interactive Setup

For scripts, CI, or bootstrap flows, run setup in non-interactive mode:

```bash theme={null}
entire enable --yes
```

To select an agent without prompts:

```bash theme={null}
entire enable --yes --agent claude-code
```

## Verify Git Hooks

After changing hook setup, check the repository status and test the Git client you actually use:

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

Then make a test commit and push. If no checkpoint appears, run [checkpoint troubleshooting](/guides/sessions/troubleshooting).


# Logging and Diagnostics
Source: https://docs.entire.io/guides/configuration/logging-and-diagnostics

Configure log verbosity, inspect active settings, and collect diagnostics.

Use this page when you need more detail about what Entire is doing locally or need to confirm which settings are active.

Most diagnostic output is local to your machine. Turn on debug logging temporarily unless the whole team needs the same verbosity.

## Start Here If

Use this page to:

* turn on debug logging while investigating an issue
* confirm which settings Entire is using
* run a repository health check
* view logs or create a diagnostic bundle

## Log Level

`log_level` controls how much detail Entire writes to operational logs. The default is `info`; use `debug` while investigating.

<Tabs>
  <Tab title="Temporary Override">
    Use `ENTIRE_LOG_LEVEL` when you need debug output for one command or one shell session.

    ```bash theme={null}
    ENTIRE_LOG_LEVEL=debug entire status
    ```

    `ENTIRE_LOG_LEVEL` takes precedence over settings files.
  </Tab>

  <Tab title="Local Settings">
    Use local settings for temporary debug logging or machine-specific troubleshooting.

    ```json .entire/settings.local.json theme={null}
    {
      "log_level": "debug"
    }
    ```
  </Tab>

  <Tab title="Project Settings">
    Use project settings only when the whole repository should use the same log level.

    ```json .entire/settings.json theme={null}
    {
      "log_level": "debug"
    }
    ```
  </Tab>
</Tabs>

Supported values are `debug`, `info`, `warn`, and `error`.

## Inspect Active Settings

Run:

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

Use this after editing settings to confirm Entire is reading the value you changed and to see which settings file supplied it.

## Check Repository Health

Run:

```bash theme={null}
entire doctor
```

Use `entire doctor` when sessions look stuck, Git hooks are not firing, checkpoint data is not syncing, or `entire status` shows warnings. It checks repository setup, hook state, checkpoint metadata, and common session problems.

## View or Share Diagnostics

Entire writes local diagnostic logs under `.entire/logs/`. Keep logs local unless someone asks for a specific file or bundle while troubleshooting.

<Tabs>
  <Tab title="View Logs">
    Show recent operational logs with:

    ```bash theme={null}
    entire doctor logs
    ```

    To stream new log lines while you reproduce an issue, run:

    ```bash theme={null}
    entire doctor logs --follow
    ```
  </Tab>

  <Tab title="Create Bundle">
    Create a diagnostic bundle for an issue report with:

    ```bash theme={null}
    entire doctor bundle
    ```

    Diagnostic bundles are redacted by default. Use `--raw` only when support has asked for an unredacted bundle.
  </Tab>
</Tabs>

For other local runtime files under `.entire/`, see [Entire-Generated Files](/guides/configuration/entire-files).

## Trace Slow Hooks

Hooks that take 1.5 seconds or longer trace themselves by default, at WARN level, so a slow hook records its own breakdown with no configuration. Reproduce the slow Git command, then run:

```bash theme={null}
entire doctor trace
```

Use this when `git commit` or `git push` works but feels slower than expected.

Set `ENTIRE_PERF_SLOW_MS=0` to turn automatic tracing off. A [log level](#log-level) above WARN also hides these traces. To trace every hook, including fast ones, set the log level to `debug`.

See [`entire doctor trace`](/cli-reference/doctor#doctor-trace) for `--summary`, `--slow`, and the other flags.

## Verify Logging Changes

After changing logging settings, rerun the command you were investigating and check the logs:

```bash theme={null}
entire doctor logs
```


# Configuration
Source: https://docs.entire.io/guides/configuration/overview

Find the right place to configure Entire.

Use configuration docs when you need to change how Entire behaves in a repository, on your machine, or during Git and agent workflows.

Use the table below to find the guide for the part of Entire you want to configure.

## What Are You Configuring?

| If you want to configure...                                                             | Go to                                                                        |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Local, project, or global settings files                                                | [Local, Project, and Global Settings](/guides/configuration/settings-layers) |
| Which Entire-generated files should be committed or kept local                          | [Entire-Generated Files](/guides/configuration/entire-files)                 |
| Where checkpoint data is stored or pushed                                               | [Session Storage](/guides/checkpoints/checkpoint-storage)                    |
| Git commit and push hooks, including GUI Git clients                                    | [Git Hooks](/guides/configuration/git-hooks)                                 |
| Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Pi, or custom agent integration hooks | [Set Up an Agent](/agents/setup)                                             |
| Redaction rules, PII, telemetry, or checkpoint commit signing                           | [Privacy and Redaction](/guides/configuration/privacy-and-redaction)         |
| Debug logs, diagnostics, or effective settings                                          | [Logging and Diagnostics](/guides/configuration/logging-and-diagnostics)     |
| Saved review profiles for `entire review`                                               | [Review Profiles](/guides/configuration/review-profiles)                     |

## How Configuration Is Layered

Entire merges settings from multiple places. More specific settings win:

1. Local settings: `.entire/settings.local.json`
2. Project settings: `.entire/settings.json`
3. Global settings: `~/.config/entire/settings.json`
4. Defaults

Use project settings for behavior the whole team should share. Use local settings for personal preferences, machine-specific setup, debug logging, or private redaction rules.

## Common Paths

<CardGroup>
  <Card title="Local, Project, and Global Settings" icon="gear" href="/guides/configuration/settings-layers">
    Choose local, project, or global settings for a configuration change.
  </Card>

  <Card title="Entire-Generated Files" icon="folder" href="/guides/configuration/entire-files">
    Decide which Entire-generated files belong in Git and which should stay local.
  </Card>

  <Card title="Session Storage" icon="database" href="/guides/checkpoints/checkpoint-storage">
    See which storage backend a repository uses, switch backends, and migrate.
  </Card>

  <Card title="Fix GUI Git Commits" icon="git-commit" href="/guides/configuration/git-hooks">
    Use absolute Git hook paths when GUI clients cannot find the Entire binary.
  </Card>

  <Card title="Control Privacy Settings" icon="shield" href="/guides/configuration/privacy-and-redaction">
    Configure redaction, telemetry, and checkpoint commit signing.
  </Card>
</CardGroup>


# Privacy and Redaction
Source: https://docs.entire.io/guides/configuration/privacy-and-redaction

Configure redaction layers, image externalization, telemetry, and checkpoint commit signing.

Use this page to configure privacy-related behavior for a repository or for your local machine.

By default, Entire redacts API keys, access tokens, credentialed URLs, database connection strings, and private keys before it writes checkpoint metadata. Secret scanning remains active, but you can choose which pattern scanner Entire uses.

For the threat model, the full list of redaction layers, and what each layer does and does not cover, see [Security & Privacy](/security).

## Start Here If

Use this page to:

* choose secret scanner engines
* add PII or custom redaction rules
* turn on the OpenAI Privacy Filter
* move inline images out of transcripts
* opt in or out of anonymous CLI analytics
* change checkpoint commit signing

## Settings Reference

Every key below lives under `.entire/settings.json` (shared with the team) or `.entire/settings.local.json` (yours alone), except where noted.

| Setting path                                      | Type    | Default               | Effect                                                                                  |
| ------------------------------------------------- | ------- | --------------------- | --------------------------------------------------------------------------------------- |
| `redaction.betterleaks.enabled`                   | boolean | `true`                | Run Betterleaks for secret pattern matching. **Project settings only**                  |
| `redaction.goredact.enabled`                      | boolean | `false`               | Run goredact for secret pattern matching. **Project settings only**                     |
| `redaction.pii.enabled`                           | boolean | `false`               | Turn on [PII redaction](#pii-redaction)                                                 |
| `redaction.pii.email`                             | boolean | `true` when PII is on | Redact email addresses                                                                  |
| `redaction.pii.phone`                             | boolean | `true` when PII is on | Redact phone numbers                                                                    |
| `redaction.pii.address`                           | boolean | `false`               | Redact US street addresses                                                              |
| `redaction.pii.custom_patterns`                   | object  | `{}`                  | Label-to-regex map producing `[REDACTED_<LABEL>]` tokens                                |
| `redaction.custom_redactions`                     | object  | `{}`                  | Label-to-regex map producing the bare `REDACTED` token                                  |
| `redaction.externalize_images`                    | boolean | `false`               | Lift inline base64 images into the checkpoint's `assets/` store                         |
| `redaction.openai_privacy_filter.enabled`         | boolean | `false`               | Run [OPF](#openai-privacy-filter) at push time                                          |
| `redaction.openai_privacy_filter.categories`      | object  | `{}`                  | Which OPF categories to detect. At least one is required when OPF is enabled            |
| `redaction.openai_privacy_filter.timeout_seconds` | number  | `30`                  | Per-invocation timeout for the `opf` process                                            |
| `redaction.openai_privacy_filter.prompt_default`  | string  | `"ask"`               | `ask`, `never`, or `always`                                                             |
| `redaction.openai_privacy_filter.command`         | string  | `"opf"`               | Path to the `opf` binary. **Read only from an untracked `.entire/settings.local.json`** |
| `telemetry`                                       | boolean | `null`                | Anonymous CLI analytics                                                                 |
| `sign_checkpoint_commits`                         | boolean | `true`                | Sign checkpoint commits with your existing Git key                                      |

## Secret Scanner Engines

Layer 2 of Entire's redaction pipeline can run Betterleaks, goredact, or both. Betterleaks runs by default and covers several hundred known secret formats. goredact is off by default and checks a smaller set of provider and contextual token shapes with structural validators such as token length or checksums.

<Note>
  CLI 0.10.2 uses Betterleaks and does not support scanner selection. `v0.10.3-nightly.202608210613.680d64782` first exposes the settings below.
</Note>

Configure scanner selection in the committed project settings file:

```json .entire/settings.json theme={null}
{
  "redaction": {
    "betterleaks": {
      "enabled": true
    },
    "goredact": {
      "enabled": false
    }
  }
}
```

Entire reads these keys only from `.entire/settings.json`. It ignores them in `.entire/settings.local.json` and logs a warning because scanner selection affects the checkpoint content shared through the repository.

<Warning>
  Keep at least one scanner enabled. Entire refuses to load settings when both `redaction.betterleaks.enabled` and `redaction.goredact.enabled` are `false`.
</Warning>

If goredact is the only active scanner and it fails during a scan, Entire stops the checkpoint write. When both scanners run, Entire can complete the write with Betterleaks coverage if goredact fails. See [Redaction Layers](/security#redaction-layers) for the complete pipeline.

## PII Redaction

PII redaction is disabled by default. Enable it when checkpoint metadata may include personal information such as email addresses, phone numbers, or addresses.

<Tabs>
  <Tab title="Project Settings">
    Use project settings when PII redaction should apply to everyone working in the repository.

    ```json .entire/settings.json theme={null}
    {
      "redaction": {
        "pii": {
          "enabled": true,
          "email": true,
          "phone": true,
          "address": false
        }
      }
    }
    ```
  </Tab>

  <Tab title="Local Settings">
    Use local settings when PII redaction should apply only to your machine.

    ```json .entire/settings.local.json theme={null}
    {
      "redaction": {
        "pii": {
          "enabled": true
        }
      }
    }
    ```
  </Tab>

  <Tab title="Custom Patterns">
    Each label becomes part of the replacement token, uppercased. The pattern below produces `[REDACTED_EMPLOYEE_ID]`.

    ```json .entire/settings.json theme={null}
    {
      "redaction": {
        "pii": {
          "enabled": true,
          "custom_patterns": {
            "employee_id": "EMP-\\d{6}"
          }
        }
      }
    }
    ```

    A pattern that reveals an internal ID format is itself sensitive. Put that one in `.entire/settings.local.json`, which stays out of Git.
  </Tab>
</Tabs>

See [PII redaction](/security#pii-redaction-optional) for categories, defaults, and limitations.

## User-Defined Redaction

User-defined redaction lets you redact project-specific strings that Entire's built-in secret detection may not catch. Patterns use Go RE2 syntax, so lookarounds and backreferences are unavailable.

<Tabs>
  <Tab title="Inline Rules">
    Use inline rules for a small number of patterns.

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

    Put shared rules in `.entire/settings.json`. Put private rules in `.entire/settings.local.json`. Entries merge per key, so a local rule can override one shared key and leave the rest alone.
  </Tab>

  <Tab title="Rule Packs">
    Use rule packs for larger reusable sets of redaction rules. Shared packs go in `.entire/redactors/`. Personal packs go in `.entire/redactors/local/`, which `entire enable` keeps gitignored.

    ```yaml .entire/redactors/acme-internal.yaml theme={null}
    name: acme-internal
    version: 1.0.0
    description: Internal ACME service tokens
    rules:
      - id: acme-token
        description: Long-lived ACME service tokens
        regex: 'ACME_TOKEN_[A-Za-z0-9]{20,}'
        samples:
          - { input: "key=ACME_TOKEN_abc123def456ghi789jkl", redacted: true }
          - { input: "ACME_TOKEN_short", redacted: false }
      - id: acme-session
        regex: 'asess_[a-f0-9]{32}'
    ```

    `name` has to match the filename stem. Every pack also needs a `version` and at least one rule carrying an `id` and a `regex`. Entire reads the `.yaml`, `.yml`, and `.json` extensions.
  </Tab>
</Tabs>

Rules take effect on the next CLI or hook invocation. See [User-defined redaction](/security#user-defined-redaction) for rule pack behavior, sample self-tests, and validation details.

## OpenAI Privacy Filter

The OpenAI Privacy Filter is an optional layer that runs a local token-classification model over checkpoints at push time, catching names and other personal data that regex layers miss. It is off by default.

<Warning>
  OPF runs on the `entire/checkpoints/v1` branch backend. Repositories on the ref-based backend, which is the default for repositories enabled with CLI 0.10.0 or later, push without the OPF pass. Check `checkpoints.primary.type` in `.entire/settings.json` before enabling OPF, and see [Session Storage](/guides/checkpoints/checkpoint-storage) to change backends.
</Warning>

### Install `opf`

```bash theme={null}
pip install opf
```

Confirm the binary resolves before you enable the filter, because a missing `opf` aborts your pushes:

```bash theme={null}
opf --help
```

### Enable It

OPF needs at least one category. Enabling the filter with no category selected aborts the push with a configuration error rather than tagging commits as scanned.

```json .entire/settings.json theme={null}
{
  "redaction": {
    "openai_privacy_filter": {
      "enabled": true,
      "categories": {
        "private_person": true
      },
      "timeout_seconds": 30,
      "prompt_default": "ask"
    }
  }
}
```

### Categories

Set a category to `true` to detect it. Entire rejects unknown category names when it loads settings, so a typo surfaces immediately instead of silently disabling a category.

| Category          | Replacement token           | Detects                                    |
| ----------------- | --------------------------- | ------------------------------------------ |
| `private_person`  | `[REDACTED_PERSON]`         | Person names                               |
| `private_email`   | `[REDACTED_EMAIL]`          | Email addresses                            |
| `private_phone`   | `[REDACTED_PHONE]`          | Phone numbers                              |
| `private_address` | `[REDACTED_ADDRESS]`        | Street addresses                           |
| `private_url`     | `[REDACTED_URL]`            | URLs that may identify a person or account |
| `private_date`    | `[REDACTED_DATE]`           | Dates such as a date of birth              |
| `account_number`  | `[REDACTED_ACCOUNT_NUMBER]` | Account, card, and SSN-shaped numbers      |
| `secret`          | `REDACTED`                  | Generic credential-shaped values           |

### Control the Pre-Push Prompt

`prompt_default` decides whether the pre-push hook asks before running OPF.

| Value      | Behavior                                                     |
| ---------- | ------------------------------------------------------------ |
| `"ask"`    | Prompt on an interactive push. This is the default           |
| `"always"` | Run without asking                                           |
| `"never"`  | Skip OPF, and push content redacted by the regex layers only |

Choosing **Always** at the prompt writes `prompt_default: "always"` into `.entire/settings.local.json` for you.

### Override for a Single Push

`ENTIRE_OPF` beats both the setting and the prompt, for that push only.

```bash theme={null}
ENTIRE_OPF=no git push
```

Use `ENTIRE_OPF=no` when a CI runner pushes without `opf` installed. Use `ENTIRE_OPF=yes` to run OPF without a prompt.

### Push Caps

Two environment variables bound how much work one push hands to the model. Both accept a number or `unlimited`.

| Variable                     | Default                 | Guards against                                                                 |
| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------ |
| `ENTIRE_OPF_BOOTSTRAP_LIMIT` | `100` commits           | A first push to a remote with no checkpoint history rewriting hours of commits |
| `ENTIRE_OPF_BATCH_LIMIT`     | `2097152` bytes (2 MiB) | A single commit carrying a very large pasted transcript                        |

```bash theme={null}
ENTIRE_OPF_BATCH_LIMIT=10485760 git push
```

### The `command` Setting

`command` points at a specific `opf` binary. Entire reads it only from `.entire/settings.local.json`, and only when that file is untracked, because the value becomes a process Entire executes during `git push`. Entire logs a rejected `command` and falls back to `$PATH`.

```json .entire/settings.local.json theme={null}
{
  "redaction": {
    "openai_privacy_filter": {
      "command": "/opt/homebrew/bin/opf"
    }
  }
}
```

See [The `command` setting is local-only](/security#openai-privacy-filter-optional) for why this restriction exists.

## Externalized Images

`redaction.externalize_images` moves inline base64 images out of transcript files and into the checkpoint's `assets/` store, replacing each with a short `entire-asset:assets/...` placeholder. It is off by default.

```json .entire/settings.json theme={null}
{
  "redaction": {
    "externalize_images": true
  }
}
```

`ENTIRE_EXTERNALIZE_IMAGES=1` turns it on for one invocation without editing settings.

Turning this on keeps large binary blobs out of `full.jsonl` and `transcript.jsonl`, which makes those files cheaper to read and diff. Restore re-injects images byte-exactly whether or not the flag is on.

<Warning>
  This setting changes where Entire stores image bytes, not whether any layer scans them. No redaction layer reads image content in either arrangement, so an image containing a credential or customer data reaches the remote intact. See [Externalized images](/security#externalized-images).
</Warning>

## Telemetry

Telemetry controls anonymous CLI usage analytics. It does not send prompts, transcripts, source code, file paths, repository names, or flag values.

<Tabs>
  <Tab title="Settings File">
    To opt out in this repository, set:

    ```json .entire/settings.json theme={null}
    {
      "telemetry": false
    }
    ```

    Use `.entire/settings.local.json` instead when the telemetry preference should apply only to your machine.
  </Tab>

  <Tab title="Environment Variable">
    To opt out for a single command or shell environment, set:

    ```bash theme={null}
    ENTIRE_TELEMETRY_OPTOUT=1 entire status
    ```
  </Tab>
</Tabs>

See [Telemetry and analytics](/security#telemetry-and-analytics) for what is and is not captured.

## Checkpoint Commit Signing

Checkpoint commits are signed by default when your Git signing setup is available.

To disable signing for the repository, set:

```json .entire/settings.json theme={null}
{
  "sign_checkpoint_commits": false
}
```

Use `.entire/settings.local.json` instead when the signing preference should apply only to your machine.

See [Checkpoint commit signing](/security#checkpoint-commit-signing) for requirements and best-effort behavior.

## Verify Privacy Settings

After changing privacy settings, run:

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

For redaction changes, run a normal Entire workflow after updating settings. Entire skips an invalid regex or a malformed rule pack and writes the reason to `.entire/logs/entire.log` instead of stopping the CLI.

To confirm OPF ran, push and then check the checkpoint commit for its trailer:

```bash theme={null}
git log -1 --format=%B entire/checkpoints/v1 | grep Entire-OPF-Applied
```


# Review Profiles
Source: https://docs.entire.io/guides/configuration/review-profiles

Configure saved review profiles for entire review.

Use this page when you want `entire review` to use a saved review setup.

A review profile tells Entire which agents should review a branch, which agent should judge the results, and where the final verdict should go.

For command syntax, see the [`review` command reference](/cli-reference/review). For a complete review workflow, see [Review and Recap Agent Work](/learn/review-and-recap-agent-work).

## What This Config Affects

Review profile settings control:

* named profiles you can run with `entire review PROFILE`
* the default review profile
* reviewer agents, judge agent, output mode, task text, model choices, and reviewer slots
* whether the review setup is shared with the repository or kept local to your machine

## Configure Review Profiles

<Tabs>
  <Tab title="Shared Project Profile">
    Use a shared project profile when the team should run the same review setup for this repository.

    Create or update a profile with:

    ```bash theme={null}
    entire review --configure
    ```

    You can also configure a profile without the interactive setup:

    ```bash theme={null}
    entire review --configure \
      --set-agents codex,claude-code \
      --set-judge codex \
      --set-output local
    ```

    By default, `entire review --configure` saves the profile to `.entire/settings.json`.

    Commit `.entire/settings.json` when the review profile should apply to everyone working in the repository.
  </Tab>

  <Tab title="Local Profile">
    Use a local profile for personal reviewer choices, private model preferences, or temporary review experiments.

    Add `--local` when the profile should be saved only on your machine:

    ```bash theme={null}
    entire review --configure --local
    ```

    You can combine `--local` with non-interactive setup flags:

    ```bash theme={null}
    entire review --configure --local \
      --set-agents codex \
      --set-judge codex \
      --set-output local
    ```

    Local review profiles are saved to `.entire/settings.local.json`.

    Local settings have higher priority than shared project settings, so use them when your review setup should not affect teammates.
  </Tab>
</Tabs>

## Review Profile Settings

`entire review --configure` manages these setting paths:

| Setting path             | Type   | Use for                                                                                 |
| ------------------------ | ------ | --------------------------------------------------------------------------------------- |
| `review_default_profile` | string | The default review profile name                                                         |
| `review_profiles`        | object | Named review profiles and their reviewer, judge, output, task, model, and slot settings |

Use `entire review --configure` or `entire review --edit` to update review profiles when possible. The profile JSON can contain nested reviewer and model settings, so the CLI is the safest way to keep the shape valid.

## Modify Review Profiles

Use the review command to change saved profile settings:

```bash theme={null}
entire review --configure
entire review --configure --set-agents codex,claude-code --set-judge codex
entire review --edit
```

Use `--local` when the change should be personal:

```bash theme={null}
entire review --configure --local
```

## Verify Review Profiles

After configuring review profiles, list them:

```bash theme={null}
entire review --list
```

To see the reviewers for the selected profile, run:

```bash theme={null}
entire review --agents
```

Run a named profile with:

```bash theme={null}
entire review general
```

If the review uses the wrong agents or output mode, check whether a local profile in `.entire/settings.local.json` is overriding the shared profile in `.entire/settings.json`.


# Local, Project, and Global Settings
Source: https://docs.entire.io/guides/configuration/settings-layers

Configure shared repository behavior, personal overrides, and the files Entire writes under .entire.

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

Use this page when you are deciding whether a setting should apply to everyone on the project, only to your machine, or to all repositories you work in.

<Tabs>
  <Tab title="Local Settings">
    Local settings have the highest priority and are used for personal preferences, private rules, machine-specific paths, and temporary debugging.

    ## Local Settings File

    Local settings are stored in `.entire/settings.local.json` and are automatically ignored by Git.

    Local settings are merged with project settings. You only need to specify the settings you want to override:

    ```json .entire/settings.local.json theme={null}
    {
      "log_level": "debug",
      "telemetry": false
    }
    ```

    ## Local Settings Reference

    Use these settings locally when the behavior should not affect teammates.

    | Setting path                              | Type         | Use for                                                                    | Learn more                                                                                                          |
    | ----------------------------------------- | ------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
    | `commit_linking`                          | string       | Personal commit-linking behavior during `git commit`                       | [Capture Sessions and Their Checkpoints](/guides/checkpoints/capture-checkpoints#link-future-commits-automatically) |
    | `strategy_options.push_sessions`          | boolean      | Checkpoint push behavior only on your machine                              | [Checkpoint Storage](/guides/checkpoints/keep-checkpoints-local)                                                    |
    | `strategy_options.checkpoint_remote`      | object       | Personal checkpoint remote while testing storage behavior                  | [Checkpoint Storage](/guides/checkpoints/store-checkpoints-in-another-repo)                                         |
    | `redaction.pii.enabled`                   | boolean      | Optional PII redaction for your own captured sessions                      | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#pii-redaction)                                  |
    | `redaction.custom_redactions`             | object       | Private regex redaction rules that should not be committed                 | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#user-defined-redaction)                         |
    | `redaction.externalize_images`            | boolean      | Move inline base64 images into the checkpoint asset store on your machine  | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#externalized-images)                            |
    | `redaction.openai_privacy_filter`         | object       | Personal OpenAI Privacy Filter settings, including `prompt_default`        | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#openai-privacy-filter)                          |
    | `redaction.openai_privacy_filter.command` | string       | Path to your `opf` binary. Read only from an untracked local settings file | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#the-command-setting)                            |
    | `telemetry`                               | boolean/null | Personal analytics preference in this repository                           | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#telemetry)                                      |
    | `sign_checkpoint_commits`                 | boolean      | Personal checkpoint commit signing preference                              | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#checkpoint-commit-signing)                      |
    | `log_level`                               | string       | Temporary debug logging without changing team settings                     | [Logging and Diagnostics](/guides/configuration/logging-and-diagnostics#log-level)                                  |
    | `external_agents`                         | boolean      | Agent integration discovery only on your machine                           | [Set Up an Agent](/agents/setup#agent-integrations)                                                                 |
    | `absolute_git_hook_path`                  | boolean      | Full `entire` binary path in Git hooks for GUI Git clients on your machine | [Git Hooks](/guides/configuration/git-hooks#gui-git-clients)                                                        |

    ## Modify Local Settings

    <Tabs>
      <Tab title="Use the CLI">
        Add `--local` when the command should write to `.entire/settings.local.json`.

        ```bash theme={null}
        entire configure --local --telemetry=false
        entire configure --local --skip-push-sessions
        entire configure --local --absolute-git-hook-path
        ```

        If a setting does not have a CLI flag, edit `.entire/settings.local.json` directly.
      </Tab>

      <Tab title="Edit JSON">
        Edit `.entire/settings.local.json` directly:

        ```bash theme={null}
        vim .entire/settings.local.json
        ```

        Top-level settings are written directly:

        ```json .entire/settings.local.json theme={null}
        {
          "log_level": "debug"
        }
        ```

        Dotted setting paths are written as nested objects:

        ```json .entire/settings.local.json theme={null}
        {
          "redaction": {
            "custom_redactions": {
              "private_codename": "PROJECT_[A-Z]{4}"
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    ## Verify Local Settings

    After editing local settings, run:

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

    Use this to confirm Entire is still reading the repository configuration. If the behavior does not match `.entire/settings.local.json`, check the setting name and JSON nesting. Local settings override project and global settings for the same setting path.
  </Tab>

  <Tab title="Project Settings">
    Project settings apply to the current repository and are used for shared behavior such as checkpoint storage, team redaction rules, and default repository behavior.

    ## Project Settings File

    Project settings are stored in `.entire/settings.json`.

    When Entire creates project settings, the file starts with:

    ```json .entire/settings.json theme={null}
    {
      "enabled": true
    }
    ```

    Most projects can start here. Add settings only when the repository should share that behavior.

    ## Project Settings Reference

    Use these settings in `.entire/settings.json` when the behavior should apply to the whole project.

    | Setting path                              | Type         | Default                        | Description                                                                                 | Learn more                                                                                                          |
    | ----------------------------------------- | ------------ | ------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
    | `enabled`                                 | boolean      | `true`                         | Whether Entire is active in this repository                                                 | [Local, Project, and Global Settings](/guides/configuration/settings-layers#project-settings-file)                  |
    | `commit_linking`                          | string       | `"prompt"`                     | Controls whether Entire prompts before linking a Git commit to recent agent session context | [Capture Sessions and Their Checkpoints](/guides/checkpoints/capture-checkpoints#link-future-commits-automatically) |
    | `strategy_options.push_sessions`          | boolean      | `true`                         | Automatically push checkpoint data when someone runs `git push`                             | [Session Storage](/guides/checkpoints/checkpoint-storage#store-checkpoints-with-your-code)                          |
    | `strategy_options.checkpoint_remote`      | object       | `null`                         | Push checkpoint data to a separate repository                                               | [Checkpoint Storage](/guides/checkpoints/store-checkpoints-in-another-repo)                                         |
    | `strategy_options.summarize.enabled`      | boolean      | `false`                        | Auto-generate checkpoint summaries at commit time                                           | [Session Storage](/guides/checkpoints/checkpoint-storage#auto-generate-checkpoint-summaries)                        |
    | `redaction.betterleaks.enabled`           | boolean      | `true`                         | Run Betterleaks for secret pattern matching                                                 | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#secret-scanner-engines)                         |
    | `redaction.goredact.enabled`              | boolean      | `false`                        | Run goredact for secret pattern matching                                                    | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#secret-scanner-engines)                         |
    | `redaction.pii.enabled`                   | boolean      | `false`                        | Enable optional PII redaction on top of always-on secret redaction                          | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#pii-redaction)                                  |
    | `redaction.custom_redactions`             | object       | `{}`                           | Add shared regex rules that replace matches with `REDACTED`                                 | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#user-defined-redaction)                         |
    | `redaction.externalize_images`            | boolean      | `false`                        | Move inline base64 images out of transcripts into the checkpoint asset store                | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#externalized-images)                            |
    | `redaction.openai_privacy_filter.enabled` | boolean      | `false`                        | Run the OpenAI Privacy Filter over checkpoints at push time                                 | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#openai-privacy-filter)                          |
    | `checkpoints.primary.type`                | string       | `git-refs` on first-time setup | Checkpoint storage backend: `git-refs` or `git-branch`                                      | [Session Storage](/guides/checkpoints/checkpoint-storage)                                                           |
    | `telemetry`                               | boolean/null | `null`                         | Send anonymous usage analytics for this repository                                          | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#telemetry)                                      |
    | `sign_checkpoint_commits`                 | boolean      | `true`                         | Sign checkpoint commits using your existing Git signing key                                 | [Privacy and Redaction](/guides/configuration/privacy-and-redaction#checkpoint-commit-signing)                      |
    | `log_level`                               | string       | `"info"`                       | Log verbosity: `debug`, `info`, `warn`, `error`                                             | [Logging and Diagnostics](/guides/configuration/logging-and-diagnostics#log-level)                                  |
    | `external_agents`                         | boolean      | `false`                        | Enable discovery of `entire-agent-<name>` agent integrations from `$PATH`                   | [Set Up an Agent](/agents/setup#agent-integrations)                                                                 |
    | `absolute_git_hook_path`                  | boolean      | `false`                        | Embed the full `entire` binary path in Git hooks for GUI Git clients                        | [Git Hooks](/guides/configuration/git-hooks#gui-git-clients)                                                        |

    ## Modify Project Settings

    To enable agent integration discovery in project settings, add:

    ```json .entire/settings.json theme={null}
    {
      "external_agents": true
    }
    ```

    <Tabs>
      <Tab title="Use the CLI">
        Add `--project` when the command should write to `.entire/settings.json`.

        ```bash theme={null}
        entire configure --project --checkpoint-remote github:owner/repo
        entire configure --project --skip-push-sessions
        entire configure --project --telemetry=false
        ```

        If a setting does not have a CLI flag, edit `.entire/settings.json` directly.
      </Tab>

      <Tab title="Edit JSON">
        Edit `.entire/settings.json` directly:

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

        Top-level settings are written directly:

        ```json .entire/settings.json theme={null}
        {
          "telemetry": false
        }
        ```

        Dotted setting paths are written as nested objects:

        ```json .entire/settings.json theme={null}
        {
          "strategy_options": {
            "push_sessions": false
          }
        }
        ```
      </Tab>
    </Tabs>

    ## Verify Project Settings

    After editing project settings, run:

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

    Use this to confirm Entire is still reading the repository configuration. If the behavior does not match `.entire/settings.json`, check for an override in `.entire/settings.local.json`. Local settings have higher priority than project settings.
  </Tab>

  <Tab title="Global Settings">
    Global settings apply to all repositories and are used for personal defaults that should apply across projects.

    ## Global Settings File

    Global settings are stored in `~/.config/entire/settings.json`.

    Use global settings for personal defaults that should apply across repositories.

    Example:

    ```json ~/.config/entire/settings.json theme={null}
    {
      "telemetry": false
    }
    ```

    ## Global Settings Reference

    Use global settings for personal defaults that should apply unless a project or local setting overrides them.

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

    ## Modify Global Settings

    <Tabs>
      <Tab title="Use the CLI">
        `entire configure` updates repository settings. There is no global flag for `entire configure`, so edit `~/.config/entire/settings.json` directly.
      </Tab>

      <Tab title="Edit JSON">
        Create the config directory if it does not exist, then edit the file:

        ```bash theme={null}
        mkdir -p ~/.config/entire
        vim ~/.config/entire/settings.json
        ```

        Example:

        ```json ~/.config/entire/settings.json theme={null}
        {
          "telemetry": false
        }
        ```
      </Tab>
    </Tabs>

    ## Verify Global Settings

    After editing global settings, run this from an Entire-enabled repository:

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

    Use this to confirm Entire is still reading configuration. Global settings apply only when the same setting is not set in `.entire/settings.json` or `.entire/settings.local.json`.
  </Tab>
</Tabs>


# Dispatches in CLI
Source: https://docs.entire.io/guides/dispatches/dispatches-in-cli

Use `entire dispatch` to generate markdown summaries from the terminal.

Use the CLI when you want a dispatch from the terminal, in a script, or as part of an agent workflow.

<Frame>
  <div>
    <iframe title="Entire Dispatch CLI demo" />
  </div>
</Frame>

```bash theme={null}
entire dispatch [flags]
```

If you run `entire dispatch` with no flags in an interactive terminal, Entire opens a guided wizard. In non-interactive contexts, or when you provide flags, it prints markdown directly.

## Cloud Dispatch

Cloud dispatch is the default mode. It uses Entire server data for repositories you can access.

Generate a dispatch for recent work:

```bash theme={null}
entire dispatch
```

Limit the dispatch to specific repositories:

```bash theme={null}
entire dispatch --repos entireio/cli,entireio/entire.io
```

Set a time window:

```bash theme={null}
entire dispatch --since 7d
```

## Local Dispatch

Use local mode when you want to summarize local repository data with your locally installed agent CLI.

Generate a local dispatch from the current repository:

```bash theme={null}
entire dispatch --local
```

Include every existing local branch:

```bash theme={null}
entire dispatch --local --all-branches
```

`--all-branches` only applies to local mode. Renamed or deleted branches are skipped.

## Customize the Voice

Use `--voice` to choose a preset or provide a literal description:

```bash theme={null}
entire dispatch --voice neutral
```

```bash theme={null}
entire dispatch --voice "Audience: product team. Focus on user-visible changes."
```

## Common Flags

| Flag                      | Description                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--repos <owner/repo>`    | Cloud repo slugs, up to 5. Use comma-separated values for multiple repos.                                        |
| `--since TIME`            | Start of the time window. Accepts Go durations, relative times, or ISO dates. Defaults to `7d`.                  |
| `--until TIME`            | End of the time window. Defaults to now.                                                                         |
| `--voice PRESET_OR_TEXT`  | Voice preset name or custom text.                                                                                |
| `--local`                 | Generate with local repository data instead of Entire server data.                                               |
| `--all-branches`          | Include every existing local branch. Only valid with `--local`.                                                  |
| `--agent NAME`            | Local text-generation agent to use. Only valid with `--local`.                                                   |
| `-j, --jurisdiction SLUG` | Jurisdiction, such as `us` or `eu`, whose cell generates the cloud dispatch. Defaults to your home jurisdiction. |

For every flag, see the [`dispatch` command reference](/cli-reference/dispatch).

## Continue With

<CardGroup>
  <Card title="Dispatches in entire.io" icon="globe" href="/guides/dispatches/dispatches-in-entire-io">
    Generate and preview dispatches in the web interface.
  </Card>

  <Card title="dispatch" icon="terminal" href="/cli-reference/dispatch">
    See the full command reference.
  </Card>
</CardGroup>


# Dispatches in entire.io
Source: https://docs.entire.io/guides/dispatches/dispatches-in-entire-io

Generate and preview Dispatches from the Entire web interface.

Use entire.io when you want a visual flow for choosing repositories, setting a time window, shaping the voice, and copying a rendered markdown summary.

<Frame>
  <div>
    <iframe title="Dispatches on Entire Web" />
  </div>
</Frame>

The recording above comes from [Entire Dispatch 0x000C](https://entire.io/blog/entire-dispatch-0x000c), which introduced Dispatches in entire.io.

## Open Dispatches

Open Dispatches from the entire.io sidebar, command palette, or `g d` shortcut.

## Choose the Scope

Choose the repositories and time window you want summarized.

* Select up to 5 repositories per dispatch
* If you select one repository, choose up to 5 branches
* If you select multiple repositories, Dispatches use each repository's default branch
* Choose a time window such as 1 day, 7 days, 14 days, or 30 days

Use one repository and specific branches for a focused project update. Use multiple repositories for a broader team update.

## Choose the Voice

Choose a voice preset or provide custom guidance.

| Voice     | Use it when                                                   |
| --------- | ------------------------------------------------------------- |
| `neutral` | You want straightforward product or engineering update prose. |
| `marvin`  | You want a drier, more opinionated tone.                      |
| `custom`  | You want to name the audience, purpose, or framing yourself.  |

Custom guidance is useful for instructions like `Audience: product team. Focus on user-visible changes only.`

## Generate and Copy

Click **Generate dispatch**. Entire returns markdown and renders the preview inline.

The preview includes the generated summary plus scope metadata, such as the repositories, branches, and date window covered. Copy the markdown when you are ready to share it.

## Continue With

<CardGroup>
  <Card title="Dispatches in CLI" icon="terminal" href="/guides/dispatches/dispatches-in-cli">
    Generate dispatches from the terminal.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/dispatches/troubleshooting">
    Fix missing Dispatches, empty summaries, and scope issues.
  </Card>
</CardGroup>


# Dispatches
Source: https://docs.entire.io/guides/dispatches/overview

Summarize recent agent work into a shareable markdown update.

Dispatches turn recent agent work into a readable summary you can share with teammates, reviewers, product partners, or anyone who needs to understand what changed.

Use a dispatch when you want the story of recent work without opening every checkpoint, session, commit, and branch by hand.

## What Dispatches Summarize

Dispatches can summarize recent work from:

* checkpoints created from agent-assisted commits
* sessions, prompts, transcripts, and tool activity
* commits connected to captured agent work
* one repository, multiple repositories, or a narrower branch and time window

A dispatch is a summary. Use it to get oriented, write status updates, or prepare a handoff. Use [checkpoints](/guides/sessions/overview#what-is-a-checkpoint) when you need to inspect the exact prompt, transcript, files, and diff behind a change.

## Where to Generate Dispatches

| Surface                                                 | Use it when                                                                                                     |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [entire.io](/guides/dispatches/dispatches-in-entire-io) | You want to choose repositories, preview the markdown visually, and copy a stakeholder-ready update.            |
| [Entire CLI](/guides/dispatches/dispatches-in-cli)      | You are already in the terminal, want scriptable markdown output, or need a local summary from repository data. |

## Common Uses

* Write a weekly engineering update from agent-assisted work
* Summarize progress across several repositories
* Create a focused recap for one repo and branch
* Prepare a non-technical brief from technical work
* Catch up before reviewing a branch or continuing a project

## Before You Start

Dispatches work best when:

* Entire is capturing agent work in the repositories you choose
* checkpoints or sessions have been pushed or are available locally
* you choose a time window that contains recent activity
* you are authenticated with `entire login` when using cloud-backed CLI dispatches

## Continue With

<CardGroup>
  <Card title="Dispatches in entire.io" icon="globe" href="/guides/dispatches/dispatches-in-entire-io">
    Generate and preview dispatches in the web interface.
  </Card>

  <Card title="Dispatches in CLI" icon="terminal" href="/guides/dispatches/dispatches-in-cli">
    Generate markdown dispatches from your terminal.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/dispatches/troubleshooting">
    Fix missing Dispatches, thin summaries, scope issues, and CLI mode conflicts.
  </Card>
</CardGroup>


# Troubleshooting
Source: https://docs.entire.io/guides/dispatches/troubleshooting

Fix common Dispatches visibility, scope, output, and CLI mode issues.

Use this page when Dispatches are missing, the summary is empty or too thin, or the CLI command rejects the scope you provided.

<AccordionGroup>
  <Accordion title="Dispatches Are Not Visible in entire.io">
    Dispatches may be enabled gradually for entire.io accounts.

    If you do not see Dispatches in the sidebar or command palette:

    * confirm you are signed in to the right entire.io account
    * confirm the workspace has access to Dispatches
    * use `entire dispatch` from the CLI while web access is unavailable
  </Accordion>

  <Accordion title="The Summary Is Empty or Too Thin">
    Check whether the selected scope contains captured work.

    Try this:

    * choose a longer time window
    * choose a repository or branch that has recent checkpoints or sessions
    * push recent checkpoint data if you expect cloud dispatches to include it
    * use local mode if the work exists locally but has not been pushed

    ```bash theme={null}
    entire dispatch --local
    ```
  </Accordion>

  <Accordion title="The Wrong Repositories or Branches Are Included">
    Check the dispatch scope.

    In entire.io, branch selection appears only when you select one repository. If you select multiple repositories, Dispatches use each repository's default branch.

    In the CLI, pass cloud repository slugs with `owner/repo` format:

    ```bash theme={null}
    entire dispatch --repos entireio/cli,entireio/entire.io
    ```
  </Accordion>

  <Accordion title="`--repos` Does Not Work with `--local`">
    `--repos` is for cloud dispatches. `--local` reads from the local repository instead.

    Use cloud mode for specific remote repositories:

    ```bash theme={null}
    entire dispatch --repos entireio/cli
    ```

    Use local mode for the current checkout:

    ```bash theme={null}
    entire dispatch --local
    ```
  </Accordion>

  <Accordion title="`--all-branches` Did Not Include a Branch">
    `--all-branches` only includes existing local branches in local mode. Renamed or deleted branches are skipped.

    Check local branches first:

    ```bash theme={null}
    git branch
    ```

    Then run:

    ```bash theme={null}
    entire dispatch --local --all-branches
    ```
  </Accordion>

  <Accordion title="The Voice or Audience Is Wrong">
    Use a preset voice or provide custom guidance.

    ```bash theme={null}
    entire dispatch --voice neutral
    ```

    ```bash theme={null}
    entire dispatch --voice "Audience: leadership. Focus on impact and risks."
    ```
  </Accordion>

  <Accordion title="Still Stuck?">
    Include these details when asking for help:

    * `entire version`
    * whether you used entire.io or the CLI
    * the repositories and branches you selected
    * the time window
    * whether the work appears in checkpoints or sessions
    * the full error message, if the CLI failed

    You can file an issue at [github.com/entireio/cli](https://github.com/entireio/cli) or ask in the [Entire Discord](https://discord.gg/jZJs3Tue4S).
  </Accordion>
</AccordionGroup>

## Continue With

<CardGroup>
  <Card title="Dispatches" icon="newspaper" href="/guides/dispatches/overview">
    Learn what Dispatches summarize and when to use them.
  </Card>

  <Card title="Dispatches in CLI" icon="terminal" href="/guides/dispatches/dispatches-in-cli">
    Generate dispatches from the terminal.
  </Card>
</CardGroup>


# How entire-graph Works
Source: https://docs.entire.io/guides/graph/how-graph-works

Understand how entire-graph analyzes a repository, guides your coding agent, and works with Search.

Once entire-graph is [installed and enabled for a repository](/guides/graph/set-up-graph), your coding agent can use it to investigate the codebase during a task. entire-graph analyzes the repository locally and returns relevant files, symbols, and relationships. Your agent then inspects the source before answering a question or making changes.

## What entire-graph Analyzes

entire-graph maps files, symbols, and relationships such as callers, callees, and type usage. It also uses a limited amount of Git history to identify files that often change together.

entire-graph runs locally and does not send your code to a model or external service. It can reuse a local cache to make later queries faster.

## When to Use entire-graph or Search

entire-graph and [Search](/guides/search/overview) can both help your agent find code, but they serve different purposes.

|                          | entire-graph                                              | Search                                                          |
| ------------------------ | --------------------------------------------------------- | --------------------------------------------------------------- |
| Find code                | Finds and ranks relevant code in the current repository   | Finds matching code across indexed repositories                 |
| Understand relationships | Traces callers, callees, type usage, and potential impact | Returns code locations without tracing their relationships      |
| Find past context        | Uses limited Git history to identify related code         | Finds previous commits, sessions, and agent work                |
| Where it runs            | Runs locally without sending your code elsewhere          | Uses Entire's online search and requires an internet connection |
| Best used for            | Understanding how code connects before making a change    | Locating code or learning the history behind it                 |

The two can work together. Your agent might use Search to locate code or find previous work, then use entire-graph to trace how that code connects and what a change could affect.

## What entire-graph Might Not Find

How deeply entire-graph can analyze your code depends on the language, and coverage comes in two tiers.

**Semantic languages** are parsed for relationships, so `impact`, `neighbors`, and `def` can trace callers, callees, and type usage. There are 36:

Bash, C, C#, C++, CUE, Clojure, ClojureScript, Dart, Elixir, Erlang, F#, Go, Groovy, HCL, Haskell, Java, JavaScript, Julia, Kotlin, Lua, OCaml, Objective-C, PHP, Perl, Protocol Buffers, Python, R, Ruby, Rust, SQL, Scala, Swift, TypeScript, YAML, Zig, Zsh

**Inventory-only filetypes** are recognized for file and symbol structure without call or type analysis. There are 149 of these, which is why a file can appear in `search` results while `neighbors` returns no relationships for the symbols inside it.

<Note>
  These counts describe the current release. Run `entire graph capabilities --json` to see what your installed build supports, and read `semantic_languages` for the tier that traces relationships.
</Note>

Because entire-graph analyzes source without running it, it may miss connections created dynamically through interfaces, reflection, generated code, or other runtime behavior. Treat its results as a focused starting point and verify them against the source.

## Continue With

<CardGroup>
  <Card title="Use entire-graph with Your Coding Agent" icon="robot" href="/guides/graph/use-graph">
    Learn what to ask and what happens after you prompt your agent.
  </Card>

  <Card title="Install and Enable entire-graph" icon="wrench" href="/guides/graph/set-up-graph">
    Install entire-graph and add its instructions to a repository.
  </Card>

  <Card title="entire-graph CLI Reference" icon="terminal" href="/cli-reference/graph">
    Review entire-graph commands and options.
  </Card>
</CardGroup>


# Overview
Source: https://docs.entire.io/guides/graph/overview

entire-graph, a plugin for the Entire CLI that helps your agents find their answers fast and saves token spend by up to 71%.

entire-graph is an installable [plugin](/cli-reference/plugin) for the [Entire CLI](/cli-reference). It analyzes the repository your agent is working in and gives your agent a map of relevant code and relationships. Your agent can use that map to find the right code, understand how it connects, and assess what a change could affect before editing.

## Benefits of Using entire-graph

* Spend less time pointing your agent to the right files, leaving more room in its context window to solve the task.
* Help your agent understand how the code works by showing how functions, types, and other symbols connect.
* Make safer changes by identifying code that could be affected before your agent starts editing.
* Get answers grounded in specific source locations that your agent can inspect and verify.

## How to Use entire-graph

After you [install entire-graph and enable it for a repository](/guides/graph/set-up-graph), ask your coding agent where code lives, how it connects, or what a change could affect.

See [Use entire-graph with Your Coding Agent](/guides/graph/use-graph) for common prompts, the agent workflow, and an example result.

## Continue With

<CardGroup>
  <Card title="Install and Enable entire-graph" icon="wrench" href="/guides/graph/set-up-graph">
    Install entire-graph and add its instructions to a repository.
  </Card>

  <Card title="Use entire-graph with Your Coding Agent" icon="robot" href="/guides/graph/use-graph">
    Learn what to ask and what happens after you prompt your agent.
  </Card>

  <Card title="How entire-graph Works" icon="diagram-project" href="/guides/graph/how-graph-works">
    Learn how entire-graph maps your code and works with Search.
  </Card>

  <Card title="entire-graph CLI Reference" icon="terminal" href="/cli-reference/graph">
    Review entire-graph commands and options.
  </Card>

  <Card title="entire-graph Troubleshooting" icon="stethoscope" href="/guides/graph/troubleshooting">
    Fix installation, adoption, cache, and coverage problems.
  </Card>
</CardGroup>


# Install and Enable entire-graph
Source: https://docs.entire.io/guides/graph/set-up-graph

Install entire-graph on your machine, add its instructions to a repository, and verify your coding agent can use it.

## Before You Start

Make sure you have:

* [Entire CLI installed](/installation) and [updated](/installation#install-and-update-entire) to version 0.10.0 or later
* Git 2.36 or later on your `PATH`
* a local Git repository
* a coding agent that reads instructions from `AGENTS.md` or `CLAUDE.md`

<Note>
  entire-graph requires Git 2.36 or later because it uses the single-session
  object protocol that version added to check an object's type before reading
  its contents. Run `git --version` to check your version. If it is older,
  queries fail with a `git cat-file --batch-command` error; see [entire-graph
  Troubleshooting](/guides/graph/troubleshooting#install-and-setup).
</Note>

## 1. Install entire-graph

Install entire-graph on your machine with the Entire CLI:

```bash theme={null}
entire plugin install graph
```

Verify the installation with [`entire graph version`](/cli-reference/graph#graph-version):

```bash theme={null}
entire graph version
```

If the command prints a version number, entire-graph is installed. See [`entire plugin`](/cli-reference/plugin) to install a specific version, upgrade entire-graph, or remove it from your machine.

## 2. Enable entire-graph in Your Repository

entire-graph needs to add instructions that tell your coding agent when and how to use it. From the root of your repository, run [`entire graph init-agents`](/cli-reference/graph#graph-init-agents):

```bash theme={null}
entire graph init-agents --repo .
```

This creates or updates three files, and it treats the guide differently from the two agent instruction files:

* `.entire/graph-agent.md` is the agent operating guide. entire-graph generates it in full and regenerates it in full on every successful rerun.
* `AGENTS.md` and `CLAUDE.md` are created if they do not exist. If either file is already present, entire-graph adds or replaces a single managed block between `<!-- entire-graph:begin -->` and `<!-- entire-graph:end -->` markers and preserves everything outside those markers.

<Warning>
  Do not edit `.entire/graph-agent.md`. It is plugin-managed, so the next
  `entire graph init-agents` run overwrites it and your changes are lost. Put
  repository-specific instructions outside the `entire-graph` markers in
  `AGENTS.md` or `CLAUDE.md` instead, where reruns preserve them.
</Warning>

## 3. Commit the Instruction Files

Add the entire-graph instruction files to your repository:

```bash theme={null}
git add .entire/graph-agent.md AGENTS.md CLAUDE.md
git commit -m "Enable entire-graph"
```

Committing these files gives everyone working in the repository the same entire-graph instructions.

## 4. Start a New Coding Agent Session

Start a new session from your repository to load the entire-graph instructions.

## 5. Verify entire-graph Is Working

Ask your coding agent to find code or trace a relationship in the repository. For example:

```text theme={null}
Use entire-graph to find where route matching is implemented and trace what calls it.
```

Your agent should run a entire-graph command, inspect the relevant source files, and include specific file locations in its answer.

If your agent does not use entire-graph or the command fails, see [entire-graph Troubleshooting](/guides/graph/troubleshooting).

## Continue With

<CardGroup>
  <Card title="Use entire-graph with Your Coding Agent" icon="robot" href="/guides/graph/use-graph">
    Learn what to ask and what happens after you prompt your agent.
  </Card>

  <Card title="How entire-graph Works" icon="chart-network" href="/guides/graph/how-graph-works">
    Learn how entire-graph maps your code and guides your agent.
  </Card>

  <Card title="entire-graph CLI Reference" icon="terminal" href="/cli-reference/graph">
    Review entire-graph commands and options.
  </Card>

  <Card title="entire-graph Troubleshooting" icon="stethoscope" href="/guides/graph/troubleshooting">
    Fix installation, agent adoption, and cache problems.
  </Card>
</CardGroup>


# entire-graph Troubleshooting
Source: https://docs.entire.io/guides/graph/troubleshooting

Fix entire-graph install, activation, adoption, cache, and coverage problems.

Use this page when entire-graph is not installed, not being used by your agent, or not returning what you expect.

## Install and Setup

<AccordionGroup>
  <Accordion title="`entire graph` prints the main Entire help instead of running">
    The plugin is not installed. The CLI does not recognize `graph` as a command, so it falls back to its own help output.

    ```bash theme={null}
    entire plugin install graph
    entire graph version
    ```

    Confirm it landed:

    ```bash theme={null}
    entire plugin list
    ```
  </Accordion>

  <Accordion title="Queries fail with a `git cat-file --batch-command` error">
    Your Git is older than 2.36. entire-graph uses the single-session object protocol that Git 2.36 added to check an object's type before reading its contents, so queries cannot run without it. The error names the requirement:

    ```text theme={null}
    git cat-file --batch-command unavailable (Git 2.36 or newer required)
    ```

    Check your version, and upgrade Git if it is older:

    ```bash theme={null}
    git --version
    ```

    If several Git installations are present, confirm which one entire-graph resolves on your `PATH`:

    ```bash theme={null}
    command -v git
    ```
  </Accordion>

  <Accordion title="`entire graph version` prints `dev`">
    You are running an unversioned local build, usually from `scripts/install-local.sh` or a manual `go build`. That is expected during development and not expected otherwise.

    Reinstall a released build:

    ```bash theme={null}
    entire plugin install graph --force
    ```
  </Accordion>

  <Accordion title="`plugin install` refuses the download">
    Releases are verified against the release's `checksums.txt`. A release that publishes no checksums is refused.

    If you trust the source and understand the tradeoff, pass `--allow-unverified`. Otherwise check that you have the right repository URL.

    Installing from a URL that is not in the plugin index also asks for confirmation. In a script or CI, add `--yes`.
  </Accordion>

  <Accordion title="`init-agents` fails before writing anything">
    `init-agents` checks both instruction files before its first write, so a failure means nothing was changed.

    Two things cause it. First, `AGENTS.md` or `CLAUDE.md` is not a regular file. A directory, pipe, socket, or device is rejected, and the error names the type it found. Second, a file has a broken marker layout. Each file must contain either zero entire-graph marker tokens, or exactly one begin marker followed by one end marker.

    Marker tokens count even inside code fences, examples, or HTML comments, because they make the replacement range ambiguous. To recover:

    1. Back up `AGENTS.md` and `CLAUDE.md`.
    2. Replace any non-regular target with a regular file, or move it aside.
    3. Reword any stray marker strings that appear in examples or comments.
    4. Rerun `entire graph init-agents --repo .`.
  </Accordion>

  <Accordion title="Your edits to `.entire/graph-agent.md` disappeared">
    That file is generated, and it is regenerated in full on every successful `init-agents` run. Manual edits there are not preserved by design.

    Put your own instructions in `AGENTS.md` or `CLAUDE.md`, outside the `<!-- entire-graph:begin -->` and `<!-- entire-graph:end -->` markers. Everything outside those lines is left alone.
  </Accordion>

  <Accordion title="Remove entire-graph from a repository">
    Delete `.entire/graph-agent.md`, then remove the section entire-graph manages in `AGENTS.md` and `CLAUDE.md`. You can delete `.entire/` or either instruction file if it is otherwise empty.

    To also remove entire-graph from your machine, run:

    ```bash theme={null}
    entire plugin remove graph
    ```
  </Accordion>
</AccordionGroup>

## Your Agent Is Not Using entire-graph

<AccordionGroup>
  <Accordion title="The agent greps instead of running `entire graph search`">
    This is the most common problem, and it has three usual causes.

    **The session predates activation.** An agent session that was already open never read the new files. Quit it and start a fresh session in the repository.

    **The guide is not reaching the agent.** Confirm the generated guide matches your installed build:

    ```bash theme={null}
    diff <(entire graph agent-guide) .entire/graph-agent.md
    ```

    Empty output means they match. Then check that the managed block is present in the instruction file your agent actually reads.

    **Your agent does not resolve `@` imports.** Claude Code loads `CLAUDE.md` at session start and resolves the import. Other clients may treat the block as plain text, in which case they still get a written instruction to read `.entire/graph-agent.md`, but whether they follow it depends on the client and the model. Verify the behavior rather than assuming it.
  </Accordion>

  <Accordion title="`CLAUDE.md` seems to have the wrong block">
    If a distinct `CLAUDE.md` already contains a live standalone import that resolves to your root `AGENTS.md`, entire-graph deliberately puts only an inheritance notice in its `CLAUDE.md` block, so the guide is not imported twice:

    ```markdown theme={null}
    <!-- entire-graph:begin -->
    <!-- Entire Graph instructions are inherited through AGENTS.md. -->
    <!-- entire-graph:end -->
    ```

    Add or remove that `AGENTS.md` import and rerun `init-agents` to switch between the two layouts. Import detection only recognizes standalone paths. A mention inside inline code, a code fence, or an HTML comment does not count, and anything ambiguous keeps the direct pointer instead of assuming inheritance.
  </Accordion>
</AccordionGroup>

## Queries Are Slow

<AccordionGroup>
  <Accordion title="Every query rebuilds the index">
    entire-graph reuses a cached snapshot only when the working tree is clean. Any dirty file that entire-graph can index turns reuse off for the whole repository until the tree is clean again.

    Clean tree:

    ```text theme={null}
    Index: cache-hit (69ms) | Query: 0ms | Total: 70ms
    ```

    One uncommitted change to an indexable file such as `go.mod`:

    ```text theme={null}
    Index: cache-miss (782ms) | Query: 0ms | Total: 782ms
    ```

    Check what is dirty:

    ```bash theme={null}
    git status --short
    ```

    Extensionless files and root dependency manifests like `go.mod` and `package.json` all count. Dirty files entire-graph cannot index, such as a `.bin`, do not.

    The most common version of this is forgetting to commit the three activation files after running `init-agents`.
  </Accordion>

  <Accordion title="You ran `index` but queries still miss the cache">
    Two defaults have to line up, and out of the box they do not.

    `index` only warms committed-tree queries, and the interactive commands read the working tree unless you pass `--head`. `index` also defaults to `--profile full` while plain `search` defaults to `--profile fast`, and the profile is part of the cache key.

    So a default `index` run does not warm a default `search`. Match both:

    ```bash theme={null}
    entire graph index --repo . --profile fast
    entire graph search --repo . --head --profile fast --query "..."
    ```

    Changing `.graphignore` also selects a different cache entry.
  </Accordion>

  <Accordion title="`def` and `explain` never seem to cache">
    Unlike the other query commands, `def` and `explain` only cache when `--cache-dir` or `ENTIRE_PLUGIN_DATA_DIR` is set. Set one of them if you are calling those two repeatedly.
  </Accordion>
</AccordionGroup>

## Results Are Not What You Expected

<AccordionGroup>
  <Accordion title="A symbol name is ambiguous">
    entire-graph lists every definition it found and prints the exact selector for each one, so you can copy the one you want:

    ```text theme={null}
    "Match" matches 9 definitions; all are listed, the first 2 with source.
    - Router.Match (mux.go:151) [method]  --symbol Router.Match --file mux.go --line 151
    - routeRegexp.Match (regexp.go:189) [method]  --symbol routeRegexp.Match --file regexp.go --line 189
    - Route.Match (route.go:47) [method]  --symbol Route.Match --file route.go --line 47
    ```

    You can also address a definition directly with `--symbol FILE:LINE`.
  </Accordion>

  <Accordion title="No symbols matched">
    ```text theme={null}
    No symbols matched "NopeNotHere". Run `entire graph search --query "NopeNotHere"` to find the name, or `entire graph symbols --repo .` for the full definition inventory.
    ```

    Usually the name is spelled differently in source, or it lives in a language that is inventory only. Start with `search`, which takes plain language rather than an exact symbol.
  </Accordion>

  <Accordion title="`impact` reports fewer callers than really exist">
    Expected, and worth internalizing. Static analysis is heuristic, not a compiler. Calls through interfaces, reflection, dynamic dispatch, and generated or runtime-wired code can be missed or left unresolved.

    Dependent counts are guidance for inspection, not facts. Treat graph output as evidence to check against source. Relation edges carry `resolution` and `confidence` fields rather than a completeness promise.
  </Accordion>

  <Accordion title="`search` says LOW CONFIDENCE">
    entire-graph tells you when the ranking did not actually choose, for example when the top two results are effectively tied:

    ```text theme={null}
    LOW CONFIDENCE: top score 34.3 and ranks 1 and 2 are tied (0.0190 apart) - the ranking did not choose. This repo may not contain what you asked for; verify before editing.
    ```

    Rephrase the query to be more specific, or accept that the repository may not contain what you asked for. Do not edit on a low-confidence hit without reading the source first.
  </Accordion>

  <Accordion title="A language returns files but no relationships">
    Coverage comes in two tiers. Semantic languages are parsed for relationships; inventory-only filetypes give you file and symbol structure but no call or type analysis. See [What entire-graph Might Not Find](/guides/graph/how-graph-works#what-entire-graph-might-not-find) for which languages are in each tier.

    Check what your build supports:

    ```bash theme={null}
    entire graph capabilities --json
    ```
  </Accordion>

  <Accordion title="Files are missing, or coverage says degraded">
    Files the parser cannot handle surface as machine-readable partial failures rather than vanishing silently. Look at the `partial_failures` and `warnings` fields in JSON output, or the coverage line in agent format.

    Vendored and generated sources that are tracked in Git are the usual cause, since they show up as `E_FILE_TOO_LARGE` or `E_PARSE_ERROR`. Exclude them with a `.graphignore` at the repository root, which uses gitignore syntax and applies on top of `.gitignore`.
  </Accordion>
</AccordionGroup>

## Checking the Environment

`entire graph doctor` reports the resolved repository, the Entire environment variables, whether the plugin data directory is writable, and confirms no network egress:

```text theme={null}
ENTIRE_CLI_VERSION=0.10.1
ENTIRE_REPO_ROOT=/path/to/repo
ENTIRE_PLUGIN_DATA_DIR=/Users/you/.local/share/entire/plugins/data/graph
no_egress=true
plugin_data_dir=writable
repo_root=/path/to/repo
```

If a script built a command line against a different version, check it before running anything:

```bash theme={null}
entire graph doctor --assert "search --profile full --top-k 10 --format text"
```

An unaccepted flag is named explicitly, without reading the repository or building an index:

```text theme={null}
search does not accept --nope in entire-graph v0.4.0: this binary may be older than the caller that built the command line; run "entire graph search --help" for the flags it does accept (unexpected: --nope)
```

## Continue With

<CardGroup>
  <Card title="Install and Enable entire-graph" icon="wrench" href="/guides/graph/set-up-graph">
    Install the plugin and turn it on for a repository.
  </Card>

  <Card title="entire-graph CLI Reference" icon="terminal" href="/cli-reference/graph">
    Every query, analysis, and export command.
  </Card>

  <Card title="plugin" icon="plug" href="/cli-reference/plugin">
    Install, upgrade, and remove plugins.
  </Card>

  <Card title="entire-graph Issues" icon="github" href="https://github.com/entireio/entire-graph/issues">
    Report a problem with entire-graph.
  </Card>
</CardGroup>


# Use entire-graph with Your Coding Agent
Source: https://docs.entire.io/guides/graph/use-graph

Ask your coding agent to use entire-graph to find code, trace relationships, and understand what a change could affect.

After you [install and enable entire-graph](/guides/graph/set-up-graph), ask your coding agent questions about the repository in your own words. You do not need to run entire-graph commands yourself or mention entire-graph in every prompt.

## What You Can Ask

Your agent chooses the entire-graph command that matches your question.

| Goal                     | Example prompt                                        | entire-graph operation |
| ------------------------ | ----------------------------------------------------- | ---------------------- |
| Find an implementation   | Where is request routing implemented?                 | `search`               |
| Understand a definition  | Show and explain the definition of `ResolveRoute`.    | `def`                  |
| Trace callers or callees | What calls `ResolveRoute`?                            | `neighbors`            |
| Assess change impact     | What could be affected if I change `ResolveRoute`?    | `impact`               |
| Review a branch          | Summarize the semantic changes from `main` to `HEAD`. | `diff`                 |
| Export the graph         | Export the repository graph as NDJSON.                | `snapshot`             |

## What Happens After You Ask

For a task that requires finding code, your agent starts with a entire-graph search to narrow its investigation. It then reads the source around the most relevant results and uses follow-up entire-graph queries when it needs to trace relationships or assess impact.

entire-graph returns evidence for your agent to check, not a final conclusion. Your agent should verify the results against the source and run a focused test before completing a change. Interactive entire-graph queries read the working tree by default, so they include uncommitted edits.

## Example

In the [`gorilla/mux`](https://github.com/gorilla/mux) repository, you could ask:

```text theme={null}
Find where route matching is implemented, trace what calls it,
and explain what could be affected if its behavior changes.
```

### Example result

**Where route matching happens**

* `Router.Match` (`mux.go:151-182`) checks each registered route, builds the middleware chain, and handles not-found and method-not-allowed results.
* `Route.Match` (`route.go:47-114`) evaluates the matchers for an individual route and collects route variables.
* `routeRegexp.Match` (`regexp.go:189-209`) checks host, path, and query patterns.

**What calls it**

* `Router.ServeHTTP` calls `Router.Match` for incoming requests (`mux.go:203`).
* `Router.Match` calls `Route.Match` for each registered route (`mux.go:153`).
* The CORS middleware calls `Route.Match` when collecting allowed methods (`middleware.go:79`).

**What could be affected**

* Handler selection and middleware execution
* 404 and 405 responses
* Route variables used by handlers
* The `Access-Control-Allow-Methods` header produced by the CORS middleware

entire-graph helps your agent identify where to investigate, but the agent should still inspect the cited source before drawing a conclusion.

## When entire-graph Is Not Needed

If a task already identifies the exact file and the file is small, your agent can read it directly. entire-graph is most useful when your agent needs to find where to begin or understand how code connects.

## Run entire-graph Directly

You can also run entire-graph commands yourself for manual inspection, debugging, or automation. See the [entire-graph CLI reference](/cli-reference/graph) for commands and options.

## Continue With

<CardGroup>
  <Card title="Install and Enable entire-graph" icon="wrench" href="/guides/graph/set-up-graph">
    Install entire-graph and add its instructions to a repository.
  </Card>

  <Card title="How entire-graph Works" icon="chart-network" href="/guides/graph/how-graph-works">
    Learn what entire-graph analyzes and where its results have limits.
  </Card>

  <Card title="entire-graph CLI Reference" icon="terminal" href="/cli-reference/graph">
    Review entire-graph commands and options.
  </Card>

  <Card title="entire-graph Troubleshooting" icon="stethoscope" href="/guides/graph/troubleshooting">
    Fix installation, adoption, cache, and coverage problems.
  </Card>
</CardGroup>


# Entire-Native Branches
Source: https://docs.entire.io/guides/repositories/entire-native-branches

Push branches that stay on Entire when GitHub is down.

## What Is an Entire-Native Branch?

When you mirror a repository with Entire, it stays in sync with GitHub as its primary origin. You clone and fetch from a regional Entire mirror, but every push still routes to GitHub. By design, pushes are only as fast as GitHub allows, and when there is an outage, you cannot push at all.

Entire-native branches let you keep pushing during an outage and absorb the heavy write traffic of agent workflows. Use one when you have several agents working in parallel, or when you need pushes to be fast. An Entire-native branch skips the sync with GitHub and stays on Entire, in the region that hosts your repository.

## Push to an Entire-Native Branch

To enable an Entire-native branch, you just need to name your branch with the `entire/unmirrored/` prefix and push as usual:

```bash theme={null}
git switch -c entire/unmirrored/agent-work
git push origin entire/unmirrored/agent-work
```

The branch lands on the placement that receives the push and stays there.

<Note>
  These examples assume `origin` points at your Entire mirror, which is the default when you run `entire repo mirror use`. If you added Entire as a separate remote with `entire repo mirror use --remote entire`, push to `entire` instead of `origin`.
</Note>

## Or Tell Your Agent

If you do not want to type this prefix manually, add this to your `CLAUDE.md`, `AGENTS.md`, or equivalent:

```markdown theme={null}
When asked to push to Entire (not GitHub), push to a branch named
`entire/unmirrored/<task-name>`. When asked to publish to GitHub,
push the same commits to a branch without that prefix.
```

### Push and Prompt as Normal

From then on, when prompting your agent, instruct it where the work should go, and it will pick the right branch automatically.

When you want the work to stay on Entire:

> Push this to Entire, not GitHub.

When you want it on GitHub:

> Publish this to GitHub.

The agent handles the branch names. Native branches stay on Entire until you publish them. And you can continue coding and pushing even when GitHub is down.

## Publish the Work Upstream

Entire-native branches don't sync to GitHub automatically. When you are ready to bring the work into your GitHub repo, push it again under a normal branch name without any prefix:

```bash theme={null}
git push origin HEAD:agent-work
```

## Access and Permissions

You still need write access to push, the same as with any mirrored branch. Entire checks this against the access list it syncs from GitHub every hour. See [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions) for how that sync works.

## Limitations

* Entire does not currently back up Entire-native branches, so if you need to keep the work for a longer time, you need to save a copy somewhere else too.
* The branch lives in the single region you pushed it to. Entire does not copy it to your other regions.

## Continue With

<CardGroup>
  <Card title="Mirrors" icon="clone" href="/guides/repositories/mirrors">
    Learn how a mirror serves a GitHub repository from an EntireDB cluster.
  </Card>

  <Card title="Mirror Access and Permissions" icon="lock" href="/guides/repositories/mirror-access-and-permissions">
    Understand GitHub-synced access, hourly collaborator sync, and offboarding.
  </Card>

  <Card title="Mirrors in CLI" icon="terminal" href="/guides/repositories/mirrors-in-cli">
    Create mirrors and configure Git remotes from the Entire CLI.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/repositories/troubleshooting">
    Fix missing repositories, app access, clone, fetch, and push issues.
  </Card>
</CardGroup>


# Install the Entire GitHub App
Source: https://docs.entire.io/guides/repositories/github-app-access

Authorize the Entire GitHub App and choose which repositories Entire can access.

Entire uses the GitHub App to access the repositories you choose.

## When You Need This

Configure GitHub App access when you want to:

* make a GitHub repository appear in Entire
* create a repository mirror
* let Entire read repository and checkpoint activity
* let Entire verify GitHub collaborator access for mirror permissions

GitHub App access controls which GitHub repositories Entire can see. It does not move, delete, or replace the GitHub repository.

## Configure GitHub App Access

Choose the flow that matches where the repository lives.

<Tabs>
  <Tab title="Personal Repository">
    Use this when the repository is owned by your GitHub account.

    In entire.io, open repository setup and choose **Configure GitHub App**.

    GitHub opens the Entire GitHub App settings. From there, choose either:

    * **All repositories**, if Entire should be able to access every repository in your account
    * **Only select repositories**, if Entire should only access specific repositories

    Save the GitHub App configuration, then return to entire.io.
  </Tab>

  <Tab title="Organization Repository">
    Use this when the repository is owned by a GitHub organization.

    For organization repositories, a GitHub organization admin must install or update the Entire GitHub App.

    In entire.io, open repository setup and choose **Configure GitHub App**.

    GitHub opens the Entire GitHub App settings. From there, the organization admin can choose either:

    * **All repositories**, if Entire should be able to access every repository in the organization
    * **Only select repositories**, if Entire should only access specific repositories

    Save the GitHub App configuration, then return to entire.io.

    After the app is installed and allowed to access a repository, team members can use repositories they already have GitHub collaborator access to.
  </Tab>
</Tabs>

## What the Flow Looks Like

GitHub asks you to authorize Entire before you choose which repositories the app can access.

<Frame>
  <img alt="GitHub authorization screen for Entire" />
</Frame>

After authorization, return to entire.io and select the repositories you want to connect.

<Frame>
  <img alt="Repository selector in entire.io" />
</Frame>

## Verify Access

For a repository to appear in Entire or be available for mirroring:

* the Entire GitHub App must be installed for the account or organization
* the app must be allowed to access that repository
* your GitHub account must have access to that repository

If the repository does not appear after configuring access, confirm that you are viewing the correct GitHub account or organization and that the repository is included in the GitHub App access list.

## Permissions

The Entire GitHub App requests these permissions:

**Repository permissions**

| Permission                | Purpose                                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| Administration: read      | Read repository settings, teams, and collaborators.                                         |
| Checks: read              | Read check status for repository activity and review context.                               |
| Commit statuses: read     | Read commit status information.                                                             |
| Contents: read/write      | Read repository contents and support Git operations that require repository content access. |
| Pull requests: read/write | Read and support pull request workflows, comments, labels, assignees, and related metadata. |

**Organization permissions**

| Permission    | Purpose                              |
| ------------- | ------------------------------------ |
| Members: read | Read organization members and teams. |

<Note>
  Checkpoint data is created locally by the Entire CLI and stored in your repository as Git refs under `refs/entire/checkpoints/`, or on the `entire/checkpoints/v1` branch in repositories that use the legacy branch backend. The GitHub App does not create local checkpoints for you.
</Note>

## Mirrors

Repository mirrors require GitHub App access to the source GitHub repository.

After GitHub App access is configured, you can create a mirror from entire.io or the CLI:

```bash theme={null}
entire repo mirror create github.com/OWNER/REPO
```

GitHub App access controls which repositories Entire can see. User mirror access follows GitHub collaborator permissions and syncs hourly. See [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions).

## Remove Access

If you uninstall the Entire GitHub App or remove a repository from its access list:

* the repository may stop appearing in entire.io
* Entire cannot create or update mirrors for that repository
* Entire cannot sync new checkpoint activity from that repository
* existing checkpoint data already stored in Entire remains visible according to your current access settings
* local Git branches and local checkpoint data are not deleted

## Continue With

<CardGroup>
  <Card title="Mirrors" icon="clone" href="/guides/repositories/mirrors">
    Create and use repository mirrors.
  </Card>

  <Card title="Mirror Access and Permissions" icon="lock" href="/guides/repositories/mirror-access-and-permissions">
    Understand GitHub-synced access, hourly collaborator sync, and offboarding.
  </Card>
</CardGroup>


# Mirror Access and Permissions
Source: https://docs.entire.io/guides/repositories/mirror-access-and-permissions

Understand how repository mirror access follows GitHub collaborator permissions.

Entire uses GitHub collaborator permissions to decide who can use a repository mirror.

A mirror has two access requirements:

* **GitHub App access** lets Entire see and mirror the source repository.
* **GitHub collaborator access** controls who can clone, fetch, and push through the `entire://` remote.

Entire syncs GitHub collaborators into mirror access hourly. There is no separate Entire-side permission list to grant or revoke manually.

## Before Users Can Create or Join Mirrors

For organization repositories, a GitHub organization admin must install the Entire GitHub App and allow it to access the repository. See [GitHub App Access](/guides/repositories/github-app-access) for the GitHub App setup flow.

Each user should also sign in with the Entire CLI:

```bash theme={null}
entire login
```

This connects the user's Entire account to their GitHub identity so Entire can check repository access.

## Hourly Collaborator Sync

Entire checks the GitHub collaborator list hourly and updates mirror access from that list.

A read-only GitHub collaborator can clone and fetch from the mirror. A GitHub collaborator with write access can also push through the mirror.

GitHub access changes can take up to an hour to appear in Entire. If a GitHub collaborator has not signed in to Entire yet, automatic access can take up to an hour after they sign in.

## User Self-Onboarding

After the GitHub App is installed, a user with access to the GitHub repository can create or join the mirror:

```bash theme={null}
entire login
entire repo mirror create github.com/OWNER/REPO
```

If the mirror does not exist yet, Entire creates it. If the mirror already exists, the command checks the current user's GitHub access and returns the mirror URL.

## Check Mirror Access

GitHub admins and repository owners can list the users who currently have mirror access:

```bash theme={null}
entire repo mirror collaborators list github.com/OWNER/REPO
```

This command is read-only. To change who can use the mirror, update collaborator access in GitHub and wait for the next hourly sync.

## Offboard a User

When you offboard a user, remove their GitHub access. Entire mirror access is updated by the hourly collaborator sync.

<Warning>
  After GitHub access is removed, the user can no longer push through the mirror because pushes are authenticated with GitHub. Clone and fetch access may continue until the next hourly collaborator sync.
</Warning>

## Continue With

<CardGroup>
  <Card title="Mirrors" icon="clone" href="/guides/repositories/mirrors">
    Learn how mirrors make GitHub repositories available in Entire.
  </Card>

  <Card title="repo" icon="terminal" href="/cli-reference/repo">
    See the command syntax for repository and mirror commands.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/repositories/troubleshooting">
    Fix mirror setup, access, clone, fetch, and push issues.
  </Card>
</CardGroup>


# Mirrors
Source: https://docs.entire.io/guides/repositories/mirrors

Connect an existing GitHub repository to Entire with an Entire-backed Git remote.

<iframe title="Entire 101 | Ep. 3: What is Mirroring a Repo Anyway?" />

## What Is a Mirror?

A mirror is a synchronized copy of your repository. The origin remains on GitHub, but the copy lives on Entire in one or more regional clusters of your choice. This allows you to offload heavy read traffic to Entire, enabling your agents to pull and clone faster.

Entire represents the GitHub repository as a single repository object. Each region you mirror into is a mirror placement, which connects that object to one Entire cluster. If you mirror the same repository in two regions, you have one repository object and two mirror placements, each with its own `entire://` URL.

## Why Use a Mirror

Mirroring is helpful when you or your agents need faster Git reads close to where they run.

It works well when:

* agents clone or fetch the same repository often, such as a large monorepo with high agentic traffic
* you want your agents to keep cloning and pulling during a GitHub outage
* you want a repository available in your home region or in multiple regions

## Before You Create a Mirror

The [Entire GitHub App must be able to access the repository](/guides/repositories/github-app-access) before you can create a mirror. After that, anyone with access to the GitHub repository can create a mirror from entire.io or with the Entire CLI.

You should choose regions based on where your agents run and where your organization allows code to live. Each region you select becomes a separate mirror placement.

If a repository has mirrors in more than one region, `entire repo clone` and `entire repo mirror use` ask you to choose one. For non-interactive commands, use `--cluster`.

## Create a Mirror

There are multiple ways to create a mirror, here’s how:

* To create a mirror from entire.io, read [Mirrors in entire.io](/guides/repositories/mirrors-in-entire-io).

* To create one from the terminal, head to [Mirrors in CLI](/guides/repositories/mirrors-in-cli).

* For a full walkthrough, see [Mirror a GitHub Repository](/learn/mirror-a-github-repository).

## What Changes

Creating a mirror gives you:

* a synced Entire copy of your GitHub repository
* an `entire://` remote for Git operations
* faster clone and fetch traffic for agents in that region
* an Entire access list that syncs from GitHub every hour

You can clone directly from the mirror or add it as another remote in an existing checkout.

## What Does Not Change

Creating a mirror does not:

* move, delete, or replace the GitHub repository
* require every developer to change remotes
* rewrite Git history
* bypass GitHub authentication or repository rules for pushes

Entire syncs GitHub collaborators into mirror access hourly. People with read access can clone and fetch, while people with write access can push. See [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions) for more on access, self-onboarding, and offboarding.

## What Mirrors Do Not Do

### Git LFS

Mirrors do not currently support [Git LFS](https://git-lfs.com/).

If you clone a repository that uses LFS through an `entire://` remote, the checkout can fail because Git LFS tries to download files through Entire:

```text theme={null}
Error downloading object: ... batch request: ssh: Could not resolve hostname entire
error: external filter 'git-lfs filter-process' failed
fatal: <file>: smudge filter lfs failed
```

Use Entire for normal Git operations and GitHub for LFS downloads.
For a fresh clone, skip LFS downloads during checkout, point LFS at GitHub, and then pull the files:

```bash theme={null}
GIT_LFS_SKIP_SMUDGE=1 entire repo clone /gh/OWNER/REPO
cd REPO
git config lfs.url "https://github.com/OWNER/REPO.git/info/lfs"
git lfs pull
```

For an existing checkout, configure the URL and pull:

```bash theme={null}
git config lfs.url "https://github.com/OWNER/REPO.git/info/lfs"
git lfs pull
```

## Continue With

<CardGroup>
  <Card title="GitHub App Access" icon="github" href="/guides/repositories/github-app-access">
    Choose which GitHub repositories Entire can access.
  </Card>

  <Card title="Mirrors in entire.io" icon="browser" href="/guides/repositories/mirrors-in-entire-io">
    Configure GitHub access and choose repositories from the web interface.
  </Card>

  <Card title="Mirrors in CLI" icon="terminal" href="/guides/repositories/mirrors-in-cli">
    Create a mirror from the terminal and use it from Git.
  </Card>

  <Card title="Mirror Access and Permissions" icon="lock" href="/guides/repositories/mirror-access-and-permissions">
    Understand GitHub-synced access, hourly collaborator sync, and offboarding.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/repositories/troubleshooting">
    Fix mirror setup, access, clone, fetch, and push issues.
  </Card>
</CardGroup>


# Mirror Repositories in the CLI
Source: https://docs.entire.io/guides/repositories/mirrors-in-cli

Create GitHub repository mirrors with the Entire CLI and configure Git remotes.

You can inspect and mirror repositories in the Entire CLI as easily as you would on entire.io.

## Before You Start

Make sure you have:

* [Entire installed](/installation)
* access to clone the GitHub repository you want to mirror
* the [Entire GitHub App authorized](/guides/repositories/github-app-access) for the repository

Each selected region creates a separate mirror placement. If you select several regions, choose the placement closest to your agents when you clone or configure a remote. [Mirror access follows GitHub collaborator permissions](/guides/repositories/mirror-access-and-permissions).

Read [What Mirrors Do Not Do](/guides/repositories/mirrors#what-mirrors-do-not-do) before setup if the repository uses Git LFS. Branches under `entire/unmirrored/` stay in one Entire region and do not sync to GitHub.

## Log In

Log in with the Entire CLI:

```bash theme={null}
entire login
```

Confirm that your login is active:

```bash theme={null}
entire auth status
```

## Inspect Repositories and Mirrors

List repositories that your login can access:

```bash theme={null}
entire repo mirror list
```

The list combines existing mirrors with GitHub repositories you can onboard. Use `--mirrored` to show existing mirrors or `--available` to show GitHub repositories that do not have a mirror placement yet.

Inspect one repository and its placement on each cluster:

```bash theme={null}
entire repo mirror get OWNER/REPO
```

The detail view shows the repository's visibility and access, then lists each cluster, clone URL, and mirror status.

## Create the Mirror

Run the create command with no arguments:

```bash theme={null}
entire repo mirror create
```

Entire prompts you to select repositories and regions. It creates a placement for every selected repository in every selected region:

```text theme={null}
Select repos to mirror
Space to select, enter to confirm.

> [•] <owner>/<repo>

Select regions to mirror into
Each repo is mirrored into every selected region.

> [•] us-east (us)
  [•] eu-west (eu)

REPO            REGION        STATUS  CLONE URL
<owner>/<repo>  us-east (us)  ready   entire://aws-us-east-2.entire.io/gh/<owner>/<repo>
<owner>/<repo>  eu-west (eu)  ready   entire://aws-eu-central-1.entire.io/gh/<owner>/<repo>
```

This registers the mirror placements on Entire. It does not change any local Git checkout.

### Script the Mirror Creation

To create one placement without repository prompts, pass the repository and, optionally, its cluster host:

```bash theme={null}
export GH_OWNER="<owner>"
export GH_REPO="<repo>"

entire repo mirror create "github.com/$GH_OWNER/$GH_REPO" aws-us-east-2.entire.io
```

The repository can be written as `owner/repo`, an HTTPS GitHub URL, or an SSH GitHub URL. If you omit the cluster host, an interactive terminal prompts when more than one cluster is available. A non-interactive run defaults to `aws-us-east-2.entire.io`. To create placements in several regions from a script, run the command once per cluster host.

The command waits until the initial clone from GitHub is available, then returns the placement ID and clone URL.

Creating a mirror is idempotent for a given repository and region: rerunning the command returns the existing mirror. To return as soon as the mirror is registered instead of waiting for the initial clone, pass `--no-wait`.

## Clone the Mirror

Clone by repository path:

```bash theme={null}
entire repo clone "/gh/$GH_OWNER/$GH_REPO"
```

If the repository has one placement, Entire selects it. If it has placements on several clusters, an interactive terminal prompts you to choose one. Select a cluster in a non-interactive command with `--cluster`:

```bash theme={null}
entire repo clone "/gh/$GH_OWNER/$GH_REPO" --cluster aws-eu-central-1.entire.io
```

You can also pass a full `entire://` URL. Because the URL already names a cluster, Entire passes it to `git clone` without a placement lookup.

## Use the Mirror in an Existing Checkout

From the existing GitHub checkout, run:

```bash theme={null}
cd "$GH_REPO"
entire repo mirror use
```

Entire resolves the GitHub repository from the local `origin` remote. If the repository has placements on several clusters, an interactive terminal prompts you to choose one. A non-interactive run requires `--cluster`. The interactive flow then asks whether to repoint `origin` or add the mirror as a separate remote.

When Entire repoints `origin`, it preserves the previous GitHub URL as `upstream` if that remote name is available. If `upstream` already exists, Entire leaves it unchanged and warns that it did not save the previous URL. Choose another name with `--upstream NAME`. In a non-interactive command, `entire repo mirror use` repoints `origin` by default.

To keep `origin` unchanged and add the mirror as `entire`, run:

```bash theme={null}
entire repo mirror use --remote entire
```

This command only edits the current checkout's Git configuration. The server-side mirror must already exist.

## Push through the Mirror

Push to the configured remote with normal Git commands:

```bash theme={null}
git push -u origin <branch>
```

Entire forwards the push through the mirror to the upstream GitHub repository. Your GitHub write access, branch protection rules, and required checks still apply.

## Push an Unmirrored Branch

Branches whose names start with `entire/unmirrored/` are never forwarded to GitHub. The branch stays in the mirror's Entire region, so pushes to it are not subject to GitHub's push rate limits. See [Entire-Native Branches](/guides/repositories/entire-native-branches) for when to use them.

Create and push an unmirrored branch with normal Git commands:

```bash theme={null}
git switch -c "entire/unmirrored/<branch>"
git push -u origin "entire/unmirrored/<branch>"
```

When you want the work on GitHub, push the same commits to a branch name outside the prefix:

```bash theme={null}
git push origin "entire/unmirrored/<branch>:<branch>"
```

<Warning>
  Entire does not currently back up unmirrored branches, and they are not available on GitHub or from mirrors in other regions. Keep a copy of any work you cannot afford to lose on a mirrored branch or on GitHub.
</Warning>

## Raw Git Fallback

Use raw Git commands when you need to manage the remote configuration yourself. Git invokes `git-remote-entire` for `entire://` remotes.

Clone from a known placement URL:

```bash theme={null}
git clone "entire://aws-us-east-2.entire.io/gh/$GH_OWNER/$GH_REPO"
```

To repoint `origin`:

```bash theme={null}
git remote set-url origin "entire://aws-us-east-2.entire.io/gh/$GH_OWNER/$GH_REPO"
```

To keep `origin` and add a separate remote:

```bash theme={null}
git remote add entire "entire://aws-us-east-2.entire.io/gh/$GH_OWNER/$GH_REPO"
```

With raw Git, save the previous URL and select the regional placement yourself. See [Troubleshooting](/guides/repositories/troubleshooting) for `git-remote-entire` diagnostics.

## Remove the Mirror

When you no longer need the mirror, remove the server-side mirror placement:

```bash theme={null}
entire repo mirror remove "github.com/$GH_OWNER/$GH_REPO"
```

Removing a mirror does not delete or rewrite the GitHub repository. It also does not change any local Git remotes you configured in `.git/config`.

## Continue With

<CardGroup>
  <Card title="Mirror a GitHub Repository" icon="terminal" href="/learn/mirror-a-github-repository">
    Follow the end-to-end tutorial for creating, cloning, pushing through, and restoring a mirror.
  </Card>

  <Card title="Mirrors in entire.io" icon="browser" href="/guides/repositories/mirrors-in-entire-io">
    Configure GitHub access and choose repositories from the web interface.
  </Card>

  <Card title="Mirror Access and Permissions" icon="lock" href="/guides/repositories/mirror-access-and-permissions">
    Understand GitHub-synced access, hourly collaborator sync, and offboarding.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/repositories/troubleshooting">
    Fix missing repositories, app access, clone, fetch, and push issues.
  </Card>
</CardGroup>


# Mirror Repositories in entire.io
Source: https://docs.entire.io/guides/repositories/mirrors-in-entire-io

Configure GitHub access, choose repositories, and create mirrors from entire.io.

Use entire.io when you want to configure GitHub access, mirror, and choose repositories from the web interface. This guide covers the web flow. For the command-line flow, see [Mirrors in CLI](/guides/repositories/mirrors-in-cli).

## Before You Start

Make sure you have:

* a GitHub account connected to Entire
* access to the GitHub repository you want to mirror
* a GitHub organization admin available if the repository belongs to an organization and the Entire GitHub App has not been installed yet

## Configure GitHub Access

In entire.io, open the repository setup flow and choose **Configure GitHub App**.

GitHub opens the Entire GitHub App configuration. From there, an organization admin can install the app or update its repository access.

<Frame>
  <img alt="Configure GitHub access in entire.io" />
</Frame>

Choose either:

* **All repositories**, if Entire should be able to access every repository in the account or organization
* **Only select repositories**, if Entire should only access specific repositories

Save the GitHub App configuration, then return to entire.io.

## Select Repositories

After GitHub access is configured, entire.io shows the repositories that are available to mirror.

Select the repositories you want to make available in Entire. If a repository does not appear, confirm that:

* the Entire GitHub App can access the repository
* your GitHub account has access to the repository
* you are viewing the correct account or organization

For more help, see [Troubleshooting](/guides/repositories/troubleshooting).

## Choose Data Residency

Choose the region where Entire stores and serves the repository mirror. Entire currently supports mirroring in regions such as the United States, India, Australia and the European Union.

Use the region required by your team's security, compliance, or latency needs. You can choose a region per repository before continuing.

<Frame>
  <img alt="Choose data residency for mirrored repositories in entire.io" />
</Frame>

## Continue to Entire

After you choose repositories and data residency, continue to the repositories tab in entire.io.

The mirrored repositories appear in the repository list. From there, your team can use entire.io to inspect repository activity and agents can use the mirror as a regional Git remote.

<Frame>
  <img alt="Mirrored repositories listed in entire.io" />
</Frame>

## If You Are Not an Org Admin

If you are not a GitHub organization admin, you may not be able to add or remove repositories from the GitHub App configuration.

You can still continue to entire.io and use repositories that an admin has already made available. If the repository you need is missing, ask a GitHub organization admin to configure the Entire GitHub App for that repository.

<Frame>
  <img alt="Non-admin repository access state in entire.io" />
</Frame>

For the full GitHub App permission model, see [GitHub App Access](/guides/repositories/github-app-access). For GitHub-synced mirror access and hourly collaborator sync, see [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions).

## Continue With

<CardGroup>
  <Card title="GitHub App Access" icon="github" href="/guides/repositories/github-app-access">
    Choose which GitHub repositories Entire can access.
  </Card>

  <Card title="Mirrors" icon="clone" href="/guides/repositories/mirrors">
    Learn how mirrors make GitHub repositories available in Entire.
  </Card>

  <Card title="Mirrors in CLI" icon="terminal" href="/guides/repositories/mirrors-in-cli">
    Create a mirror from the terminal and use it from Git.
  </Card>

  <Card title="Mirror Access and Permissions" icon="lock" href="/guides/repositories/mirror-access-and-permissions">
    Understand GitHub-synced access, hourly collaborator sync, and offboarding.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/repositories/troubleshooting">
    Fix missing repositories, app access, clone, fetch, and push issues.
  </Card>
</CardGroup>


# Overview
Source: https://docs.entire.io/guides/repositories/overview

Learn how Entire provides distributed Git hosting for teams and agents.

Traditional Git hosting was built for a human-paced workflow: clone once, work for a while, then push a change.

Agents have fundamentally changed that workflow. Around the clock, agents are cloning and pushing at unprecedented scale. When all of that traffic hits a central origin, the result is slow clones and pushes, throttled agents, and downtime. Entire is a globally distributed Git hosting network built to handle the scale of agentic coding by enabling you to host your code in one or multiple regional clusters. In our early testing, Entire is up to 89 times faster than other Git providers.

## Benefits of Hosting Your Code with Entire

* **Scale.** Agents can push and pull on large monorepos in parallel at increased speed, without being throttled.
* **Low latency.** The closer the agent is to the server, the less time you spend waiting on a clone or pull.
* **Data residency.** Sovereign code hosting in one or more jurisdictions of your choice.
* **Availability.** When one region or node is unavailable, your other regions keep serving, and Entire-native branches let you keep pushing even when your upstream provider is down.

## How It Works

**Mirroring your repository.** Today, you can [mirror your repository](/guides/repositories/mirrors) directly onto our Git network in multiple regions, including the United States, the European Union, India, and Australia. This keeps a synced copy of your GitHub repository on Entire, so your agents can clone and pull from the region closest to them while GitHub stays the source of truth.

**Entire-native branches.** A mirrored repository stays in sync with GitHub and enables significantly faster clones. But pushes are only as fast as your origin allows, and when GitHub is down you cannot push to your origin at all. An [Entire-native branch](/guides/repositories/entire-native-branches) skips that sync and stays on the region you pushed it to, so you can keep pushing during an outage and absorb the concurrency of several agents working in parallel. To use one, name your branch with the `entire/unmirrored/` prefix and push as usual. When you're ready to bring the work into GitHub, push it again under a normal branch name.

## Continue With

<CardGroup>
  <Card title="GitHub App Access" icon="github" href="/guides/repositories/github-app-access">
    Choose which GitHub repositories Entire can access.
  </Card>

  <Card title="Mirrors" icon="clone" href="/guides/repositories/mirrors">
    Bring an existing GitHub repository into Entire.
  </Card>

  <Card title="Mirrors in CLI" icon="terminal" href="/guides/repositories/mirrors-in-cli">
    Create a mirror from the terminal and use it from Git.
  </Card>

  <Card title="Mirror a GitHub Repository" icon="graduation-cap" href="/learn/mirror-a-github-repository">
    Follow the complete mirror workflow from access setup through removal.
  </Card>
</CardGroup>


# Troubleshooting
Source: https://docs.entire.io/guides/repositories/troubleshooting

Fix common repository mirror setup, access, clone, fetch, and push issues.

Use this page when a repository mirror cannot be created, cloned, fetched, pushed to, or accessed by the expected users.

## `git-remote-entire` Diagnostics

Git invokes `git-remote-entire` when a remote uses an `entire://` URL. Confirm that the helper is installed and available on `PATH`:

```bash theme={null}
git-remote-entire --version
```

If the shell cannot find the command, [update or reinstall Entire](/installation#install-and-update-entire). The release archive installs `entire` and `git-remote-entire` together.

For a clone or fetch failure, confirm your login and the placement before testing the remote directly:

```bash theme={null}
entire auth status
entire repo mirror get OWNER/REPO
git ls-remote entire://CLUSTER_HOST/gh/OWNER/REPO
```

The URL must include the cluster host. Use `entire repo mirror get OWNER/REPO` to find the full URL, or use `entire repo clone /gh/OWNER/REPO` to let Entire select a placement.

Set `ENTIRE_DEBUG` to include authentication, cluster discovery, request, response, and timing details from the helper on standard error:

```bash theme={null}
ENTIRE_DEBUG=1 git ls-remote entire://CLUSTER_HOST/gh/OWNER/REPO
```

Review diagnostic output before sharing it outside your organization.

<AccordionGroup>
  <Accordion title="Unknown Command &#x22;repo&#x22;">
    Your `entire` binary may be older than the repository mirror commands.

    [Update Entire](/installation#install-and-update-entire), then try again:

    ```bash theme={null}
    entire repo mirror create github.com/OWNER/REPO
    ```
  </Accordion>

  <Accordion title="The Repository Is Missing from GitHub App Access">
    Confirm that the Entire GitHub App is installed and allowed to access the repository.

    1. Open [GitHub installed apps](https://github.com/settings/installations).
    2. Find **Entire**.
    3. Click **Configure**.
    4. Choose **All repositories** or select the repository you want to mirror.
    5. Save the GitHub App configuration.

    For the full GitHub App setup flow, see [GitHub App Access](/guides/repositories/github-app-access).
  </Accordion>

  <Accordion title="A User Cannot Create or Join a Mirror">
    Check both access requirements:

    * The Entire GitHub App can access the repository.
    * The user has access to the repository in GitHub.
    * The user has signed in with the Entire CLI using `entire login`.

    After those are true, the user can create or join the mirror:

    ```bash theme={null}
    entire repo mirror create github.com/OWNER/REPO
    ```

    Entire syncs GitHub collaborators into mirror access hourly. If the user recently got GitHub access or recently signed in to Entire, wait for the next sync or have them run `entire repo mirror create github.com/OWNER/REPO`.

    See [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions) for GitHub-synced access, hourly collaborator sync, and self-onboarding.
  </Accordion>

  <Accordion title="Mirror Creation Takes a While">
    The default create command waits for the initial GitHub-to-Entire clone to finish. Large repositories can take longer.

    If you only need to register the mirror and check back later, use `--no-wait`:

    ```bash theme={null}
    entire repo mirror create github.com/OWNER/REPO --no-wait
    ```
  </Accordion>

  <Accordion title="Git Cannot Clone or Fetch from the Mirror">
    Confirm that the repository has a ready placement and let Entire select its clone URL:

    ```bash theme={null}
    entire repo mirror get OWNER/REPO
    entire repo clone /gh/OWNER/REPO
    ```

    If the repository has placements on several clusters, select one explicitly:

    ```bash theme={null}
    entire repo clone /gh/OWNER/REPO --cluster CLUSTER_HOST
    ```

    If cloning still fails:

    * Run `entire login` to refresh your Entire session.
    * Confirm you have GitHub collaborator access to the repository.
    * If your GitHub access changed recently, wait for the next hourly collaborator sync.
    * Confirm your network can reach the selected cluster host.
    * If you added the mirror to an existing checkout, run `git remote -v` and confirm the remote URL.
    * Run the [`git-remote-entire` diagnostics](#git-remote-entire-diagnostics).
  </Accordion>

  <Accordion title="Cloning a Mirror with LFS Files Fails During Checkout">
    Mirrors do not currently support Git LFS. When you clone a mirror of a repository that uses LFS, the clone succeeds but checkout fails with a smudge error like:

    ```text theme={null}
    Error downloading object: ... batch request: ssh: Could not resolve hostname entire
    error: external filter 'git-lfs filter-process' failed
    fatal: <file>: smudge filter lfs failed
    ```

    As a workaround, point Git LFS at GitHub so that large file transfers go through GitHub, while regular Git operations keep using the mirror:

    ```bash theme={null}
    git config lfs.url "https://github.com/<owner>/<repo>.git/info/lfs"
    ```

    See [Git LFS](/guides/repositories/mirrors#git-lfs) for the full workaround, including how to recover a fresh clone that failed at checkout.
  </Accordion>

  <Accordion title="Pushes Through the Mirror Are Rejected">
    Pushes through a mirror are still authenticated with GitHub.

    If a push is rejected:

    * Confirm the user has write access to the GitHub repository.
    * Confirm branch protection rules and required checks allow the push.
    * Confirm the Entire GitHub App can access the repository.
    * Refresh the user's Entire login.

    ```bash theme={null}
    entire auth logout
    entire auth login
    ```
  </Accordion>

  <Accordion title="A Pushed Branch Does Not Appear on GitHub">
    Branch names that start with `entire/unmirrored/` are intentionally never synced to GitHub. The branch exists only in the Entire region you pushed it to.

    To publish the work on GitHub, push the commits to a branch name outside the prefix:

    ```bash theme={null}
    git push origin "entire/unmirrored/<branch>:<branch>"
    ```

    See [Entire-Native Branches](/guides/repositories/entire-native-branches) for how unmirrored branches work.
  </Accordion>

  <Accordion title="A Removed User Can Still Read from a Mirror">
    Removing GitHub access prevents push-through writes because pushes are authenticated with GitHub. Clone and fetch access may continue until the next hourly collaborator sync.

    See [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions#offboard-a-user) for the offboarding flow.
  </Accordion>

  <Accordion title="The Mirror Was Removed but a Local Checkout Still Points to It">
    Removing a server-side mirror placement does not edit local Git configuration.

    Check the remote in the local checkout:

    ```bash theme={null}
    git remote -v
    ```

    To switch back to GitHub:

    ```bash theme={null}
    git remote get-url upstream
    git remote set-url origin git@github.com:<owner>/<repo>.git
    ```
  </Accordion>

  <Accordion title="Still Stuck?">
    Include these details when asking for help:

    * `entire version`
    * the GitHub repository URL
    * the `entire://` mirror URL
    * whether the Entire GitHub App can access the repository
    * whether the issue happens during create, clone, fetch, or push
    * the full error message

    You can file an issue at [github.com/entireio/cli](https://github.com/entireio/cli) or ask in the [Entire Discord](https://discord.gg/jZJs3Tue4S).
  </Accordion>
</AccordionGroup>

## Continue With

<CardGroup>
  <Card title="Mirrors" icon="clone" href="/guides/repositories/mirrors">
    Learn how mirrors make GitHub repositories available in Entire.
  </Card>

  <Card title="Mirror Access and Permissions" icon="lock" href="/guides/repositories/mirror-access-and-permissions">
    Understand GitHub-synced access, hourly collaborator sync, and offboarding.
  </Card>
</CardGroup>


# Overview
Source: https://docs.entire.io/guides/search/overview

Query the code across your repositories and the commits, sessions, and agent work that produced it.

<iframe title="Why is our code like this? Agentic Search on Entire" />

Agentic Search answers questions about your code and the work that produced it. One query returns the commits and sessions behind a change alongside the matching code.

Search runs on a dual engine:

* **Semantic search** matches meaning and keywords across commits and sessions, surfacing the reasoning behind a change.
* **Code Search** finds literal text such as function names, error messages, and configuration keys. It is symbol-aware, with definitions and references.

[entire.io](/guides/search/search-in-entire-io) searches every repository you can access. The [Entire CLI](/guides/search/search-in-cli) starts with the current repository and widens with `--repo` or `--all-repos`.

Search reads Entire's indexes, not your local working tree. See [What Is Indexed and When](/guides/search/what-is-indexed) for what it covers and when new work shows up.

<div>
  <iframe />
</div>

## Benefits of Using Search

* Ask why code is the way it is and get the commit, session, and prompt behind it, not just the lines that changed.
* Find precedent in repositories your agent has never cloned.
* Answer in fewer turns than cloning and grepping take, leaving more context window for the task.
* Find literal source text across your repositories in one query.

We benchmarked those claims. On nine engineering-history questions from our own repositories, run ten times each, an agent with Search answered 81 of 90 correctly. The same agent working from full Git history and the GitHub CLI answered 70 of 90, using more than twice the tokens and twice the steps.

These questions come from our own history rather than a public corpus. The harness, tasks, grading, and per-run results are at [entireio/searchmark](https://github.com/entireio/searchmark), so you can rerun it against your own organization.

## How to Use Search

| Surface                                         | Semantic search                                                                                 | Code Search                        |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------- |
| [entire.io](/guides/search/search-in-entire-io) | Use the [**Commits** and **Sessions**](/guides/search/search-in-entire-io#review-results) tabs. | Use the **Code** tab.              |
| [Entire CLI](/guides/search/search-in-cli)      | Run `entire search "QUERY"`.                                                                    | Run `entire search --code "TEXT"`. |

See [Use Search with Your Coding Agent](/guides/search/search-from-your-agent) for the Skill that runs these queries on your agent's behalf.

## Continue With

<CardGroup>
  <Card title="Search in entire.io" icon="globe" href="/guides/search/search-in-entire-io">
    Use semantic search and Code Search from the Search page.
  </Card>

  <Card title="Search in the CLI" icon="terminal" href="/guides/search/search-in-cli">
    Search past work or indexed code from your terminal.
  </Card>

  <Card title="Use Search with Your Coding Agent" icon="robot" href="/guides/search/search-from-your-agent">
    Let an agent find relevant commits and sessions.
  </Card>

  <Card title="Search Past Work and Code" icon="route" href="/learn/search-past-agent-work">
    Practice both kinds of search with one guided tutorial.
  </Card>

  <Card title="What Is Indexed and When" icon="database" href="/guides/search/what-is-indexed">
    Check what Search can find and when new work becomes available.
  </Card>

  <Card title="Search Troubleshooting" icon="wrench" href="/guides/search/troubleshooting">
    Fix login, indexing, scope, and query issues.
  </Card>
</CardGroup>


# Use Search with Your Coding Agent
Source: https://docs.entire.io/guides/search/search-from-your-agent

Ask your coding agent to search past work and indexed source code instead of running the queries yourself.

After you install the `search` Skill, ask your coding agent to find past work or locate text in indexed source files in your own words.

Describe what you are looking for, and the Skill chooses the appropriate search, reviews the results, and summarizes the most relevant matches.

## Before You Start

Install the Skill in the environment where your agent runs, and [log in to Entire](/cli-reference/login) there:

```shell theme={null}
npx skills add https://github.com/entireio/skills --skill search
```

Install version 0.7.2 or later of the [Entire Skills collection](https://github.com/entireio/skills). From that version the Skill widens a search past the current repository on its own, so your agent can find work in a repository it has never cloned.

<Note>
  The CLI can install a smaller helper that runs `entire search --json` instead. Pass `--search-skill` to [`entire agent add`](/cli-reference/agent), which scaffolds it for one selected agent. That helper handles a hit from another repository, and it does not escalate to `--all-repos` on its own the way the Skill does. See [Install CLI Managed Helpers](/learn/skills-overview#install-cli-managed-helpers) for the agents it supports.
</Note>

## See Search in Action

<div>
  <iframe title="Search Skill demo" />
</div>

## What You Can Ask

Run your agent from the repository you want to search.

The examples below assume your agent is running from a local clone of the [Entire CLI repository](https://github.com/entireio/cli).

Unlike a query you type into Search directly, requests to your agent can be phrased as instructions, and the Skill translates them into effective search queries for you.

| Goal                                               | Example prompt                                                          | Search mode                                          |
| -------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
| Find a past decision, feature, or bug              | how did we decide to make history import explicit when enabling Entire? | Semantic search                                      |
| Find text in source code                           | find where the `--import-history` option is implemented                 | Code Search                                          |
| Find precedent in a repository you have not cloned | have we hit this rate-limit error in any of our services before?        | Semantic search, widened past the current repository |

<Tip>
  In clients that expose installed Skills as slash commands, you can also invoke the Skill directly with `/search`, followed by what you want to find.
</Tip>

## What Happens After You Ask

The Skill summarizes the most relevant matches. For past work it answers from each hit's title, snippet, and files touched, and it opens a checkpoint transcript when the top hits are ambiguous or you ask for detail. For source code it returns file paths and matching snippets. Ask a follow-up question to explore a particular result.

A session records what someone decided at the time, not what the code does now. Have your agent confirm that the code it cites still matches the session it found.

## When Search Is Not Needed

When you already know the file and the change is in front of you, let your agent read the working tree directly. Search covers work that is already pushed and indexed.

## Continue With

<CardGroup>
  <Card title="Search in the CLI" icon="terminal" href="/guides/search/search-in-cli">
    Run semantic search or Code Search yourself.
  </Card>

  <Card title="Make Your Agent Use Entire" icon="wand-sparkles" href="/learn/skills">
    Install Skills and learn the main agent workflows.
  </Card>

  <Card title="Search Troubleshooting" icon="stethoscope" href="/guides/search/troubleshooting">
    Fix login, scope, and agent adoption problems.
  </Card>
</CardGroup>


# Search in the CLI
Source: https://docs.entire.io/guides/search/search-in-cli

Search past agent work or indexed source code from the Entire CLI.

## Run Search

First, [log in to Entire](/cli-reference/login):

```shell theme={null}
entire login
```

Run Search from a Git repository:

```shell theme={null}
entire search
```

By default, the CLI searches the current repository. Running the command without a query opens the interactive search.

Search reads pushed content from Entire's indexes. It does not search uncommitted changes or commits that exist only in your local clone. See [What Is Indexed and When](/guides/search/what-is-indexed).

## Enter a Query

The example queries below come from the indexed [Entire CLI repository](https://entire.io/gh/entireio/cli). They show how Search behaves, and you need access to that repository to reproduce them.

### Find Past Work

To find related checkpoints, sessions, and commits, enter a short phrase or ask a natural-language question:

```shell Short phrase example theme={null}
entire search "history import when enabling Entire"
```

```shell Natural-language question example theme={null}
entire search "how did we decide to make history import explicit when enabling Entire?"
```

Semantic search matches meaning and keywords, so describe what you are looking for rather than giving an instruction. See [Find Past Work](/guides/search/search-in-entire-io#find-past-work) for how wording changes the match.

### Find Text in Source Code

Add `--code` to find literal text in indexed source files:

```shell Literal text example theme={null}
entire search --code "import-history"
```

## Review Results

Interactive search runs the query against history and source code. Enter a query, press Enter, and use the number keys to move between result types:

* `1`: **Commits**, history results
* `2`: **Sessions**, history results
* `3`: **Code**, literal matches grouped by file

Search folds checkpoint matches into their owning sessions. You can still open a checkpoint directly by ID:

```shell theme={null}
entire checkpoint explain CHECKPOINT_ID
```

For a checkpoint from another GitHub repository, add `--repo OWNER/REPO` and use the full checkpoint ID.

Use `Up` and `Down` or `k` and `j` to move through results, and press `Enter` to open the selected result. Press `/` to edit the query, and use `n` and `p` or `Right` and `Left` to change pages. In a detail view, press `Esc` to return to the results. From the results, `Esc` or `q` closes Search.

## Filter Results

Filter past-work results by author, branch, or date. For example:

```shell theme={null}
entire search "history import when enabling Entire" branch:cli-onboard
```

To search a repository other than the current one, use `--repo`:

```shell theme={null}
entire search "history import when enabling Entire" --repo entireio/cli
```

For all supported flags, inline filters, and repository formats, see the [`search` command reference](/cli-reference/search).

## Use Search in Scripts

Add `--json` to return machine-readable results for scripts, automation, or agent instructions:

```shell theme={null}
entire search "history import when enabling Entire" --repo entireio/cli --json
```

For agent workflows, combine `--compact` and `--limit` to reduce the response size:

```shell theme={null}
entire search "history import when enabling Entire" --compact --limit 5
```

`--compact` implies `--json` and returns identifiers, ranking metadata, and truncated titles instead of full prompts. Results also include repository, branch, author, date, files touched, and match snippets when available. The flag applies to semantic search only and cannot be combined with `--code`. `--limit` sets the maximum results per page for semantic search, or the maximum total results with `--code`.

## Continue With

<CardGroup>
  <Card title="Search in entire.io" icon="globe" href="/guides/search/search-in-entire-io">
    Browse history and code results visually.
  </Card>

  <Card title="Use Search with Your Coding Agent" icon="robot" href="/guides/search/search-from-your-agent">
    Let a Skill run these queries on your agent's behalf.
  </Card>

  <Card title="Search Command Reference" icon="terminal" href="/cli-reference/search">
    See search syntax, filters, and output options.
  </Card>

  <Card title="What Is Indexed and When" icon="database" href="/guides/search/what-is-indexed">
    Check availability, timing, and repository scope.
  </Card>
</CardGroup>


# Search in entire.io
Source: https://docs.entire.io/guides/search/search-in-entire-io

Find past agent work and indexed source code from your browser.

## Open Search

Once you are [logged in to Entire](/cli-reference/login), open **Search** from the entire.io sidebar.

<Note>
  You must be logged in to use Search, including when searching public repositories.
</Note>

You can also:

* press `/` to open Search directly
* press `Command-K` on macOS or `Ctrl-K` elsewhere, enter a query, and choose the Search action

With an empty query, Search shows your recent searches.

<div>
  <iframe />
</div>

## Choose Repositories

By default, Search includes every indexed repository you can access. Use the **Repository** filter to search one or more specific repositories.

You do not need a local clone to search a repository in entire.io. The repository must be available to your Entire account and indexed. If it does not appear in the filter, you cannot search it from entire.io yet.

<div>
  <iframe />
</div>

## Enter a Query

Enter a phrase, question, function name, error message, or other text.

The examples below come from the indexed [Entire CLI repository](https://entire.io/gh/entireio/cli). They show how Search behaves, but this repository may not appear in your **Repository** filter.

### Find Past Work

To find related past work, enter a short phrase or ask a natural-language question.

Semantic search matches meaning and keywords, so describe what you are looking for rather than giving an instruction. A query like `git optimization` works better than `show me all of the latest git optimizations`: words such as "show me all of the" do not appear in the work itself and dilute the match. To find recent work, use the date filter instead of words like "latest".

```text Short phrase example theme={null}
history import when enabling Entire
```

```text Natural-language question example theme={null}
how did we decide to make history import explicit when enabling Entire?
```

<div>
  <iframe />
</div>

### Find Source Code

Use the **Code** tab to search for code or text such as a function name, error message, or configuration option in your source files:

```text Literal text example theme={null}
import-history
```

<div>
  <iframe />
</div>

## Review Results

After you enter a query, choose a tab to review one kind of result:

* **Commits** show related Git commits.
* **Sessions** show related agent conversations.
* **Code** shows lines containing literal matches from indexed source files.

<div>
  <iframe />
</div>

## Filter Results

Filter past-work results by repository, date, or branch, and sort them by relevance, date, author, or title. You can filter code results by repository.

Select a commit or session to open it. In **Code**, expand a file to view its matching lines.

<div>
  <iframe />
</div>

## Continue With

<CardGroup>
  <Card title="Search in the CLI" icon="terminal" href="/guides/search/search-in-cli">
    Run both search modes from your terminal.
  </Card>

  <Card title="Search Past Work and Code" icon="route" href="/learn/search-past-agent-work">
    Practice both kinds of search with one guided tutorial.
  </Card>

  <Card title="Use Search with Your Coding Agent" icon="robot" href="/guides/search/search-from-your-agent">
    Let a Skill run these queries on your agent's behalf.
  </Card>
</CardGroup>


# Search Troubleshooting
Source: https://docs.entire.io/guides/search/troubleshooting

Fix common semantic search and Code Search issues in the CLI, entire.io, and the `search` Skill.

Use this page when Search does not appear or cannot find the work or code you expect.

Before troubleshooting, review [What Is Indexed and When](/guides/search/what-is-indexed). Local-only work, indexing delay, repository scope, and a valid query with no matches can all explain an empty result.

## Login and Setup

<AccordionGroup>
  <Accordion title="The CLI Says You Are Not Authenticated">
    Run:

    ```shell theme={null}
    entire login
    ```

    Search only returns repositories, history, and code your account can access.
  </Accordion>

  <Accordion title="`entire search` Does Not Appear in `entire --help`">
    [Update the Entire CLI](/installation#install-and-update-entire), then check the installed version:

    ```shell theme={null}
    entire version
    ```

    `entire checkpoint search` is an equivalent alias in every version.
  </Accordion>
</AccordionGroup>

## Your Agent Is Not Using Search

<AccordionGroup>
  <Accordion title="The Search Skill Returns No Useful History">
    Confirm the agent has the [Skills workflow](/learn/skills) installed and can run `entire search --json`.

    Make the prompt more specific:

    ```text theme={null}
    search past work for duplicate validation in the checkout form
    ```
  </Accordion>
</AccordionGroup>

## Results Are Missing or Incomplete

<AccordionGroup>
  <Accordion title="Recent Work or Code Does Not Appear">
    Confirm the work has been committed and pushed, then give Entire a couple minutes to index it.

    Check that the current repository is Entire-enabled:

    ```shell theme={null}
    entire status
    ```

    If the work happened in another repository, use `--repo OWNER/REPO` or `--all-repos`.
  </Accordion>

  <Accordion title="Search Warns That Results May Be Incomplete">
    A query fans out across regions, and a slow or unreachable one degrades the response instead of hanging it. entire.io reports that some sources were unavailable, and the CLI writes `results may be incomplete` to standard error.

    Run the query again. If the warning persists, scope it to a repository that lives outside the affected region:

    ```shell theme={null}
    entire search "retry logic" --repo OWNER/REPO
    ```

    One query fans out to every region holding repositories you can access, so narrowing to a repository in the failing region does not help. That is where the query has to go. Check [status.entire.io](https://status.entire.io/) for a regional incident.

    Semantic search reports this warning on standard error only, so `--json` output carries no sign of it. Code Search reports the affected jurisdictions in its JSON.
  </Accordion>
</AccordionGroup>

## Results Are Not What You Expected

<AccordionGroup>
  <Accordion title="Search Returns Results from the Wrong Scope">
    CLI search is scoped to the current repository by default, while entire.io searches all accessible indexed repositories.

    Search one repository from the CLI:

    ```shell theme={null}
    entire search "retry logic" --repo OWNER/REPO
    ```

    Search all accessible repositories:

    ```shell theme={null}
    entire search "retry logic" --all-repos
    ```
  </Accordion>

  <Accordion title="Search Opens an Interactive View When You Expected Plain Output">
    Use `--json` for scripts, automation, or agent instructions:

    ```shell theme={null}
    entire search "auth token refresh" --json
    ```

    Running a semantic search in a terminal opens the interactive results view. Redirected or piped output is JSON automatically.
  </Accordion>

  <Accordion title="Past-Work Results Are Too Broad">
    Add a feature name, error message, file, decision, or filter that would have appeared in the prompt, commit, or transcript:

    ```shell theme={null}
    entire search "duplicate validation error banner" branch:main date:month
    ```
  </Accordion>

  <Accordion title="Code Search Does Not Find the Expected Code">
    Code Search matches literal text, not a description of behavior. Search for a function or variable name, error message, config key, or unique string that appears in the file.

    If you remember the work but not the source text, use semantic and keyword search without `--code`.
  </Accordion>

  <Accordion title="A Multi-Term Code Search Returns Nothing">
    Code Search matches your query literally, so a phrase of several words often has no match even when each word appears in the repository. Search one distinctive token instead:

    ```shell theme={null}
    entire search --code "import-history"
    ```

    Use semantic search without `--code` when you want to describe the change rather than name the text.
  </Accordion>

  <Accordion title="`author:`, `branch:`, or `date:` Do Not Filter Code Search">
    Code Search supports only the `repo:` inline filter. It reads the other tokens as literal query text. Use semantic search without `--code` when you need author, branch, or date filters.
  </Accordion>

  <Accordion title="Can Code Search Match Exact Letter Case?">
    Not currently. The CLI accepts `--case-sensitive`, but the search backend does not yet apply it.
  </Accordion>

  <Accordion title="`checkpoint explain --repo` Rejects a Commit SHA">
    `entire checkpoint explain` takes a checkpoint ID or a commit SHA, and it resolves a commit through the `Entire-Checkpoint` trailer in your local clone. Adding `--repo` removes that fallback, so a cross-repository lookup needs the full [checkpoint ID](/glossary#checkpoint-id) the result carries rather than a commit SHA.

    ```shell theme={null}
    entire checkpoint explain 01KVBJCWYA4YW6J5M9GP655HZN --repo OWNER/REPO --no-pager
    ```
  </Accordion>
</AccordionGroup>

## Continue With

<CardGroup>
  <Card title="Search" icon="magnifying-glass" href="/guides/search/overview">
    Compare semantic and keyword search with literal Code Search.
  </Card>

  <Card title="Search in the CLI" icon="terminal" href="/guides/search/search-in-cli">
    Review both CLI search modes.
  </Card>

  <Card title="What Is Indexed and When" icon="database" href="/guides/search/what-is-indexed">
    Check availability, timing, scope, and empty-result expectations.
  </Card>
</CardGroup>


# What Is Indexed and When
Source: https://docs.entire.io/guides/search/what-is-indexed

Understand what Search can find, when new content appears, and how repository scope affects results.

Search queries Entire's indexes. It does not read your local working tree.

## What Search Indexes

| Search mode     | Indexed content                                                                           | Results                         |
| --------------- | ----------------------------------------------------------------------------------------- | ------------------------------- |
| Semantic search | Git commits from repositories Entire has synced and agent history pushed with checkpoints | Commits and sessions            |
| Code Search     | Text from tracked files available in an indexed repository                                | Literal matches grouped by file |

Semantic search indexes user prompts and assistant prose. It leaves out tool-only turns and the code inside a transcript, and folds checkpoint matches into their owning sessions. If you have the checkpoint ID, open it directly:

```shell theme={null}
entire checkpoint explain CHECKPOINT_ID
```

For a checkpoint from another GitHub repository, add `--repo OWNER/REPO` and use the full checkpoint ID.

Code Search does not find uncommitted changes, untracked files, commits that exist only in your local clone, or branches other than the one Entire indexes.

## When New Content Appears

Commit and push the branch that contains your work. Push the checkpoint data so semantic search can index agent-session content.

Indexing runs after your content reaches Entire, so recent work may not appear right away. Give it a couple of minutes before treating a missing result as a problem.

## Which Repositories Search Includes

The CLI searches the current repository by default. Use `--repo` for a specific indexed repository or `--all-repos` for all indexed repositories your account can access:

```shell theme={null}
entire search "retry logic" --repo entireio/cli
entire search "retry logic" --all-repos
```

By default, entire.io searches all accessible indexed repositories. Use the **Repository** filter to narrow the scope.

A local clone does not make a repository searchable. Your Entire account needs access to it, and Entire must finish syncing and indexing it.

## What an Empty Result Means

An empty result usually means the search worked and found nothing. It is not by itself a sign of an authentication or indexing error.

Before changing the query, confirm you pushed the work, gave indexing time, and searched the right repository. Then check the search mode:

* Use semantic search for prompts, decisions, commits, and agent-session context.
* Use Code Search for literal source text such as function names, error messages, and configuration keys.

If the content should be indexed and the scope is correct, continue with [Search Troubleshooting](/guides/search/troubleshooting).

## Continue With

<CardGroup>
  <Card title="Search in entire.io" icon="globe" href="/guides/search/search-in-entire-io">
    Search accessible indexed repositories in the browser.
  </Card>

  <Card title="Search in the CLI" icon="terminal" href="/guides/search/search-in-cli">
    Semantic and Code Search from your terminal.
  </Card>

  <Card title="Search Troubleshooting" icon="wrench" href="/guides/search/troubleshooting">
    Diagnose missing commands, results, or repositories.
  </Card>
</CardGroup>


# Attach Sessions
Source: https://docs.entire.io/guides/sessions/attach-sessions

Link an existing agent session to a commit and checkpoint.

Attach a session when useful agent context exists, but Entire did not link it automatically.

## When to Attach a Session

Use `entire session attach` when:

* hooks were not installed when the session started
* hooks did not fire
* a research session should be linked to the latest commit
* a completed agent review should be preserved as review context

## Attach a Session

Attach reads an existing agent transcript, creates or updates a checkpoint, and links that context to the last commit.

```bash theme={null}
entire session attach SESSION_ID --agent AGENT
```

If the last commit already has an `Entire-Checkpoint` trailer, the session is added to that checkpoint. Otherwise, Entire creates a checkpoint and can amend the last commit with the trailer.

## Attach without Prompts

Use `--force` when you want Entire to skip confirmation and amend the last commit:

```bash theme={null}
entire session attach SESSION_ID --agent AGENT --force
```

## Attach a Review Session

Use `--review` when the session was an agent review of existing work:

```bash theme={null}
entire session attach SESSION_ID --agent codex --review
```

If the review used specific Skills, declare them with `--skills`:

```bash theme={null}
entire session attach SESSION_ID --agent codex --review --skills review
```

## Continue With

<CardGroup>
  <Card title="List Sessions" icon="list" href="/guides/sessions/list-sessions">
    Find the session ID to attach.
  </Card>

  <Card title="session attach Command Reference" icon="link" href="/cli-reference/session#session-attach">
    See attach flags and examples.
  </Card>

  <Card title="Import Past Sessions" icon="terminal" href="/guides/sessions/import-past-agent-history">
    Bring past local agent sessions into Entire as read-only checkpoints.
  </Card>
</CardGroup>


# Import Past Sessions
Source: https://docs.entire.io/guides/sessions/import-past-agent-history

Bring past local agent sessions into Entire as read-only checkpoints.

Import past sessions when useful agent context exists locally, but Entire did not capture it while the work happened.

<Frame>
  <div>
    <iframe title="Import existing Claude Code sessions demo" />
  </div>
</Frame>

## When to Import Past Sessions

Use `entire import` when:

* you enabled Entire after useful agent work already happened
* you want past local agent sessions to become searchable in Entire
* you want to import sessions from an agent's local transcript store

| If you want to                               | Use                                                         |
| -------------------------------------------- | ----------------------------------------------------------- |
| Bring past local agent sessions into Entire  | `entire import AGENT`                                       |
| Link one missed session to the latest commit | [`entire session attach`](/guides/sessions/attach-sessions) |
| Continue working from an earlier session     | [`entire session resume`](/guides/sessions/resume-sessions) |

## Preview an Import

Use `--dry-run` to see what Entire would import before writing checkpoints:

```bash theme={null}
entire import claude-code --dry-run
```

The preview shows how many sessions and turns Entire found, what would be imported, and what was already imported.

## Import Past Sessions

Import reads agent transcripts for the current repository, creates read-only checkpoints, and makes that history available in Entire.

Run import from inside the repository whose agent history you want to bring into Entire:

```bash theme={null}
entire import claude-code
```

Replace `claude-code` with the agent you want to import from. Run `entire import --help` or see the [import command reference](/cli-reference/import) for supported agents and flags.

## Import Specific Sessions

Use `--session` when you only want to import a specific session:

```bash theme={null}
entire import claude-code --session SESSION_ID
```

You can repeat `--session` to import more than one session.

## Import from a Custom Transcript Path

Use `--path` when the agent transcripts are stored somewhere other than the default location:

```bash theme={null}
entire import claude-code --path TRANSCRIPT_DIRECTORY
```

## What Imported Sessions Become

Imported sessions are stored as read-only checkpoints in your repository's [checkpoint storage](/guides/checkpoints/checkpoint-storage), alongside the checkpoints Entire captures live.

Imported checkpoints are:

* searchable
* explainable
* idempotent, so re-running import skips turns that already exist
* not linked to a Git commit
* not rewindable

## Continue With

<CardGroup>
  <Card title="Search Past Work" icon="sparkles" href="/guides/search/overview">
    Search imported history by phrase, meaning, or agent context.
  </Card>

  <Card title="import Command Reference" icon="terminal" href="/cli-reference/import">
    See import syntax, flags, and supported agents.
  </Card>

  <Card title="Attach Sessions" icon="link" href="/guides/sessions/attach-sessions">
    Link a missed session to the latest commit.
  </Card>

  <Card title="Inspect Sessions" icon="terminal" href="/guides/sessions/inspect-sessions-in-cli">
    Inspect session metadata and transcript output.
  </Card>
</CardGroup>


# Inspect Sessions in CLI
Source: https://docs.entire.io/guides/sessions/inspect-sessions-in-cli

Inspect session metadata, transcript output, and token usage from the CLI.

Use CLI inspection when you want session details in your terminal, need JSON for automation, or want to export raw transcript data.

## Inspect Session Metadata

Inspect a specific session:

```bash theme={null}
entire session info SESSION_ID
```

`entire session info` shows the agent, model, status, worktree, timing, token usage, checkpoint links, and files touched.

For structured output:

```bash theme={null}
entire session info SESSION_ID --json
```

## Inspect the Current Session

If you do not know the session ID yet, start with the current worktree:

```bash theme={null}
entire session current
entire session current --json
```

## Export Transcript Data

Use `--transcript` when you need the raw agent transcript:

```bash theme={null}
entire session current --transcript > session.jsonl
entire session info SESSION_ID --transcript > session.jsonl
```

Transcript format depends on the agent.

## Review Token Usage

Use `entire session tokens` to inspect token usage and optimization recommendations:

```bash theme={null}
entire session tokens
entire session tokens SESSION_ID
```

For compact guidance that an agent can act on:

```bash theme={null}
entire session tokens --agent-brief
```

## Continue With

<CardGroup>
  <Card title="List Sessions" icon="list" href="/guides/sessions/list-sessions">
    Find the current session or copy a session ID.
  </Card>

  <Card title="session Command Reference" icon="terminal" href="/cli-reference/session">
    See session subcommands and flags.
  </Card>
</CardGroup>


# List Sessions
Source: https://docs.entire.io/guides/sessions/list-sessions

Find active and ended sessions from the CLI.

Use the CLI when you need to find the current session, list older sessions, or get the session ID for another command.

## Check Active Sessions

Use `entire status` to see active sessions in the current repository:

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

This is the fastest way to see whether Entire is capturing an agent session right now.

## Show the Current Session

Use `entire session current` when you want the most relevant session for the current worktree:

```bash theme={null}
entire session current
```

For structured output:

```bash theme={null}
entire session current --json
```

## List All Sessions

Use `entire session list` to see sessions tracked by Entire, including ended sessions:

```bash theme={null}
entire session list
```

For automation:

```bash theme={null}
entire session list --json
```

## Find a Session ID

Most session commands accept a session ID:

```bash theme={null}
entire session info SESSION_ID
entire session stop SESSION_ID
entire session tokens SESSION_ID
```

Use `entire status`, `entire session current`, or `entire session list` when you need to copy that ID.

## Continue With

<CardGroup>
  <Card title="Inspect Sessions" icon="terminal" href="/guides/sessions/inspect-sessions-in-cli">
    Inspect metadata, transcripts, and token usage.
  </Card>

  <Card title="Stop Sessions" icon="circle-stop" href="/guides/sessions/stop-sessions">
    End stale or active sessions from the CLI.
  </Card>
</CardGroup>


# Overview
Source: https://docs.entire.io/guides/sessions/overview

Enable Entire and automatically store your agent sessions in Git on every push.

<iframe title="Entire 101 | Ep. 2: How to Create Your First Checkpoint" />

Entire keeps two connected records of AI-assisted work. A [session](/glossary#session) is the conversation: the prompts, responses, tool calls, and file changes that happen while an agent works. A [checkpoint](/glossary#checkpoint) is the individual unit of that context, saved when you commit and linked to the commit. Entire captures both automatically and stores them alongside your commits in the repository, so nothing is lost when a terminal closes or a conversation ends.

## What Is a Session?

A session is the complete record of a coding interaction between you and your AI agent. It captures:

* prompts and agent responses
* tool calls, shell commands, and file operations
* files created, modified, or deleted
* time-stamped agent and model metadata
* line attribution showing which changes came from the agent versus a human.

## What Is a Checkpoint?

A checkpoint is the unit of context Entire saves behind an AI-assisted change. When you or your agent commit, Entire saves the captured session context, such as the prompts, transcript, and tool calls that led to the commit, as a checkpoint and links it to that commit. Each checkpoint has an ID, and Entire adds it to the commit message with an [`Entire-Checkpoint` trailer](/glossary#entire-checkpoint).

A single session can produce many checkpoints, one for each commit you make while it runs. A single checkpoint can also draw on more than one session when several contributed to the same change. See [How Sessions and Checkpoints Relate](#how-sessions-and-checkpoints-relate) for the common shapes.

A checkpoint stores the available context behind the change, including:

* the linked Git commit
* the agent session or sessions behind the change
* prompts and transcript
* tool activity
* changed files
* token usage, when available
* [AI attribution](/guides/sessions/sessions-in-entire-io#files-and-attribution) for the changed lines

## How Sessions and Checkpoints Relate

Sessions and checkpoints have a flexible relationship that mirrors how you actually work:

| Scenario                                | How it looks in Entire                                                              |
| --------------------------------------- | ----------------------------------------------------------------------------------- |
| One session, one checkpoint             | Most common. You ask the agent to do something, it does the work, and you commit.   |
| One checkpoint, multiple sessions       | Several sessions contribute to the same change before you commit.                   |
| One session, multiple checkpoints       | One longer session keeps going while you commit multiple checkpoints along the way. |
| Multiple sessions, multiple checkpoints | Multiple sessions and commits are linked across a larger or parallel piece of work. |

## How It Works

Once you [enable Entire](/quickstart) for a repository, the [CLI](/cli-reference) uses Git hooks and [agent hooks](/agents/overview) to capture session context while you work. When you commit, Entire saves that context as a checkpoint and links it to the commit. In practice, you just work, commit, and the context follows along. See [Capture Sessions and Their Checkpoints](/guides/checkpoints/capture-checkpoints) for setup details and commit-linking options.

If capture started late, hooks did not fire, or a session was useful even though it did not produce file changes, you can [attach the session](/guides/sessions/attach-sessions) to a checkpoint after the fact.

## Why This Helps

* Resuming exactly where you left off. Pick up prior agent work from a session or a branch instead of starting over. See [Resume Sessions](/guides/sessions/resume-sessions).
* Seeing what actually happened. Review prompts, transcripts, tool calls, and file changes for any session without guessing. Read more on [Sessions in entire.io](/guides/sessions/sessions-in-entire-io) and [Inspect Sessions in CLI](/guides/sessions/inspect-sessions-in-cli).
* Tracing any commit back to the conversation that produced it. Every commit made during a session is linked to a checkpoint, so you can go from code to context easily. See [Inspect Checkpoints](/guides/checkpoints/inspect-checkpoints).
* Knowing who wrote what. Line attribution shows how much of a change came from the agent versus a human. See [entire blame](/cli-reference/blame).
* Recovering missed context. Attach a session after the fact if capture started late or hooks didn't start. See [Attach Sessions](/guides/sessions/attach-sessions).
* Bringing in past work. Import agent history that predates Entire, and find prior context by meaning across past sessions. Read more on [Search](/guides/search/overview).

## How Checkpoints Connect to Git

Entire stores checkpoint metadata [in your repository](/security#where-your-data-lives), in its own Git ref or on the checkpoints branch depending on the [storage backend](/guides/checkpoints/checkpoint-storage). Your normal Git history stays clean. Entire does not add extra commits to your working branch.

## Get Started

| Task                                                               | Where to go                                                                       |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| Review prompts, transcript, tools, files, and attribution visually | [Sessions in entire.io](/guides/sessions/sessions-in-entire-io)                   |
| Find a session ID or see what is active                            | [List Sessions](/guides/sessions/list-sessions)                                   |
| Inspect metadata, transcripts, or token usage from the terminal    | [Inspect Sessions in CLI](/guides/sessions/inspect-sessions-in-cli)               |
| Open a checkpoint from the CLI or entire.io                        | [Inspect Checkpoints](/guides/checkpoints/inspect-checkpoints)                    |
| Control when and how sessions and checkpoints are captured         | [Capture Sessions and Their Checkpoints](/guides/checkpoints/capture-checkpoints) |
| Choose where checkpoint data is stored                             | [Storage Backends](/guides/checkpoints/checkpoint-storage)                        |
| Attach missed session context                                      | [Attach Sessions](/guides/sessions/attach-sessions)                               |
| Continue previous agent work                                       | [Resume Sessions](/guides/sessions/resume-sessions)                               |
| Bring past local agent sessions into Entire                        | [Import Past Sessions](/guides/sessions/import-past-agent-history)                |
| Find prior session context by meaning                              | [Search](/guides/search/overview)                                                 |
| Package context for another agent                                  | [Make Your Agent Use Entire](/learn/skills)                                       |

## Continue With

<CardGroup>
  <Card title="Sessions in entire.io" icon="message" href="/guides/sessions/sessions-in-entire-io">
    Review timelines, transcripts, files, and attribution visually.
  </Card>

  <Card title="Inspect Checkpoints" icon="magnifying-glass" href="/guides/checkpoints/inspect-checkpoints">
    Open a checkpoint from the CLI or entire.io.
  </Card>

  <Card title="List Sessions" icon="list" href="/guides/sessions/list-sessions">
    Find active sessions and session IDs from the terminal.
  </Card>

  <Card title="Attach Sessions" icon="link" href="/guides/sessions/attach-sessions">
    Recover missed context and link it to a checkpoint.
  </Card>

  <Card title="Resume Sessions" icon="code-branch" href="/guides/sessions/resume-sessions">
    Continue prior agent work from a session or branch.
  </Card>

  <Card title="Storage Backends" icon="database" href="/guides/checkpoints/checkpoint-storage">
    Choose between a Git ref and the checkpoints branch.
  </Card>

  <Card title="Investigate Why Code Exists" icon="search-code" href="/learn/investigate-why-code-exists">
    Use attribution and checkpoint context to investigate a surprising line.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/sessions/troubleshooting">
    Resolve missing, stale, or unlinked sessions and checkpoints.
  </Card>
</CardGroup>


# Resume Sessions
Source: https://docs.entire.io/guides/sessions/resume-sessions

Continue previous agent work from a stopped session or branch.

Resume a session when you want to continue previous agent work instead of starting from scratch.

<Frame>
  <div>
    <iframe title="Entire session resume picker demo" />
  </div>
</Frame>

## Resume from the Picker

Run resume with no argument to open an interactive picker of stopped sessions across worktrees:

```bash theme={null}
entire session resume
```

After you choose a session, Entire checks out the related branch, restores the session log if needed, and asks whether to start the agent.

## Resume from a Branch

If you already know the branch, pass it directly:

```bash theme={null}
entire session resume BRANCH
```

Entire finds the session ID from checkpoint-linked commits on that branch.

## Force Resume from an Older Checkpoint

Use `--force` when you need to resume from an older checkpoint without confirmation:

```bash theme={null}
entire session resume BRANCH --force
```

<Warning>
  If newer commits without checkpoints exist on the branch, resume can reset Git state to the most recent commit with a checkpoint. Entire prompts before doing this unless you force it.
</Warning>

## Continue With

<CardGroup>
  <Card title="List Sessions" icon="list" href="/guides/sessions/list-sessions">
    Find sessions before resuming work.
  </Card>

  <Card title="session resume Command Reference" icon="code-branch" href="/cli-reference/session#session-resume">
    See resume behavior and flags.
  </Card>
</CardGroup>


# Sessions in entire.io
Source: https://docs.entire.io/guides/sessions/sessions-in-entire-io

Review session timelines, transcripts, tool calls, files, and attribution in entire.io.

Use entire.io when you want to visually inspect what happened during an agent session and move between the session, checkpoint, and file changes.

## Open a Session

Open the checkpoint that contains the session you want to inspect, then use the session list to choose the agent work behind that checkpoint.

<Frame>
  <img alt="Sessions list inside a checkpoint" />
</Frame>

Each session row shows the agent, step count, opening prompt, and relative timestamp.

## Session Timeline

The timeline shows the conversation in order, including prompts, agent responses, expandable tool calls, and runtime tags. The metadata panel summarizes the agent, model, duration, and token usage when available.

<Frame>
  <img alt="Session timeline view" />
</Frame>

Use timeline filters to focus on prompts, responses, intermediate steps, checkpoints, or specific tool-call types.

## Files and Attribution

Files modified during a session are reviewed through the checkpoint that owns the session. When a checkpoint includes multiple sessions, the diff shows the combined change, while session details preserve the per-session context.

<Frame>
  <img alt="Changes tab showing a file diff" />
</Frame>

Entire also calculates how much of a checkpoint came from the agent versus a human edit. Attribution helps reviewers decide when to inspect the transcript more closely.

<Frame>
  <video>
    <source type="video/mp4" />
  </video>
</Frame>

The breakdown can include:

* agent-written lines
* human-added, modified, or removed lines
* agent percentage for the checkpoint or session

## Sub-Agent Sessions

When an agent spawns a sub-agent, Entire records it against the parent session and materializes its transcript into the parent's next checkpoint. The session list shows the parent, so review the sub-agent's file changes through the checkpoint that owns it. entire.io does not browse sub-agent records on their own yet.

[Agent Integrations](/agents/overview#compare-built-in-integrations) covers which agents record which sub-agents and which roll their tokens up.

## Continue With

<CardGroup>
  <Card title="Inspect Checkpoints in entire.io" icon="browser" href="/guides/checkpoints/inspect-in-entire-io">
    Open the checkpoint context that owns a session.
  </Card>

  <Card title="Inspect Sessions in CLI" icon="terminal" href="/guides/sessions/inspect-sessions-in-cli">
    Inspect session metadata, transcripts, and token usage from the terminal.
  </Card>
</CardGroup>


# Stop Sessions
Source: https://docs.entire.io/guides/sessions/stop-sessions

End stale or active sessions from the CLI.

Stop a session when Entire still considers it active, but the agent run is finished or no longer relevant.

## Stop One Session

Find the session ID:

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

Then stop that session:

```bash theme={null}
entire session stop SESSION_ID
```

## Stop All Active Sessions

Use `--all` when several stale sessions are active:

```bash theme={null}
entire session stop --all
```

To skip confirmation:

```bash theme={null}
entire session stop --all --force
```

<Warning>
  `entire session stop` marks sessions as ended. It does not create a checkpoint or flush pending work. Commit first when you want session context linked to code changes.
</Warning>

## Continue With

<CardGroup>
  <Card title="List Sessions" icon="list" href="/guides/sessions/list-sessions">
    Find active sessions and session IDs.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/sessions/troubleshooting">
    Resolve stale, missing, or misplaced sessions.
  </Card>
</CardGroup>


# Troubleshooting
Source: https://docs.entire.io/guides/sessions/troubleshooting

Resolve missing, stale, or unlinked sessions, and fix checkpoint capture, linking, and sync issues.

Use this page when a session is missing or stale, a checkpoint was not created, or a checkpoint did not link or sync where you expected.

## Sessions

<AccordionGroup>
  <Accordion title="No Active Session Appears">
    Check repository and hook status:

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

    If Entire is not enabled, start with:

    ```bash theme={null}
    entire enable --agent AGENT
    ```

    If Entire is already enabled but the agent is not configured, add it:

    ```bash theme={null}
    entire agent add AGENT
    ```

    Then start your agent from inside the enabled repository. Agent hooks only capture work for agents that are configured for that repo.
  </Accordion>

  <Accordion title="The Session Did Not Link to a Commit">
    A normal committed checkpoint needs both captured session context and a Git commit.

    If the session exists but was not linked, attach it to the latest commit:

    ```bash theme={null}
    entire session attach SESSION_ID --agent AGENT
    ```

    If the commit already has a checkpoint, Entire adds the session to that checkpoint. Otherwise, Entire can create a new checkpoint and amend the commit with an `Entire-Checkpoint` trailer. See [Attach Sessions](/guides/sessions/attach-sessions) for the full flow.
  </Accordion>

  <Accordion title="The Session Is Attached to the Wrong Worktree">
    If an agent started in one worktree and continued in another, adopt the session into the current repository:

    ```bash theme={null}
    entire session adopt SESSION_ID --from ../source-worktree
    ```

    After adoption, the next commit can link to the session normally.
  </Accordion>

  <Accordion title="Stale Sessions Keep Showing Up">
    Use `entire status` to find active and stale sessions. If a session is no longer running, stop it:

    ```bash theme={null}
    entire session stop SESSION_ID
    ```

    For multiple stale sessions:

    ```bash theme={null}
    entire session stop --all
    ```

    If status suggests a repository health issue, run:

    ```bash theme={null}
    entire doctor
    ```
  </Accordion>

  <Accordion title="Token Usage Is Missing">
    Token usage depends on what the agent exposes and when the session data is available. Some agents only expose full token usage after the session ends.

    Check the session details first:

    ```bash theme={null}
    entire session info SESSION_ID
    ```

    Then check token usage:

    ```bash theme={null}
    entire session tokens SESSION_ID
    ```
  </Accordion>

  <Accordion title="The Raw Transcript Is Missing">
    Entire reads transcript data from the agent's session storage. If the agent deleted or moved its local transcript, Entire may still have metadata but not the raw transcript bytes.

    Try:

    ```bash theme={null}
    entire session info SESSION_ID --json
    ```

    If metadata exists but the transcript cannot be streamed, inspect the relevant [agent guide](/agents/overview) for that agent's transcript requirements.
  </Accordion>
</AccordionGroup>

## Checkpoints

<AccordionGroup>
  <Accordion title="Run a Checkpoint Health Check">
    Start with `entire doctor` when `entire status` shows a stale or exited session, checkpoint commands seem to miss data, or you see warnings about metadata branches.

    ```bash theme={null}
    entire doctor
    ```

    `entire doctor` can repair some metadata branch issues and condense stuck sessions into permanent checkpoint storage. It does not fix every checkpoint issue: use [Attach Sessions](/guides/sessions/attach-sessions) for missing commit trailers, and check remote or GitHub permissions for sync problems.

    To move checkpoints off the `entire/checkpoints/v1` branch and into per-checkpoint refs, see [Migrate Existing Checkpoints into Refs](/guides/checkpoints/checkpoint-storage#migrate-existing-checkpoints-into-refs).
  </Accordion>

  <Accordion title="No Checkpoint Appears After a Commit">
    A checkpoint is created when Entire can connect a Git commit to captured agent session context.

    Check these first:

    * Run `entire status` to confirm Entire is enabled in the repository
    * Confirm the repo was set up with `entire enable` or `entire configure`
    * If you committed from a GUI Git client, configure [absolute Git hook paths](/guides/configuration/git-hooks#gui-git-clients)
    * If the agent session started before hooks were installed, start a new session after setup

    If Entire captured the session but did not link it automatically, attach it manually:

    ```bash theme={null}
    entire session attach SESSION_ID -a AGENT
    ```

    See [Attach Sessions](/guides/sessions/attach-sessions) for the full flow.
  </Accordion>

  <Accordion title="The Commit Is Missing the Checkpoint Trailer">
    Entire links a commit to a checkpoint with an `Entire-Checkpoint` trailer.

    If the trailer is missing:

    * The commit may have happened before Entire was enabled
    * The prompt to link the session may have been declined
    * The session may have been created in another folder
    * Git hooks may not have run

    Use `entire checkpoint list` to see whether the checkpoint exists locally. If the session exists but the commit is not linked, use [Attach Sessions](/guides/sessions/attach-sessions).
  </Accordion>

  <Accordion title="The Checkpoint Appears Locally but Not in entire.io">
    entire.io reads checkpoint data after you push it: the per-checkpoint refs on the ref-based backend, or the `entire/checkpoints/v1` branch on the branch-based backend.

    Try this:

    1. Run `git push`
    2. Watch for any Entire warnings during the push
    3. Confirm `push_sessions` is enabled in [checkpoint storage settings](/guides/checkpoints/checkpoint-storage)
    4. Confirm the checkpoints reached the remote with `git ls-remote origin 'refs/entire/checkpoints/*'`, or `git ls-remote origin entire/checkpoints/v1` on the branch-based backend
    5. Confirm the Entire GitHub App can access the repository

    For GitHub App access issues, see [Install the Entire GitHub App](/guides/repositories/github-app-access). For checkpoint push behavior, see [Session Storage](/guides/checkpoints/checkpoint-storage).
  </Accordion>

  <Accordion title="Checkpoint Data Is Going to the Wrong Place">
    By default, Entire pushes checkpoint data to the same remote as your code. If your team stores checkpoint data in a separate repository, configure a checkpoint remote.

    Check `.entire/settings.json` for:

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

    See [checkpoint remote](/guides/checkpoints/store-checkpoints-in-another-repo) for setup details.
  </Accordion>

  <Accordion title="Checkpoint Remote Did Not Sync">
    Checkpoint remote failures do not block your main Git push. Entire saves checkpoint data locally and warns when it cannot push it.

    Common causes:

    * You do not have write access to the checkpoint remote
    * The checkpoint remote repository does not exist
    * `.entire/settings.json` was not committed, so teammates or entire.io cannot discover the setting
    * You are pushing from a fork, and fork detection skipped the organization checkpoint remote

    For checkpoint remote owner rules and push behavior, see [Store Checkpoints in Another Repository](/guides/checkpoints/store-checkpoints-in-another-repo).
  </Accordion>

  <Accordion title="A Squash Merge Lost the Checkpoint Link">
    Some Git hosts can remove commit trailers during squash merges. If the `Entire-Checkpoint` trailer is removed, Entire cannot link the squashed commit back to its checkpoint metadata.

    For GitLab squash merges, 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}
    ```
  </Accordion>

  <Accordion title="A Checkpoint Shows Unknown Author in entire.io">
    entire.io shows `Unknown author` when the commit behind a checkpoint has no author identity that GitHub can match to a user. This usually means the commit was authored with an unexpected Git identity, the author email is not associated with a GitHub account, or GitHub returned commit metadata without a matched username.

    Set your Git author identity to an email associated with your GitHub account, then create and push a new commit:

    ```bash theme={null}
    git config user.email you@example.com
    ```

    `.entire/settings.json` does not affect commit author identity. Only your Git config does.
  </Accordion>

  <Accordion title="Still Stuck?">
    Include these details when asking for help:

    * `entire version`
    * the agent you were using
    * whether the checkpoint appears in `entire checkpoint list`
    * the checkpoint ID, if there is one
    * any warning printed during `git commit` or `git push`

    You can file an issue at [github.com/entireio/cli](https://github.com/entireio/cli) or ask in the [Entire Discord](https://discord.gg/jZJs3Tue4S).
  </Accordion>
</AccordionGroup>

## Continue With

<CardGroup>
  <Card title="List Sessions" icon="list" href="/guides/sessions/list-sessions">
    Find active sessions and session IDs.
  </Card>

  <Card title="Attach Sessions" icon="link" href="/guides/sessions/attach-sessions">
    Recover missed context and link it to a checkpoint.
  </Card>

  <Card title="Stop Sessions" icon="circle-stop" href="/guides/sessions/stop-sessions">
    End stale or active sessions.
  </Card>

  <Card title="Capture Sessions and Their Checkpoints" icon="flag" href="/guides/checkpoints/capture-checkpoints">
    Learn how Entire captures agent sessions and turns them into committed checkpoints.
  </Card>

  <Card title="Storage Backends" icon="database" href="/guides/checkpoints/checkpoint-storage">
    Choose between a Git ref and the checkpoints branch.
  </Card>

  <Card title="Inspect Checkpoints" icon="magnifying-glass" href="/guides/checkpoints/inspect-checkpoints">
    Open a checkpoint from the CLI or entire.io.
  </Card>
</CardGroup>


# Introduction
Source: https://docs.entire.io/index

Coding agents need ideas, decisions, and speed. Entire stores all your code, together with sessions, prompts, and tool calls. And, for maximum agent throughput, it mirrors your Git repos around the world.

## Set Up Entire

Install the CLI, connect your agent, and capture the context behind your work.

<CardGroup>
  <Card title="Install Entire" icon="download" href="/installation">
    Add the CLI to your existing Git workflow.
  </Card>

  <Card title="Connect Your Agent" icon="robot" href="/agents/overview">
    Use Entire with Codex, Claude Code, Cursor, and more.
  </Card>

  <Card title="Capture Your First Checkpoint" icon="flag" href="/guides/checkpoints/capture-checkpoints">
    Save the session and decisions behind a change.
  </Card>
</CardGroup>

## What Entire Does

<CardGroup>
  <Card title="Code Hosting" icon="code-branch" href="/guides/repositories/overview">
    Mirror your repos on Entire so agents clone and push up to 89 times faster than other Git providers. Host code in the US, EU, India, or Australia, and keep pushing on Entire-native branches even when your Git provider is down.
  </Card>

  <Card title="Session Storage" icon="comments" href="/guides/sessions/overview">
    Every commit an agent makes becomes a checkpoint: the code change paired with the prompt, reasoning, and tool calls behind it. Secrets are redacted before anything leaves your machine.
  </Card>

  <Card title="Agentic Search" icon="magnifying-glass" href="/guides/search/overview">
    Search repositories, commits, and agent sessions in one query. Give agents the implementation they need and the reasoning behind it, without retracing old work.
  </Card>

  <Card title="Semantic Graph" icon="diagram-project" href="/guides/graph/overview">
    entire-graph maps the symbols and relationships in your code so agents find answers fast, cutting token spend by up to 71%.
  </Card>

  <Card title="Any Agent" icon="robot" href="/agents/overview">
    Works with Claude Code, Codex, Cursor, Gemini CLI, and more. Our open-source, MIT-licensed CLI captures sessions from any supported agent, and the Agent Integration Protocol adds others.
  </Card>
</CardGroup>

## Why Host Your Code With Entire

Coding agents create much more Git traffic than a typical human workflow. They clone repositories, inspect history, create worktrees, and run tasks in parallel.

Entire provides distributed Git hosting so agents can work from repositories close to where they run. It is up to 89x faster than the competition. You can mirror an existing GitHub repository into one or more Entire regions while keeping GitHub as the upstream source of truth, allowing your agents to clone and pull in parallel. And with Entire-native branches, you can continue pushing even during a GitHub outage, so you and your agents work is not interrupted.

This helps with:

* giving agents faster access to code and Git history
* supporting many concurrent agent workflows
* keeping code in the regions you choose
* continuing working with [Entire-native branches](/guides/repositories/entire-native-branches) when an upstream provider is unavailable

## Why Store Your Sessions with Entire

A diff doesn't clearly explain why a change was made. It does not show the request that started the work, the files an agent inspected, the commands it ran, or the decisions it made along the way. As massive amounts of AI-generated code are created, developers, teams and agents themselves struggle to link the intent back to the code change itself.

Entire captures that missing context and connects it to your Git history. You can use it to:

* review agent work before merging
* trace code back to the prompt and session that created it
* understand why an earlier team or agent chose a particular approach
* resume or hand off work with its context intact
* search prior work instead of understanding it from scratch

Taken together, Entire represents one API for your code and the context that created it. A new system of record for agentic coding.

## How It Works

1. Install the Entire CLI in your repository.
2. Connect Entire to the coding agent you use.
3. [Mirror the repository on Entire](/guides/repositories/mirrors) in the region closest to your agents, and point your Git remote at it.
4. Entire captures sessions and checkpoints as the agent works, and agents clone and push through the mirror.
5. Continue coding with your agent, enabling it with faster clones and the history behind your work.

## What Do You Want to Do?

<CardGroup>
  <Card title="Understand Why Code Changed" icon="code-commit" href="/learn/investigate-why-code-exists">
    Trace a line of code back to the agent session and decisions that produced it.
  </Card>

  <Card title="Mirror a GitHub Repository" icon="clone" href="/learn/mirror-a-github-repository">
    Create a regional mirror so agents clone and fetch from the region you choose.
  </Card>

  <Card title="Find Previous Decisions" icon="sparkles" href="/learn/search-past-agent-work">
    Search sessions, commits, prompts, and files.
  </Card>

  <Card title="Review Agent Work Before You Merge" icon="magnifying-glass" href="/learn/review-and-recap-agent-work">
    Catch issues across agent-generated changes with recap and review.
  </Card>
</CardGroup>

<div>
  <section>
    <div>
      <span>Platforms</span>

      <div>
        Choose Where You Work
      </div>

      <p>
        Capture locally with the CLI. Explore and share history in entire.io.
      </p>
    </div>

    <div>
      <a href="/platforms/cli-and-entire-io#entire-cli">
        <Icon icon="terminal" />

        <span>
          <span>Entire CLI</span>
          <span>Capture sessions, create checkpoints, configure storage, and automate workflows.</span>
        </span>
      </a>

      <a href="/platforms/cli-and-entire-io#entireio">
        <Icon icon="browser" />

        <span>
          <span>entire.io</span>
          <span>Browse sessions, review checkpoints, inspect files, and share context.</span>
        </span>
      </a>
    </div>
  </section>

  <section>
    <div>
      <span>Resources</span>

      <div>
        Looking for Something Specific?
      </div>
    </div>

    <div>
      <a href="/cli-reference">CLI Reference</a>
      <a href="/security">Security and privacy</a>
      <a href="/agents/overview">Supported agents</a>
      <a href="/glossary">Glossary</a>
    </div>
  </section>
</div>


# Installation
Source: https://docs.entire.io/installation

Install, update, verify, and uninstall the Entire CLI.

## System Requirements

* macOS, Linux, or Windows
* Git 2.25 or later
* Bash, Zsh, Fish, or PowerShell
* Windows PowerShell 5.1 or later, for the Windows PowerShell installer

Building from source requires Go 1.26.6 or later.

## Release Channels

Entire ships two release channels:

* `stable`: the default channel for Homebrew, Scoop, `install.sh`, and `install.ps1`
* `nightly`: prerelease builds available through Homebrew, `install.sh`, and `install.ps1`

Scoop supports the stable channel only. For a nightly install on Windows, use `install.ps1`.

## Install and Update Entire

Choose one installation method. Use the update command in the same tab when you want a newer release.

<Tabs>
  <Tab title="macOS with Homebrew">
    Install the stable channel:

    ```bash theme={null}
    brew install --cask entireio/tap/entire
    ```

    Or install the nightly channel:

    ```bash theme={null}
    brew install --cask entireio/tap/entire@nightly
    ```

    The fully qualified cask name adds the `entireio/tap` tap for you, so no separate `brew tap` step is needed.

    Update the channel you installed:

    ```bash theme={null}
    brew upgrade --cask entireio/tap/entire
    ```

    ```bash theme={null}
    brew upgrade --cask entireio/tap/entire@nightly
    ```
  </Tab>

  <Tab title="Linux Install Script">
    Install the stable channel:

    ```bash theme={null}
    curl -fsSL https://entire.io/install.sh | bash
    ```

    Or install the nightly channel:

    ```bash theme={null}
    curl -fsSL https://entire.io/install.sh | bash -s -- --channel nightly
    ```

    The script installs `entire` and `git-remote-entire` in `~/.local/bin`. If that directory is missing from your `PATH`, the script prints the command that adds it to your shell configuration.

    Run the command for your channel again to update Entire.
  </Tab>

  <Tab title="Linux Direct Download">
    Download the stable AMD64 archive and install both executables:

    ```bash theme={null}
    download_dir="$(mktemp -d)"
    mkdir -p "$HOME/.local/bin"
    curl -fsSL https://github.com/entireio/cli/releases/latest/download/entire_linux_amd64.tar.gz \
      -o "$download_dir/entire_linux_amd64.tar.gz"
    tar -xzf "$download_dir/entire_linux_amd64.tar.gz" -C "$download_dir"
    install -m 0755 "$download_dir/entire" "$download_dir/git-remote-entire" "$HOME/.local/bin/"
    rm -rf "$download_dir"
    ```

    For ARM64, replace `amd64` with `arm64` in the archive name:

    ```bash theme={null}
    download_dir="$(mktemp -d)"
    mkdir -p "$HOME/.local/bin"
    curl -fsSL https://github.com/entireio/cli/releases/latest/download/entire_linux_arm64.tar.gz \
      -o "$download_dir/entire_linux_arm64.tar.gz"
    tar -xzf "$download_dir/entire_linux_arm64.tar.gz" -C "$download_dir"
    install -m 0755 "$download_dir/entire" "$download_dir/git-remote-entire" "$HOME/.local/bin/"
    rm -rf "$download_dir"
    ```

    Run the block for your architecture again to update Entire.
  </Tab>

  <Tab title="Windows with PowerShell">
    Install the stable channel from Windows PowerShell 5.1 or later:

    ```powershell theme={null}
    irm https://entire.io/install.ps1 | iex
    ```

    Or install the nightly channel:

    ```powershell theme={null}
    iex "& {$(irm https://entire.io/install.ps1)} -Channel nightly"
    ```

    For the stable channel, the script uses Scoop when Scoop is on your `PATH`, and it adds the Entire bucket first. Without Scoop, and for every nightly install, the script verifies the release checksum, installs `entire.exe` and `git-remote-entire.exe` in `%USERPROFILE%\.local\bin`, and adds that directory to your user `PATH`. Restart your terminal after the script changes your `PATH`.

    The script accepts these options. Pass them with the script block form shown for the nightly channel, because `irm | iex` cannot forward arguments:

    | Option          | Effect                                                                                                                                            |
    | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `-Channel`      | Release channel to install, `stable` or `nightly`. Defaults to `stable`.                                                                          |
    | `-InstallDir`   | Destination for a checksum verified install. Defaults to `$HOME\.local\bin`. Passing it selects the release archive even when Scoop is available. |
    | `-NoPathUpdate` | Leave your user `PATH` unchanged. Applies to release archive installs, because Scoop manages its own `PATH` entry.                                |
    | `-Help`         | Print the usage message.                                                                                                                          |

    <Note>
      In Git Bash, MSYS, or Cygwin, `install.sh` stops and points you to this installer.
    </Note>

    Run the command for your channel again to update Entire.
  </Tab>

  <Tab title="Windows with Scoop">
    These commands drive Scoop directly. The PowerShell installer already uses Scoop for stable installs when Scoop is available.

    Add the Entire bucket once, then install the stable channel:

    ```powershell theme={null}
    scoop bucket add entire https://github.com/entireio/scoop-bucket.git
    scoop install entire/entire
    ```

    Update Scoop and Entire:

    ```powershell theme={null}
    scoop update
    scoop update entire
    ```

    <Note>
      Use `entire/entire` for new installations. Scoop previously used `entire/cli`.
    </Note>
  </Tab>

  <Tab title="Build from Source">
    Install both executables:

    ```bash theme={null}
    go install github.com/entireio/cli/cmd/entire@latest
    go install github.com/entireio/cli/cmd/git-remote-entire@latest
    ```

    Go writes them to `$(go env GOPATH)/bin`. Add that directory to your `PATH` if your shell cannot find `entire`.

    Run both commands again to update the source installation.
  </Tab>
</Tabs>

## Verify the Installation

Run:

```bash theme={null}
entire version
```

Entire CLI 0.10.5 prints three lines. The Go version and platform reflect the release and system you installed:

```text theme={null}
Entire CLI 0.10.5
Go version: go1.26.6
OS/Arch: darwin/arm64
```

Release archives also include `git-remote-entire`. Git invokes this helper when a remote uses an `entire://` URL. Verify that your shell can find both executables:

<Tabs>
  <Tab title="macOS or Linux">
    ```bash theme={null}
    command -v entire
    command -v git-remote-entire
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    Get-Command entire
    Get-Command git-remote-entire
    ```
  </Tab>
</Tabs>

## Installation and Data Locations

The executable location depends on the installation method:

| Method                                  | Location                                                    |
| --------------------------------------- | ----------------------------------------------------------- |
| Homebrew                                | The Homebrew prefix returned by `brew --prefix`             |
| Linux install script or direct download | `~/.local/bin`                                              |
| Windows PowerShell script without Scoop | `%USERPROFILE%\.local\bin`, or the `-InstallDir` you passed |
| Scoop                                   | The directory returned by `scoop prefix entire`             |
| Go                                      | `$(go env GOPATH)/bin`                                      |

Entire stores repository settings in `.entire/settings.json` and personal repository overrides in `.entire/settings.local.json`. See [Local, Project, and Global Settings](/guides/configuration/settings-layers) for those files.

The CLI also uses these directories for each user:

| Data                                                     | Default                         | Override                                                                |
| -------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
| Login contexts, update state, and file based credentials | `~/.config/entire`              | `ENTIRE_CONFIG_DIR`                                                     |
| Discovery caches                                         | `~/.cache/entire`               | `XDG_CACHE_HOME`, with `/entire` appended                               |
| Managed CLI plugins on macOS and Linux                   | `~/.local/share/entire/plugins` | `ENTIRE_PLUGIN_DIR`, or `XDG_DATA_HOME` with `/entire/plugins` appended |

`XDG_CONFIG_HOME` does not change the Entire config directory. Set `ENTIRE_CONFIG_DIR` when you need a different location.

## Control Update Prompts

Set this variable in scripts, CI, or other environments where the CLI should not prompt for an update:

```bash theme={null}
ENTIRE_NO_AUTO_UPDATE=1
```

## Shell Completion

Entire generates shell completion scripts for Bash, Zsh, Fish, and PowerShell with [`entire completion`](/cli-reference/completion). The steps below cover Bash and Zsh.

<Tabs>
  <Tab title="Bash">
    Add this command to `~/.bashrc`:

    ```bash theme={null}
    source <(entire completion bash)
    ```
  </Tab>

  <Tab title="Zsh">
    Add this command to `~/.zshrc`:

    ```bash theme={null}
    source <(entire completion zsh)
    ```
  </Tab>
</Tabs>

## Uninstall Entire

Use the command that matches your installation method.

<Tabs>
  <Tab title="Homebrew">
    Stable:

    ```bash theme={null}
    brew uninstall --cask entireio/tap/entire
    ```

    Nightly:

    ```bash theme={null}
    brew uninstall --cask entireio/tap/entire@nightly
    ```
  </Tab>

  <Tab title="Linux Install Script or Direct Download">
    ```bash theme={null}
    rm -f "$HOME/.local/bin/entire" "$HOME/.local/bin/git-remote-entire"
    ```
  </Tab>

  <Tab title="Windows PowerShell Script">
    Remove both executables from the directory you installed them in:

    ```powershell theme={null}
    Remove-Item "$HOME\.local\bin\entire.exe", "$HOME\.local\bin\git-remote-entire.exe"
    ```

    The user `PATH` entry for that directory remains. Remove it if you no longer need the directory. If the script used Scoop, follow the Scoop tab instead.
  </Tab>

  <Tab title="Scoop">
    ```powershell theme={null}
    scoop uninstall entire
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    rm -f "$(go env GOPATH)/bin/entire" "$(go env GOPATH)/bin/git-remote-entire"
    ```
  </Tab>
</Tabs>

Uninstalling the executables does not remove repository settings, checkpoints, or user data. Inspect the paths under [Installation and Data Locations](#installation-and-data-locations) before removing data you no longer need.

## Review Recent Changes

Read the [Entire CLI changelog](https://github.com/entireio/cli/blob/main/CHANGELOG.md) for changes in each release.

Continue to the [Quickstart](/quickstart) to capture your first checkpoint.


# Investigate Why Code Exists
Source: https://docs.entire.io/learn/investigate-why-code-exists

Trace code history with entire blame, entire why, and entire investigate.

Use this tutorial when you find surprising code and need to know whether it is intentional, who changed it, and what context should be preserved before you refactor.

In this tutorial, you will use `entire blame`, `entire why`, and `entire investigate` to answer:

> Why does `/leaderboard` open the leaderboard directly instead of going through the game menu?

## Prerequisites

Before you start, make sure you have:

* [Git installed](/installation)
* [Entire installed](/installation)
* Entire 0.7.7 or higher
* At least one [supported AI agent](/agents/overview) configured

## Set Up the Repo

Planetfall is a sample game repo with a rich history of [checkpoints](/guides/sessions/overview#what-is-a-checkpoint). Clone it to get started:

```bash theme={null}
git clone https://github.com/blackgirlbytes/planetfall-seed-signalkit.git
cd planetfall-seed-signalkit
```

## Scenario

You are new to the codebase, and you have been asked to clean up the leaderboard experience. While browsing the app, you notice there are two ways to open the leaderboard: players can click **Leaderboard** from the game menu, but `/leaderboard` also opens the leaderboard directly.

Before changing either path, you need to know whether the direct route is intentional or leftover routing code.

The code below handles the direct `/leaderboard` route:

```text src/main.js:278-281 theme={null}
278  if (isLeaderboardRoute) {
279    document.body.classList.add("leaderboard-route");
280    showTitleLeaderboard();
281  } else if (!requestedView && !params.get("level") && !endShortcut) {
```

## Trace the Attribution

Before deciding whether the direct route is duplicate routing code, start with the code history.

<Frame>
  <div>
    <iframe title="Entire blame demo" />
  </div>
</Frame>

To find out why `/leaderboard` opens the leaderboard directly, run [`entire blame`](/cli-reference/blame) for line `279`, where the app switches into the standalone leaderboard route:

```bash theme={null}
entire blame src/main.js --line 279
```

The output shows that line `279` last changed in a mixed-attribution commit labeled `[MX]`, meaning the commit included both agent-attributed and human-attributed changes:

```text theme={null}
Line  Tag   Agent  Author          Checkpoint    Content
279   [MX]  Codex  blackgirlbytes  bfc2c1df9e4b  document.body.classList.add("leaderboard-route");
```

The direct route points to a checkpointed commit. Next, find out why the change was made.

## Find the Reason

Run [`entire why`](/cli-reference/why) on line `279`:

```bash theme={null}
entire why src/main.js:279
```

The output gives you a brief overview of the line's history, including the checkpoint, session, commit, and original prompt:

```text theme={null}
Line 279 in src/main.js
    document.body.classList.add("leaderboard-route");

[MX] by Codex - gpt-5.5 - checkpoint bfc2c1df9e4b - session 019edf9f - commit 35cdcfb6
Prompt: "we want to be able to go the route /leaderboard and it renders the leaderboard there"

Full context: entire checkpoint explain bfc2c1df9e4b
```

The output also suggests a follow-up command. Run [`entire checkpoint explain`](/cli-reference/checkpoint#checkpoint-explain) with `--generate` to get the checkpoint's intent and outcome:

```bash theme={null}
entire checkpoint explain bfc2c1df9e4b --generate
```

You should see an explanation like this:

```text theme={null}
## Intent

Add a direct browser route /leaderboard that renders the existing leaderboard
experience without requiring navigation through the title menu.

## Outcome

Implemented the /leaderboard route by patching main.js to detect the path and
boot directly into leaderboard mode, adding CSS for standalone overlay behavior,
and adding vercel.json with SPA rewrite rules.
```

## Investigate the Decision

You learned why the route was added, but you still need to understand how the current code supports that decision. Use [`entire investigate`](/cli-reference/investigate) to inspect the route, the menu path, and the leaderboard panel together.

Create a short seed doc with the evidence you found:

```bash theme={null}
cat > leaderboard-route-investigation.md <<'EOF'
# Investigation: direct leaderboard route

Question:
Why does /leaderboard open the leaderboard directly instead of going through the game menu?

Evidence:
- src/main.js opens the leaderboard directly when the path is /leaderboard.
- entire blame ties src/main.js:279 to a mixed-attribution commit with a checkpoint.
- entire why points src/main.js:279 to the direct leaderboard route work.

Please inspect src/main.js, src/titleScreen.js, and src/leaderboardPanel.js.
Explain why the direct /leaderboard route exists, what user or demo workflow it supports,
and what should be preserved if we refactor the leaderboard.
EOF
```

Run the investigation:

```bash theme={null}
entire investigate leaderboard-route-investigation.md --max-turns 1
```

On first run, Entire may ask which agents should participate. Pick the agents configured for your Entire setup.

<Note>
  `entire investigate` is experimental. It appears under labs while the workflow is still being refined.
</Note>

## Read the Findings

Browse saved investigations:

```bash theme={null}
entire investigate --findings
```

Then print a run:

```bash theme={null}
entire investigate show RUN_ID
```

In this example, `entire investigate` found that the direct route was intentional:

```text theme={null}
## Findings

### 1. The Direct Route Is Intentional

src/main.js normalizes the path and sets:

  isLeaderboardRoute = normalizedPath === "/leaderboard"

At boot, the app checks that route before showing the title screen:

  if (isLeaderboardRoute) {
    document.body.classList.add("leaderboard-route");
    showTitleLeaderboard();
  } else if (!requestedView && !params.get("level") && !endShortcut) {
    titleScreen.show();
  }

When the path is /leaderboard, the title screen's show() is never called.
The panel opens directly. The checkpoint intent says the route should render
the existing leaderboard experience without requiring navigation through the
title menu.
```

You started with a surprising line of code, traced who changed it, found the checkpoint context, and used `entire investigate` to confirm what the route supports. Now you know `/leaderboard` is intentional and what behavior to preserve before refactoring it.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Unknown Command &#x22;blame&#x22; or &#x22;why&#x22;">
    [Update Entire](/installation#install-and-update-entire). Make sure you are on Entire 0.7.7 or higher.
  </Accordion>

  <Accordion title="entire blame Does Not Show a Checkpoint">
    Make sure you cloned the sample repo with its checkpoint metadata branch. Run `git branch -r | grep 'entire/checkpoints/v1'` to confirm the remote checkpoint branch is present.
  </Accordion>

  <Accordion title="entire why Says No Checkpoint Is Linked">
    That can be a valid result. Some lines come from commits that were not linked to Entire session context. Use Git history, tests, and `entire investigate` to continue from there.
  </Accordion>

  <Accordion title="entire investigate Asks Me to Configure Agents">
    That is expected on first run. Pick the agents configured for your Entire setup. You can re-open the picker later with `entire investigate --edit`.
  </Accordion>
</AccordionGroup>

## Continue With

<CardGroup>
  <Card title="Search Past Work and Code" icon="magnifying-glass" href="/learn/search-past-agent-work">
    Search checkpoints and sessions by meaning, phrase, or prior context.
  </Card>

  <Card title="checkpoint Command Reference" icon="terminal" href="/cli-reference/checkpoint">
    List, explain, search, and inspect checkpoints from the CLI.
  </Card>
</CardGroup>


# Mirror a GitHub Repository
Source: https://docs.entire.io/learn/mirror-a-github-repository

Bring an existing GitHub repository into Entire without moving your source of truth or changing your team's workflow.

A [mirror](/guides/repositories/mirrors) serves a GitHub repository from an EntireDB cluster while GitHub remains the upstream repository.

Your team can keep pushing to GitHub as usual, while agents and selected users clone and fetch through an `entire://` URL.

This tutorial shows how to create a mirror, use it with Git, and switch your local checkout back to GitHub if you need to.

For a shorter command-line guide, see [Mirrors in CLI](/guides/repositories/mirrors-in-cli).

## Prerequisites

Before you start, make sure you have:

* [Entire installed](/installation)
* Access to clone the GitHub repository you want to mirror
* The [Entire GitHub App authorized](/guides/repositories/github-app-access) for the repository

<Tip>
  If the mirror commands are not available, [update Entire](/installation#install-and-update-entire).
</Tip>

## Log In

Log in with the Entire CLI:

```bash theme={null}
entire login
```

Confirm that your login is active:

```bash theme={null}
entire auth status
```

## Check GitHub Access

Before you create or push through a mirror, confirm that the Entire GitHub App can access the repository.

1. Open [GitHub installed apps](https://github.com/settings/installations).
2. Find **Entire**.
3. If GitHub shows **Permission updates requested**, click **Review request** and approve the update.
4. Click **Configure** for Entire.
5. Choose **All repositories** or select the repository you want to mirror, then click **Save**.

## Create the Mirror

Choose the GitHub repository you want to mirror:

```bash theme={null}
export GH_OWNER="<owner>"
export GH_REPO="<repo>"
```

Check whether the repository already has a mirror or is available to onboard:

```bash theme={null}
entire repo mirror list --name "$GH_OWNER/$GH_REPO"
```

Create a mirror placement:

```bash theme={null}
entire repo mirror create "github.com/$GH_OWNER/$GH_REPO"
```

This registers a mirror placement on Entire. It does not change any local Git checkout.

The repository can be written as `owner/repo`, an HTTPS GitHub URL, or an SSH GitHub URL. When more than one cluster is available, an interactive terminal prompts you to choose one. A non-interactive command defaults to `aws-us-east-2.entire.io`. Entire waits until the initial GitHub clone is available.

To create the mirror in another region, pass the cluster host as the second argument:

```bash theme={null}
entire repo mirror create "github.com/$GH_OWNER/$GH_REPO" aws-eu-central-1.entire.io
```

When the initial clone is ready, the command returns the placement ID and clone URL.

Inspect the repository and its regional placements:

```bash theme={null}
entire repo mirror get "$GH_OWNER/$GH_REPO"
```

## Clone the Mirror

Clone by repository path:

```bash theme={null}
entire repo clone "/gh/$GH_OWNER/$GH_REPO"
```

If the repository has placements in several regions, an interactive terminal prompts you to select one. A non-interactive run requires `--cluster`:

```bash theme={null}
entire repo clone "/gh/$GH_OWNER/$GH_REPO" --cluster aws-us-east-2.entire.io
```

## Use the Mirror in an Existing Checkout

From an existing GitHub checkout, let Entire configure the remote:

```bash theme={null}
cd "$GH_REPO"
entire repo mirror use
```

If the repository has placements in several regions, an interactive terminal prompts you to select one. A non-interactive run requires `--cluster`. The interactive flow then asks whether to repoint `origin` or add the mirror as a separate remote.

When Entire repoints `origin`, it preserves the GitHub URL as `upstream` if that remote name is available. If `upstream` already exists, Entire leaves it unchanged and warns that it did not save the previous URL. Choose another name with `--upstream NAME`.

To keep `origin` unchanged and add the mirror as `entire`, run:

```bash theme={null}
entire repo mirror use --remote entire
git fetch entire
```

These commands only update the local checkout. They do not create or delete a mirror placement.

## Verify the Mirror

Run normal Git commands through the configured remote:

```bash theme={null}
git fetch
git status
```

Confirm that the selected remote uses an `entire://` URL:

```bash theme={null}
git remote -v
```

## Push through the Mirror

Create a test branch, make a small change, then stage and commit it:

```bash theme={null}
git switch -c mirror-push-test
echo "Mirror test" >> mirror-test.txt
git add mirror-test.txt
git commit -m "Test mirror push"
```

Push the commit through the mirror:

```bash theme={null}
git push -u origin mirror-push-test
```

Entire forwards the push through the mirror to the upstream GitHub repository. Your GitHub write access, branch protection rules, and required checks still apply.

## Restore the GitHub Remote

If `entire repo mirror use` preserved the GitHub URL as `upstream`, inspect it before restoring `origin`:

```bash theme={null}
git remote get-url upstream
git remote set-url origin "git@github.com:$GH_OWNER/$GH_REPO.git"
```

This only updates your local checkout.

## Remove the Mirror

When you no longer need the mirror, remove the server-side mirror placement:

```bash theme={null}
entire repo mirror remove "github.com/$GH_OWNER/$GH_REPO"
```

Removing a mirror does not delete or rewrite the GitHub repository. It also does not change any local Git remotes you configured in `.git/config`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Unknown Command &#x22;repo&#x22;">
    Your `entire` binary may be older than the mirror commands. [Update Entire](/installation#install-and-update-entire), then try again.
  </Accordion>

  <Accordion title="403: Write Access to Repository Not Granted">
    If `git push` reaches the Entire mirror but GitHub rejects the forwarded push, check the Entire GitHub App permissions.

    Open [GitHub installed apps](https://github.com/settings/installations), find **Entire**, review any pending permission update, and make sure the app can access the repository you mirrored.

    Then refresh your Entire login:

    ```bash theme={null}
    entire auth logout
    entire auth login
    ```
  </Accordion>

  <Accordion title="Mirror Creation Takes a While">
    The default create command waits for the initial clone to appear on Entire. For large repositories, that can take time.

    If you only need to register the mirror and check back later, use `--no-wait`:

    ```bash theme={null}
    entire repo mirror create "github.com/$GH_OWNER/$GH_REPO" --no-wait
    ```
  </Accordion>

  <Accordion title="Cloning a Mirror with LFS Files Fails During Checkout">
    Mirrors do not currently support Git LFS. If the repository uses LFS, cloning the mirror fails during checkout with a `smudge filter lfs failed` error.

    As a workaround, point Git LFS at GitHub so that large file transfers go through GitHub, while regular Git operations keep using the mirror:

    ```bash theme={null}
    GIT_LFS_SKIP_SMUDGE=1 entire repo clone "/gh/$GH_OWNER/$GH_REPO"
    cd "$GH_REPO"
    git config lfs.url "https://github.com/$GH_OWNER/$GH_REPO.git/info/lfs"
    git lfs pull
    ```

    See [Git LFS](/guides/repositories/mirrors#git-lfs) for more detail.
  </Accordion>

  <Accordion title="Git Cannot Reach the Mirror">
    If Git cannot reach the `entire://` remote, confirm the placement and retry through the Entire CLI:

    ```bash theme={null}
    entire repo mirror get "$GH_OWNER/$GH_REPO"
    entire repo clone "/gh/$GH_OWNER/$GH_REPO"
    ```

    If it keeps failing, see [`git-remote-entire` Diagnostics](/guides/repositories/troubleshooting#git-remote-entire-diagnostics).
  </Accordion>
</AccordionGroup>


# Learn Entire
Source: https://docs.entire.io/learn/overview

Follow complete Entire workflows from setup through verification.

<CardGroup>
  <Card title="Mirror a GitHub Repository" icon="clone" href="/learn/mirror-a-github-repository">
    Create a regional mirror and use it from Git.
  </Card>

  <Card title="Investigate Why Code Exists" icon="search-code" href="/learn/investigate-why-code-exists">
    Trace a surprising line to its commit, checkpoint, and original prompt.
  </Card>

  <Card title="Search Past Work and Code" icon="magnifying-glass" href="/learn/search-past-agent-work">
    Search checkpoints, sessions, commits, and code.
  </Card>

  <Card title="Review and Recap Agent Work" icon="code-review" href="/learn/review-and-recap-agent-work">
    Run a multiagent review and inspect recent activity.
  </Card>

  <Card title="Explore Skills" icon="wand-sparkles" href="/learn/skills-overview">
    Find and install a reusable workflow for your agent.
  </Card>

  <Card title="Use Skills in a Real Repository" icon="graduation-cap" href="/learn/skills">
    Build a small project, create history, and practice Skill prompts.
  </Card>
</CardGroup>


# Run Cross-Agent Reviews on Agent Work
Source: https://docs.entire.io/learn/review-and-recap-agent-work

Use recap to summarize recent agent activity, then run a cross-agent review before merging.

This tutorial shows how to use `entire recap` to understand recent agent activity, then use [`entire review`](/cli-reference/review) to run a cross-agent review before you merge.

In this tutorial, you will create a small app, make a few agent-assisted commits, recap the work, run a review with more than one agent, and use the findings to decide what to fix.

## Prerequisites

Before you start, make sure you have:

* [Entire installed](/installation)
* An AI coding agent installed
* Git configured for the project
* An Entire account
* Node.js installed

Log in to Entire:

```bash theme={null}
entire login
```

## Create a New Project

Create a Vite project:

```bash theme={null}
mkdir flight-control-review-demo
cd flight-control-review-demo
npm create vite@latest . -- --template vanilla-ts
npm install
```

Enable Entire for your agent. This example uses Codex:

```bash theme={null}
entire enable -y --agent codex
```

Replace `codex` with the agent you use.

Install another review agent so the review can compare more than one reviewer:

```bash theme={null}
entire agent add claude-code
```

This tutorial uses Codex and Claude Code as the review agents. You can use the review agents your team has installed.

Create a feature branch:

```bash theme={null}
git switch -c add-flight-control-board
```

## Build Reviewable History

Open the project in your AI coding agent and ask it to build a small app:

```text theme={null}
Build a browser app called Flight Control.

It should show a departure board for a fictional airport using local sample data.

Requirements:
- show flight number, destination, gate, departure time, status, and delay risk
- include at least 8 sample flights
- make the UI feel like an airport operations screen
- keep the data local and deterministic
- keep the code simple enough to review
```

Commit and push the work:

```bash theme={null}
git add .
git commit -m "Build flight control board"
git push -u origin add-flight-control-board
```

If Entire asks whether to link the commit to session context, choose `a`:

```text theme={null}
Link this commit to session context?
  [Y]es / [n]o / [a]lways (remember my choice): a
```

## Add More Agent Work

Ask your agent to add delay-risk logic:

```text theme={null}
Add deterministic delay-risk scoring to Flight Control.

The score should consider departure time, weather severity, gate changes, connection pressure, and current status.

Show a short reason for each score.
```

Commit and push:

```bash theme={null}
git add .
git commit -m "Add delay risk scoring"
git push
```

Ask your agent to add one more feature:

```text theme={null}
Add a "Simulate next 30 minutes" button.

Each click should apply one deterministic airport update, such as a gate change, a boarding status update, a delay increase, or a cancellation.

Keep the update sequence deterministic so the behavior is easy to review.
```

Commit and push:

```bash theme={null}
git add .
git commit -m "Add flight update simulation"
git push
```

## Recap the Work

Run `entire recap` from the project:

```bash theme={null}
entire recap
```

Use `--static` when you want plain terminal output:

```bash theme={null}
entire recap --static
```

The recap should show recent activity for this repository, including sessions, checkpoints, agent activity, and token usage when available.

<Frame>
  <div>
    <iframe title="Entire recap demo" />
  </div>
</Frame>

Try a longer range:

```bash theme={null}
entire recap --week --static
```

## Configure Cross-Agent Review

Create a review profile with Codex and Claude Code as reviewers, and Codex as the judge:

```bash theme={null}
entire review --configure \
  --set-agents codex,claude-code \
  --set-judge codex \
  --set-output local
```

Entire saves the profile and tells you how to start it.

To see configured profiles:

```bash theme={null}
entire review --list
```

To see the reviewers in the selected profile:

```bash theme={null}
entire review --agents
```

## Run the Review

Run the review:

```bash theme={null}
entire review general
```

<Frame>
  <div>
    <iframe title="Entire review demo" />
  </div>
</Frame>

By default, Entire scopes the review against the first available mainline ref, such as `origin/main`. For stacked branches, pass the parent branch with `--base`:

```bash theme={null}
entire review general --base origin/my-parent-branch
```

To add one-off instructions for a single run, use `--prompt`:

```bash theme={null}
entire review general --prompt "Focus on risky state transitions and missing tests."
```

## Read the Verdict

When the review finishes, Entire shows each reviewer's result and then consolidates the reports into a final verdict.

Compare:

* Which issues did multiple agents find?
* Which issues were unique to one reviewer?
* Which findings are blockers before merge?
* Which findings are follow-up work?

If you want to inspect saved findings locally, run:

```bash theme={null}
entire review --findings
```

Fix the issues you agree with, then commit and push:

```bash theme={null}
git add .
git commit -m "Address review feedback"
git push
```

## Recap the Review Loop

Run recap again:

```bash theme={null}
entire recap --static
```

The recap should now include the original build work, the review run, and any follow-up fixes.

This is the core workflow:

1. Build with an agent
2. Commit and push useful chunks of work
3. Use `entire recap` to understand what happened
4. Use `entire review` to review the branch before merging
5. Fix the findings that matter

## Troubleshooting

<AccordionGroup>
  <Accordion title="`entire recap` Looks Empty">
    Make sure you ran agent work in an Entire-enabled repository, linked commits to session context, pushed the branch, and gave hosted analysis a few minutes to catch up.

    You can also check local checkpoint history:

    ```bash theme={null}
    entire checkpoint list
    ```
  </Accordion>

  <Accordion title="`entire review` Asks Me to Configure Review">
    Create a review profile:

    ```bash theme={null}
    entire review --configure --set-agents codex,claude-code --set-judge codex
    ```

    You can also run `entire review --configure` without flags to use the interactive setup.
  </Accordion>

  <Accordion title="One Reviewer Is Missing">
    Confirm the review agent is installed in this repository:

    ```bash theme={null}
    entire agent list
    entire agent add AGENT_NAME
    ```

    Then check the configured reviewers:

    ```bash theme={null}
    entire review --agents
    ```
  </Accordion>

  <Accordion title="The Review Uses the Wrong Base Branch">
    Pass the branch you want to review against:

    ```bash theme={null}
    entire review general --base origin/main
    ```

    For stacked work, use the parent feature branch instead of `origin/main`.
  </Accordion>
</AccordionGroup>

## Continue With

<CardGroup>
  <Card title="review" icon="terminal" href="/cli-reference/review">
    See the command syntax for `entire review`.
  </Card>

  <Card title="Search Past Work and Code" icon="magnifying-glass" href="/learn/search-past-agent-work">
    Find previous checkpoints, sessions, and commits by phrase or meaning.
  </Card>
</CardGroup>


# Search Past Work and Code
Source: https://docs.entire.io/learn/search-past-agent-work

Find the context behind past agent work and exact text in indexed source files.

## Before You Start

Use a test repository that:

* Is [mirrored to Entire](/learn/mirror-a-github-repository)
* Has [checkpoint capture set up for your agent](/guides/checkpoints/capture-checkpoints)
* Can be committed and pushed to its remote

Make sure you are [logged in to Entire](/cli-reference/login).

## Create Searchable Work

Run your agent from the repository. After it completes each prompt, commit and push the change before moving on. If Entire asks whether to link the commit to the session context, choose `yes` or `always`. Each linked commit creates a separate checkpoint.

First, ask:

```text theme={null}
Build a simple mission tracker using the repository's existing language and
framework. Users should be able to add a mission with a name, launch site,
target orbit, and status, then view their missions in a list.
```

Commit and push the change:

```shell theme={null}
git add .
git commit -m "Build mission tracker"
git push
```

Next, ask:

```text theme={null}
Add a mission archive. Users should be able to archive a mission without
deleting it. Move archived missions into a separate section.
```

Commit and push the change:

```shell theme={null}
git add .
git commit -m "Add mission archive"
git push
```

Finally, ask:

```text theme={null}
Add mission readiness status to this project.

Choose score thresholds for Ready, Needs Review, and Hold. Explain why you chose
those thresholds, then implement them in a function named
getMissionReadinessStatus.
```

Commit and push the change:

```shell theme={null}
git add .
git commit -m "Add mission readiness status"
git push
```

Give Entire a couple of minutes to index all three changes.

## Find the Decision

Ask about the reasoning captured in the agent session:

```shell theme={null}
entire search "how did we decide whether a mission is ready to launch?"
```

Search can return the readiness-related checkpoints, sessions, and commits, including the agent's explanation of the thresholds.

## Find the Code

Search for the function in the indexed source:

```shell theme={null}
entire search --code "getMissionReadinessStatus"
```

Code Search returns the files and lines that contain the function name.

## Repeat the Search in entire.io

Run the same searches in the browser. Open **Search** from the sidebar in [entire.io](https://entire.io), enter the readiness question, and review the **Commits** and **Sessions** tabs. Then switch to the **Code** tab and search for `getMissionReadinessStatus`.

See [Search in entire.io](/guides/search/search-in-entire-io) for filters, sorting, and keyboard shortcuts.

## Continue With

<CardGroup>
  <Card title="Search in entire.io" icon="browser" href="/guides/search/search-in-entire-io">
    Search past work and source code in the browser.
  </Card>

  <Card title="Search in the CLI" icon="terminal" href="/guides/search/search-in-cli">
    Learn about queries, filters, and script-friendly output.
  </Card>
</CardGroup>


# Explain, Search, and Hand Off Work with Skills
Source: https://docs.entire.io/learn/skills

Learn how to use Skills to explain code, investigate changes, search history, and hand work off between agents

This tutorial uses four workflows from the [Entire Skills collection](/learn/skills-overview) to explain code, investigate changes, search history, and hand work off between agents.

<Note>
  Skills are most useful once Entire has recorded session context and checkpoints. This tutorial creates that history as you go, so you can try the Skills even if you are starting fresh.
</Note>

By the end, you will:

1. Understand what each Skill does
2. Install the Skills locally
3. Practice the exact prompts and commands to use
4. Build a tiny app so the Skills have real code to work against

## Skills Used in This Tutorial

You will practice `explain`, `what-happened`, `search`, and `session-handoff`. The [Skills overview](/learn/skills-overview#choose-a-skill) lists every shipped Skill with a use case, example request, and source link.

## Prerequisites

Before using these Skills, make sure you have:

1. [Git installed](/installation)
2. A supported AI agent: [Claude Code](/agents/claude-code), [Codex](/agents/codex), [Copilot CLI](/agents/copilot-cli), [Cursor](/agents/cursor), [Factory](/agents/factory-droid), [Gemini CLI](/agents/gemini-cli), [OpenCode](/agents/opencode), or [Pi](/agents/pi)
3. The [Entire CLI installed](/installation)

<Note>
  This tutorial uses [Codex](/agents/codex) for the examples. You can use these Skills with your preferred agent, including [Claude Code](/agents/claude-code), [Gemini CLI](/agents/gemini-cli), [OpenCode](/agents/opencode), [Cursor](/agents/cursor), [Copilot CLI](/agents/copilot-cli), [Factory](/agents/factory-droid), or [Pi](/agents/pi).
</Note>

## Install Skills

Install the complete collection with the [Skills CLI](https://skills.sh/):

```bash theme={null}
npx skills add https://github.com/entireio/skills --all
```

You can also use your agent's package flow:

<AccordionGroup>
  <Accordion title="Codex">
    See the [Codex integration guide](/agents/codex).

    ```bash theme={null}
    mkdir -p ~/.agents/skills
    cd ~/.agents/skills
    git clone https://github.com/entireio/skills.git entire
    ```
  </Accordion>

  <Accordion title="Claude Code">
    See the [Claude Code integration guide](/agents/claude-code).

    ```text theme={null}
    /plugin marketplace add entireio/skills
    /plugin install entire
    ```
  </Accordion>

  <Accordion title="Gemini CLI">
    See the [Gemini CLI integration guide](/agents/gemini-cli).

    ```bash theme={null}
    gemini extensions install https://github.com/entireio/skills
    ```
  </Accordion>
</AccordionGroup>

To install one Skill, see [Install Skills](/learn/skills-overview#install-skills). To add the search and agent help helpers that the CLI installs in the repository, see [Install CLI Managed Helpers](/learn/skills-overview#install-cli-managed-helpers).

## Install Entire

Install Entire by following the main [CLI installation guide](/installation).

## Create a Project

We are going to build a tiny app called `bug-notes`.

This project is enough to:

* generate history
* make changes worth explaining
* create [checkpoints](/guides/sessions/overview#what-is-a-checkpoint) worth searching

Create the project:

```bash theme={null}
mkdir bug-notes
cd bug-notes
npm create vite@latest . -- --template vanilla
npm install
```

Run it:

```bash theme={null}
npm run dev
```

## Enable Entire

From inside `bug-notes`, run [`entire enable`](/cli-reference/enable) for Codex and sign in:

```bash theme={null}
entire enable -y --agent codex
entire login
```

When run in a fresh project folder, `entire enable -y --agent codex` initializes Git, creates the initial commit, creates a GitHub repo, and pushes it so checkpoints can be indexed.

<Tip>
  If you are using a different agent, use the corresponding integration flow instead. See [Codex](/agents/codex), [Claude Code](/agents/claude-code), or [Gemini CLI](/agents/gemini-cli).
</Tip>

At this point, your project is ready to record [session](/glossary#session) context and [checkpoints](/guides/sessions/overview#what-is-a-checkpoint).

## Build the App

Open the repo in your AI agent and give it a focused task.

Suggested prompt:

```text theme={null}
Build a tiny bug tracker in this Vite app.
Requirements:
- Add a form with title and status
- Save bugs in local state
- Show a list of bug notes
- Allow filtering by open and fixed
- Keep the code simple and readable
```

Once the agent finishes, commit the result:

```bash theme={null}
git add .
git commit -m "Build bug notes app"
git push
```

That commit is important because the Skills become much more useful once there is committed and pushed history plus [Entire checkpoint data](/guides/checkpoints/checkpoint-storage).

## Add History

The `search` Skill has more material to examine when several [sessions](/glossary#session) cover distinct concepts. Do these as separate chunks of work, then commit and push after each one.

### Persistence

Suggested prompt:

```text theme={null}
Add localStorage persistence so bug notes survive refresh.
Also add a small empty state when no notes exist.
```

Commit:

```bash theme={null}
git add .
git commit -m "Add persistence and empty state"
git push
```

### Duplicate Detection

Suggested prompt:

```text theme={null}
Add duplicate bug detection.
If a user tries to add a bug note with the same title as an existing one, show an inline validation message and prevent the duplicate.
```

Commit:

```bash theme={null}
git add .
git commit -m "Prevent duplicate bug entries"
git push
```

### Severity Badges

Suggested prompt:

```text theme={null}
Add a severity field with values low, medium, and high.
Show a colored severity badge in the bug list and allow filtering by severity.
```

Commit:

```bash theme={null}
git add .
git commit -m "Add severity badges and filter"
git push
```

Now you have three distinct stories in history:

* persistence
* duplicate detection
* severity filtering

That gives `search` much better material than a single vague feature.

## Practice Skills

### Explain

Ask:

```text theme={null}
/explain src/main.js
```

Or:

```text theme={null}
Explain why the persistence logic exists
```

What you should notice:

* the skill is trying to connect the code to the original session context
* this is different from a normal code explanation, which only describes current behavior

### What Happened

Find a specific code range first:

```bash theme={null}
nl -ba src/main.js | sed -n '1,220p'
```

Then ask:

```text theme={null}
what happened here: src/main.js:40-85
```

What you should notice:

* this is block-focused
* it is about provenance of a specific region
* it is ideal when a few lines look strange or surprising

### Search

Before this exercise, make sure `entire login` already worked in Terminal. `search` uses indexed checkpoint history, so give Entire a moment to index your pushed checkpoints before trying these queries.

Start with a very specific query:

```text theme={null}
search past work for duplicate validation
```

If that is too narrow, try:

```text theme={null}
search past work for duplicate bug detection
```

Then try:

```text theme={null}
search past work for severity badges
```

Only after that, try the broader question:

```text theme={null}
have we done this before with persistence?
```

What you should notice:

* it searches [checkpoints](/guides/sessions/overview#what-is-a-checkpoint) and the session context connected to them
* it helps with memory across [sessions](/glossary#session)
* it works best with concrete nouns and feature phrases, not broad words like `persistence` by itself
* the best demo queries are feature names, validation behavior, bug text, file names, or ticket IDs

### Session Handoff

Start with the summary request:

```text theme={null}
hand off this session
```

Or:

```text theme={null}
hand off the codex session
```

What you should notice:

* the skill creates a concise handoff summary so another agent can pick up the next task
* it is especially useful after a long build or debug session

For a more intentional transfer, use a two-step workflow. This example hands work to Claude Code, but you can replace Claude Code with any supported agent.

Step 1: generate the handoff summary in your current agent:

```text theme={null}
Prepare a handoff for Claude Code. The next task is to add edit and delete actions for bug notes. Preserve the current vanilla JS structure and localStorage behavior.
```

Step 2: open the receiving agent and paste the handoff plus an explicit task brief:

```text theme={null}
Continue this project from the handoff below.

Your next task:
- add edit and delete actions for bug notes
- keep the app in plain vanilla JS
- preserve the existing localStorage behavior
- keep the code simple and readable
- make one commit when the feature is complete

Handoff:
[paste the handoff summary here]
```

This is the best tutorial pattern because it shows that:

* `session-handoff` packages the important context
* the user still controls the next objective
* the receiving agent gets both history and clear execution instructions

If you want the receiving agent to stay narrowly scoped, make the brief even more explicit:

```text theme={null}
Continue from this handoff.
Only do the next task: add delete support for bug notes.
Do not add tests or extra refactors.
Make one commit when done.

Handoff:
[paste handoff]
```

## Why Skills Help

In this tutorial, Skill prompting is stronger than normal prompting because it gives the agent a defined workflow instead of a vague question.

<AccordionGroup>
  <Accordion title="Explain Code Intent">
    `/explain src/main.js` is stronger than `Why is this code here?` because it tells the agent to investigate code intent with transcript-aware context.
  </Accordion>

  <Accordion title="Trace a Code Block">
    `what happened here: src/main.js:40-85` is stronger than `Why is this weird?` because it points to a specific block and asks for provenance.
  </Accordion>

  <Accordion title="Search Prior Work">
    `search past work for duplicate bug detection` is stronger than `Have we done this before?` because it gives the search Skill specific feature language to match.
  </Accordion>

  <Accordion title="Hand Work Off">
    `Prepare a handoff for Claude Code...` is stronger than `summarize this` because it names the receiving agent, the next task, and the key constraints.
  </Accordion>
</AccordionGroup>

The general pattern is simple:

* Normal prompting asks the agent to guess the method
* Skill prompting gives the agent both the goal and the method

That usually leads to better structure, better use of Entire history, and less back-and-forth.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Skills Are Installed but Do Not Trigger">
    Make sure:

    * the repo is installed in the right discovery path for your tool
    * the tool supports Skills or plugins
    * you are using prompts that clearly invoke the skill
  </Accordion>

  <Accordion title="`search` or `explain` Returns No Transcript">
    Possible reasons:

    * the code was created outside an Entire-tracked session
    * you have not committed yet, or have not pushed yet for `search`
    * you have not enabled Entire in the repo
    * authentication or checkpoint configuration is incomplete
  </Accordion>

  <Accordion title="`search` Works but Feels Underwhelming">
    That usually means one of these:

    * the query is too broad, like `persistence` or `auth`
    * there are not enough prior sessions yet
    * your earlier sessions did not use distinctive feature language

    To improve results:

    * use more specific queries like `duplicate bug detection` or `severity badge filter`
    * build 2 or 3 distinct features before testing the skill
    * commit and push after each feature so the history is easier to traverse and index
  </Accordion>

  <Accordion title="`session-handoff` Is Not Useful Yet">
    That usually means the project has too little tracked history. Do another meaningful work session, then commit it.
  </Accordion>
</AccordionGroup>


# Skills
Source: https://docs.entire.io/learn/skills-overview

Find, install, and use reusable Entire workflows for coding agents.

[Skills](https://github.com/entireio/skills) give coding agents reusable workflows for the [Entire CLI](/cli-reference). Each Skill tells an agent when to use Entire, which commands to run, and how to interpret the result.

<div>
  <iframe title="Explain Skill Demo" />
</div>

## What Skills Do

Skills turn requests in natural language into repeatable CLI workflows. They can search [checkpoints](/guides/sessions/overview#what-is-a-checkpoint) and transcripts, trace code to its original session, review changes with recorded intent, and package context for another agent.

Skills use the history Entire has already recorded. Start with a repository that contains at least one agent session and checkpoint.

## Choose a Skill

The [Entire Skills repository](https://github.com/entireio/skills/tree/main/skills) ships these Skills:

| Skill                                                                                        | Use It to                                                                           | Example Request                                       |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [`address-findings`](https://github.com/entireio/skills/tree/main/skills/address-findings)   | Fix open review findings on an Entire trail and resolve the findings you addressed. | `Address the findings for this trail: TRAIL_URL`      |
| [`explain`](https://github.com/entireio/skills/tree/main/skills/explain)                     | Find the session that explains why a function, file, or line exists.                | `Explain why parseConfig exists`                      |
| [`recall`](https://github.com/entireio/skills/tree/main/skills/recall)                       | Find similar prior work and turn the closest session into a task playbook.          | `Have we done a migration like this before?`          |
| [`replay`](https://github.com/entireio/skills/tree/main/skills/replay)                       | Walk through a feature's checkpoints in chronological order.                        | `Replay how authentication was built`                 |
| [`review`](https://github.com/entireio/skills/tree/main/skills/review)                       | Read recorded intent, then review the current branch for defects.                   | `Review this branch before merging`                   |
| [`search`](https://github.com/entireio/skills/tree/main/skills/search)                       | Find prior work by topic, repository, branch, author, or time window.               | `Search past work for rate limiting`                  |
| [`session-crosslink`](https://github.com/entireio/skills/tree/main/skills/session-crosslink) | Attach a session to affected repositories when the agent started outside them.      | `Link this session to the repositories it changed`    |
| [`session-handoff`](https://github.com/entireio/skills/tree/main/skills/session-handoff)     | Package active or saved session context for another agent.                          | `Hand off this session`                               |
| [`session-to-skill`](https://github.com/entireio/skills/tree/main/skills/session-to-skill)   | Turn session history or a repeated workflow into a reusable Skill draft.            | `Turn this session into a Skill`                      |
| [`teach`](https://github.com/entireio/skills/tree/main/skills/teach)                         | Build a lesson focused on a topic from canonical checkpoints.                       | `Teach me how this repository handles authentication` |
| [`using-entire`](https://github.com/entireio/skills/tree/main/skills/using-entire)           | Route codebase exploration through the relevant Entire Skill and recorded history.  | `Explore how authentication works in this codebase`   |
| [`what-happened`](https://github.com/entireio/skills/tree/main/skills/what-happened)         | Trace the latest change to a file range or pasted snippet.                          | `What happened at src/auth.ts:42?`                    |

## Install Skills

Use the [Skills CLI](https://skills.sh/) to install the complete collection:

```bash theme={null}
npx skills add https://github.com/entireio/skills --all
```

To install the Skill you found in the table, pass its name:

```bash theme={null}
npx skills add https://github.com/entireio/skills --skill address-findings
```

The installer detects supported agents and their Skill directories. See the [Skills tutorial](/learn/skills#install-skills) for Codex, Claude Code, and Gemini CLI installation commands.

## Install CLI Managed Helpers

The Entire CLI can add two helpers to a repository for Claude Code, Codex, and Gemini CLI:

* `--search-skill` installs a focused helper for `entire search --json`.
* `--agent-help-skill` installs a helper that directs the agent to the command map from the installed Entire CLI.

Install them while enabling Entire:

```bash theme={null}
entire enable --agent codex --search-skill --agent-help-skill
```

You can also add them with an agent integration:

```bash theme={null}
entire agent add codex --search-skill --agent-help-skill
```

These flags install the two helpers for the selected repository and agent. Install the twelve Skills that work across agents through the Skills CLI or your agent's package flow.

## Install a CLI Plugin

Some agent workflows depend on commands that an [Entire CLI plugin](https://github.com/entireio/cli/blob/main/docs/architecture/external-commands.md) supplies. Search the plugin index, inspect a result, and install it by name:

```bash theme={null}
entire plugin search QUERY
entire plugin info NAME
entire plugin install NAME
```

A CLI plugin is an `entire-<name>` executable that adds an `entire NAME` command. It differs from an [`entire-agent-<name>` agent integration](/agents/agent-integration-protocol/overview), which teaches Entire to capture sessions from another coding agent. Install a plugin's agent Skill separately when the workflow also ships a Skill.

## Continue with

<CardGroup>
  <Card title="Use Skills in a Real Repository" icon="graduation-cap" href="/learn/skills">
    Install Skills and practice the core workflows against a small project.
  </Card>

  <Card title="Use Search with Your Coding Agent" icon="robot" href="/guides/search/search-from-your-agent">
    Let an installed Skill search prior checkpoints and sessions.
  </Card>

  <Card title="Checkpoints" icon="flag" href="/guides/sessions/overview#what-is-a-checkpoint">
    Understand the history that Skills read.
  </Card>

  <Card title="Skills Repository" icon="github" href="https://github.com/entireio/skills">
    Read the source and installation metadata for each Skill.
  </Card>
</CardGroup>


# Entire CLI and entire.io
Source: https://docs.entire.io/platforms/cli-and-entire-io

Mirror and clone your repos. Capture, inspect, search, and share the agent-work history recorded by Entire.

Entire has two ways to host your repositories and view your agent history:

* **Entire CLI.** Runs in your terminal and works with the repository on your machine. Use it to enable Entire in a repo, capture agent sessions, list and explain checkpoints, search past work, and create or clone mirrors.
* **[entire.io](https://entire.io).** The web interface for your repositories. Use it to browse, search, and share your agentic history and to connect GitHub repositories to Entire.

The CLI captures the work on your local machine as an agent works. When you commit and push, entire.io can read that captured history and make it easier to review with your team.

## Entire CLI

### What the Entire CLI Does

The Entire CLI captures your agent sessions and links them to your commits, so you and your agents can trace any change back to the work behind it. It also lets you clone and mirror your repositories directly from Entire. The Entire CLI helps you and your agent to:

* Record every agent session as a checkpoint linked to your commits, so the prompts, transcripts, and file changes behind a change are never lost.
* Search your code and the sessions, commits, and checkpoints behind it, from the terminal or from inside your agent.
* Explain why a file or line exists with `entire blame` and `entire why`, which show the checkpoint, prompt, and session that produced it.
* Mirror and clone your repositories natively on Entire, from the region closest to your agents.
* Hand off work between sessions and agents with the session handoff Skill and `entire session resume`, so the next agent starts with the context it needs.
* Review and summarize agent work with `entire review`, a multi-agent review of a branch, and `entire recap`, a summary of recent checkpoint activity.

For the full list of commands and features, see the [CLI Reference](/cli-reference).

### How to Access the CLI

[Install the CLI](/installation), then run commands from inside a Git repository:

```bash theme={null}
entire version
entire status
```

Set up Entire for the coding agent you use:

```bash theme={null}
entire enable --yes --agent codex
```

Replace `codex` with your agent if needed, such as `claude-code` or `gemini`. See [Set Up an Agent](/agents/setup) for the full list.

These are some commands to start with:

```bash theme={null}
# See whether Entire is enabled and which sessions are active
entire status

# List checkpoints on the current branch
entire checkpoint list

# Explain the work behind a checkpoint or commit
entire checkpoint explain CHECKPOINT_ID
entire checkpoint explain HEAD~1

# See all recorded sessions, including ended ones
entire session list

# Search past agent work
entire search "how was authentication changed"
```

Some CLI commands use your hosted Entire account, such as cross-repository search, mirrors, and account activity. Sign in when prompted, or run:

```bash theme={null}
entire login
```

For a remote machine or container where a browser cannot open directly, use:

```bash theme={null}
entire login --device
```

### Host and Mirror Repositories from the CLI

Entire is a distributed Git hosting network. A [mirror](/guides/repositories/mirrors) is a synced copy of your GitHub repository that lives on Entire in a region you choose, so agents can clone and fetch from the cluster closest to them while GitHub stays the source of truth.

From the CLI you can create mirrors, see where a repository is mirrored, and clone or point an existing checkout at one:

```bash theme={null}
# List repositories you can mirror and mirrors that already exist
entire repo mirror list

# Create a mirror; Entire prompts for repositories and regions
entire repo mirror create

# Show each region, clone URL, and status for one repository
entire repo mirror get OWNER/REPO

# Clone from the mirror
entire repo clone /gh/OWNER/REPO

# Add the mirror as a remote in an existing checkout
entire repo mirror use
```

The [Entire GitHub App must have access to the repository](/guides/repositories/github-app-access) before you can create a mirror. If a repository is mirrored in more than one region, `entire repo clone` and `entire repo mirror use` ask you to choose one. Pass `--cluster` in scripts.

Mirrors sync every push back to GitHub. To keep pushing when GitHub is down, or to absorb many agents pushing at once, push to an [Entire-native branch](/guides/repositories/entire-native-branches) by naming it with the `entire/unmirrored/` prefix. See [Mirrors in CLI](/guides/repositories/mirrors-in-cli) for the full command-line flow.

## entire.io

[entire.io](https://entire.io) is the browser-based view of the history the CLI captured. It is useful when you want a visual way to understand work, search across repositories, review your commits and work, or share context with teammates.

### What entire.io Shows

After you sign in, entire.io can show:

* Recent repository activity and commits.
* Checkpoints grouped by repository and branch.
* File diffs and the agent sessions that contributed to a checkpoint.
* Session timelines, prompts, transcripts, tool calls, and files.
* Search results for sessions, commits, checkpoints, and indexed source code.
* The repositories connected to your account, their mirror regions, and their GitHub App access.

<Frame>
  <img alt="entire.io activity overview" />
</Frame>

### How to Access entire.io

1. Install and enable the Entire CLI in the repository.
2. Commit and push your work so the checkpoint data is available to Entire.
3. Sign in at [entire.io](https://entire.io).
4. Open a repository, then choose a branch, checkpoint, session, or search result to inspect.

You do not need a local clone to review a repository in entire.io, but the repository must be connected to your Entire account and its data must be available.

### Host and Mirror Repositories in entire.io

entire.io is where you connect GitHub to Entire and choose which repositories Entire can see. The repository setup flow walks you through it:

1. **Configure GitHub App.** Install the Entire GitHub App, or update its access, for all repositories or only the ones you select. This step needs a GitHub organization admin if the repository belongs to an organization.
2. **Select repositories.** Choose the repositories to make available in Entire.
3. **Choose data residency.** Pick the region where Entire stores and serves each mirror. Entire currently offers regions in the United States, the European Union, India, and Australia.

<Frame>
  <img alt="GitHub repository mirrored across Entire regions in the United States, the European Union, India, and Australia" />
</Frame>

The mirrored repositories then appear in your repository list. Your team can browse their activity in entire.io, and agents can use each mirror as a regional Git remote with the `entire://` clone URL shown for it. Mirror access follows GitHub collaborator permissions and [syncs every hour](/guides/repositories/mirror-access-and-permissions).

See [Mirrors in entire.io](/guides/repositories/mirrors-in-entire-io) for the web flow with screenshots, or [Mirror a GitHub Repository](/learn/mirror-a-github-repository) for the complete walkthrough from access setup through removal.

The two surfaces work together: the CLI captures and manages the history and creates mirrors from the terminal, while entire.io connects your GitHub repositories and makes that history easy to explore and share.

## Continue With

<CardGroup>
  <Card title="Installation" icon="download" href="/installation">
    Install and verify the Entire CLI.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Set up Entire and capture your first agent session.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli-reference">
    Find every Entire CLI command and flag.
  </Card>

  <Card title="Code Hosting" icon="server" href="/guides/repositories/overview">
    Learn how Entire hosts and mirrors repositories across regions.
  </Card>

  <Card title="Inspect Checkpoints in entire.io" icon="browser" href="/guides/checkpoints/inspect-in-entire-io">
    Inspect checkpoint details, sessions, and file diffs visually.
  </Card>

  <Card title="Sessions in entire.io" icon="message" href="/guides/sessions/sessions-in-entire-io">
    Browse the prompt, transcript, and activity behind agent work.
  </Card>

  <Card title="Search in entire.io" icon="magnifying-glass" href="/guides/search/search-in-entire-io">
    Search past work or indexed source code in the browser.
  </Card>

  <Card title="Dispatches in entire.io" icon="newspaper" href="/guides/dispatches/dispatches-in-entire-io">
    Create readable summaries from repository history.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.entire.io/quickstart

Set up Entire, create your first checkpoint, and mirror a GitHub repository.

This quickstart will help you get started with Entire. You will learn how to create a checkpoint that links an agent session to a Git commit and how to mirror a GitHub repository on Entire.

A checkpoint stores the session context behind a change, such as the prompt, agent transcript, tool calls, and changed files. A mirror keeps GitHub as your source of truth while Entire serves the repository from a region you choose.

<div>
  <iframe title="Entire getting started flow" />
</div>

## Before You Start

You need:

* Git installed and configured
* A GitHub account and a repository you can access
* An AI coding agent, such as Claude Code, Codex, Copilot CLI, Cursor, Factory, Gemini CLI, OpenCode, or Pi
* macOS, Linux, or Windows
* Optional: GitHub CLI (`gh`) installed and authenticated, if you want Entire to create and push a private GitHub repository during setup

## 1. Install Entire

Entire ships two release channels:

* `stable`: recommended for most users.
* `nightly`: prerelease builds with newer changes.

Nightly is available through Homebrew, the Linux install script, and the Windows PowerShell installer. Scoop currently supports stable only.

<Tabs>
  <Tab title="macOS (Homebrew)">
    ```bash theme={null}
    # Stable
    brew install --cask entireio/tap/entire

    # Nightly
    brew install --cask entireio/tap/entire@nightly
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # Stable
    curl -fsSL https://entire.io/install.sh | bash

    # Nightly
    curl -fsSL https://entire.io/install.sh | bash -s -- --channel nightly
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    # Stable
    irm https://entire.io/install.ps1 | iex

    # Nightly
    iex "& {$(irm https://entire.io/install.ps1)} -Channel nightly"
    ```

    The script uses Scoop for stable installs when Scoop is available. See [Installation](/installation) for the Scoop commands and the script's options.
  </Tab>

  <Tab title="From Source">
    ```bash theme={null}
    go install github.com/entireio/cli/cmd/entire@latest
    go install github.com/entireio/cli/cmd/git-remote-entire@latest
    ```
  </Tab>
</Tabs>

Check that Entire is installed:

```bash theme={null}
entire version
```

For other installation options, see [Installation](/installation).

## 2. Open a Repository and Enable Entire

Use an existing GitHub repository, or create a new folder for a demo.

<Tabs>
  <Tab title="Existing repository">
    Clone the repository, then enter it:

    ```bash theme={null}
    git clone git@github.com:OWNER/REPOSITORY.git
    cd REPOSITORY
    ```
  </Tab>

  <Tab title="New demo repository">
    Create and enter a folder:

    ```bash theme={null}
    mkdir entire-demo
    cd entire-demo
    ```

    When you enable Entire in the next step, it initializes Git and creates an initial commit. If you have GitHub CLI installed and signed in, it also creates and pushes a private GitHub repository.
  </Tab>
</Tabs>

Choose the agent you use and run its setup command:

<AccordionGroup>
  <Accordion title="Claude Code">
    ```bash theme={null}
    entire enable -y --agent claude-code
    ```
  </Accordion>

  <Accordion title="Codex">
    ```bash theme={null}
    entire enable -y --agent codex
    ```
  </Accordion>

  <Accordion title="Copilot CLI">
    ```bash theme={null}
    entire enable -y --agent copilot-cli
    ```
  </Accordion>

  <Accordion title="Cursor">
    ```bash theme={null}
    entire enable -y --agent cursor
    ```
  </Accordion>

  <Accordion title="Factory">
    ```bash theme={null}
    entire enable -y --agent factoryai-droid
    ```
  </Accordion>

  <Accordion title="Gemini CLI">
    ```bash theme={null}
    entire enable -y --agent gemini
    ```
  </Accordion>

  <Accordion title="OpenCode">
    ```bash theme={null}
    entire enable -y --agent opencode
    ```
  </Accordion>

  <Accordion title="Pi">
    ```bash theme={null}
    entire enable -y --agent pi
    ```
  </Accordion>
</AccordionGroup>

Entire installs hooks that capture your agent's work and link it to Git commits.

<Note>
  `entire enable` creates `.entire/settings.json` and `.entire/.gitignore` so collaborators share project settings. Entire keeps `.entire/settings.local.json` local for personal overrides.
</Note>

## 3. Create Your First Checkpoint

<iframe title="How to Create Your First Checkpoint" />

Start your agent from the repository root and give it a small task:

```text theme={null}
Create a file named hello-entire.md with a short note explaining that this is my first Entire checkpoint.
```

When the agent finishes, commit the change:

```bash theme={null}
git add hello-entire.md
git commit -m "Add first Entire checkpoint"
```

Entire asks whether to link the commit to the agent session:

```text theme={null}
Entire: Active <agent> session detected

Link this commit to session context?
  [Y]es / [n]o / [a]lways (remember my choice):
```

Press `Enter` or type `y`.

You have created a checkpoint. It links the commit to the prompt, transcript, tool calls, and files from the agent session.

View it with:

```bash theme={null}
entire checkpoint list
```

<Note>
  Choose `always` at the commit prompt if you want Entire to link future agent-assisted commits automatically.
</Note>

Checkpoint storage depends on the repository configuration. See [Session Storage](/guides/checkpoints/checkpoint-storage) for storage and push behavior.

## 4. Mirror Your Repository

<iframe title="How to Mirror Your Repository" />

A mirror lets agents clone and pull through Entire while GitHub remains the upstream repository.

Before you begin, make sure the [Entire GitHub App](/guides/repositories/github-app-access) can access the repository. An organization admin may need to approve the app.

Create a mirror:

```bash theme={null}
entire repo mirror create
```

Choose your repository and the region where you want Entire to host it. Choose a region close to your agents or one that meets your organization's data-residency requirements.

Then configure this checkout to use the mirror:

```bash theme={null}
entire repo mirror use
```

For this quickstart, choose to replace `origin`. Entire saves the GitHub remote as `upstream` when that name is available.

Check the result:

```bash theme={null}
git remote -v
```

`origin` should now use an `entire://` URL. Continue using Git normally:

```bash theme={null}
git fetch
git push
```

Entire sends pushes through the mirror to GitHub. Your existing GitHub access, branch protection, and review rules still apply.

<Note>
  To keep `origin` pointed at GitHub, add Entire as a separate remote instead:

  ```bash theme={null}
  entire repo mirror use --remote entire
  ```
</Note>

## Continue With

<CardGroup>
  <Card title="Inspect Checkpoints" icon="flag" href="/guides/checkpoints/inspect-checkpoints">
    Review the session and decisions behind a commit.
  </Card>

  <Card title="Search Past Work" icon="magnifying-glass" href="/guides/search/overview">
    Search code, commits, and agent sessions together.
  </Card>

  <Card title="Mirrors in the CLI" icon="terminal" href="/guides/repositories/mirrors-in-cli">
    Learn more about mirror regions and Git remotes.
  </Card>

  <Card title="Set Up an Agent" icon="robot" href="/agents/setup">
    Configure another supported coding agent.
  </Card>
</CardGroup>


# Security & Privacy
Source: https://docs.entire.io/security

Where your data lives, which redaction layers run before each write, when data leaves your machine, and how to report security issues

Entire writes AI session transcripts and checkpoint metadata into your own Git repository, and redacts them before each write. This page covers the trust boundaries, every location Entire writes to or transmits, and which redaction layers cover each one.

<Note>
  We verified the behavior on this page against **Entire CLI 0.10.2**, except for secret scanner selection, which first appears in `v0.10.3-nightly.202608210613.680d64782`. Run `entire version` to check what you have installed. To configure any of it, see [Privacy and Redaction](/guides/configuration/privacy-and-redaction) and [Session Storage](/guides/checkpoints/checkpoint-storage); this page describes behavior, those pages hold the settings keys.
</Note>

## Where Your Data Lives

Checkpoints live in **your** Git repository, not in a service Entire controls. Which Git objects hold them depends on the storage backend.

| Location                               | Holds                                                                                                                                               | Scope                             |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `refs/entire/checkpoints/<shard>/<id>` | One ref per checkpoint, carrying that checkpoint's redacted metadata and transcripts. The default for repositories enabled with CLI 0.10.0 or later | Local until you push              |
| `entire/checkpoints/v1`                | A single branch carrying every checkpoint, used by repositories enabled before CLI 0.10.0 and by anyone who passes `--checkpoint-backend branch`    | Local until you push              |
| `entire/<commit>-<worktree>`           | Shadow branches: working storage during a live session, including **raw, unredacted snapshots of your working tree**                                | Local. Entire does not push these |
| `.entire/`                             | Settings, redaction rule packs, diagnostic logs, and local runtime state                                                                            | Local. Most of it is gitignored   |
| Your own commits                       | An `Entire-Checkpoint` trailer naming the checkpoint ID                                                                                             | Public once you push              |

Both backends store checkpoint data in the same repository as your code unless you configure a [separate checkpoint repository](/guides/checkpoints/store-checkpoints-in-another-repo). To see or change which backend a repository uses, read `checkpoints.primary.type` in `.entire/settings.json` or pass `--checkpoint-backend` to [`entire configure`](/cli-reference/configure).

Anyone with access to your repository can read the checkpoints in it. If your repository is public, so are they.

<Warning>
  Treat redaction as a safety net rather than a guarantee. For customer data, internal credentials, or regulated material, use a **private** repository.
</Warning>

## Reporting a Vulnerability

Please **do not** open a public GitHub issue for a security vulnerability.

<Card title="Email security@entire.io" icon="envelope" href="mailto:security@entire.io">
  Report security vulnerabilities directly. We acknowledge within 48 hours and aim to resolve criticals within 90 days. Full disclosure policy below.
</Card>

<AccordionGroup>
  <Accordion title="Threat Model and Boundaries">
    Entire is a local development tool that writes to your repository. The protections here assume an attacker who reads your repository, not one who already controls your machine.

    **What redaction is for.** It reduces the chance that a credential or a piece of personal data that entered an agent conversation gets committed and pushed. It runs on transcript and metadata content before Entire writes it to a Git object.

    **What redaction does not do:**

    * **It does not protect a repository from the people who can read it.** Anyone with read access reads every checkpoint in it.
    * **It does not scan your source code.** Redaction covers what Entire writes, not what you commit. A hardcoded secret in a tracked file reaches the remote through your own commit.
    * **It does not defend against a compromised machine.** An attacker running code as you can read the raw agent transcripts, your Git credentials, and everything under `.entire/` before redaction runs.
    * **It does not catch every secret.** Detection is pattern- and entropy-based. See **Limitations of Redaction** below.

    **Who can read what:**

    | Party                                                | Reads                                                                                                                               | Through                                                                                                                                         |
    | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
    | Anyone with read access to your repository           | Redacted checkpoints, your code, and commit trailers                                                                                | Normal Git access                                                                                                                               |
    | Anyone with read access to the checkpoint repository | Redacted checkpoints only, when you configure a separate [checkpoint remote](/guides/checkpoints/store-checkpoints-in-another-repo) | Normal Git access                                                                                                                               |
    | entire.io                                            | The repositories you authorize, and the checkpoints in them                                                                         | The [Entire GitHub App](/guides/repositories/github-app-access), which reads the same redacted content anyone else with repository access reads |
    | Your summary provider                                | The compacted transcript for one checkpoint, redacted first, and only when you run `entire checkpoint explain --generate`           | An outbound call to the configured provider                                                                                                     |
    | PostHog                                              | Command names, flag names, and a hashed machine ID, unless you opt out                                                              | Anonymous CLI analytics                                                                                                                         |

    Entire does not operate a service that receives your transcripts. Checkpoints travel to the Git remotes you push to.
  </Accordion>

  <Accordion title="Data Storage Details">
    **Checkpoint storage holds metadata, not source code.** A checkpoint carries `prompt.txt`, `full.jsonl`, `transcript.jsonl`, `metadata.json`, `checkpoint.json`, and an optional `assets/` subtree. Metadata records the paths a session touched, in `files_touched`, and not their contents.

    **Shadow branches hold unredacted source.** Shadow branches are the one place Entire writes your source files rather than metadata. Metadata written to a shadow branch goes through the same redaction pipeline as a committed checkpoint, but **code-file snapshots are raw blobs of your working tree**, so a hardcoded secret in a tracked file appears in them verbatim. Gitignored files such as `.env` are filtered out of those snapshots as a partial defense. Entire does not push shadow branches and deletes them after a successful push once the session ends cleanly. Do not push one manually.

    **Two redaction passes for metadata.** Entire redacts metadata on the shadow-branch write and again at condensation time, when the session rolls into checkpoint storage. The metadata that lands in checkpoint storage, local or pushed, has been through redaction.

    **`RedactedBytes` type guarantee.** The redact package returns a typed wrapper, and the checkpoint stores accept only that type. A code path that tried to write unredacted transcript bytes would fail to compile rather than fail at runtime.

    **Commit trailers.** Entire adds one trailer to your own commits:

    ```
    Entire-Checkpoint: 01J9ZQ8F7K3M2N5P6R8T9V0W1X
    ```

    The value is a checkpoint ID, either a 12-character hex string or a 26-character ULID. It carries no prompt content and no file content. A ULID encodes the millisecond Entire created the checkpoint, so the trailer discloses commit timing to anyone who can read the commit message. The trailer stays in your history after you push, and you can delete the line before committing if you do not want the commit linked.

    **Remote URL redaction in logs.** When a fetch or push fails, error messages and `.entire/logs/` entries strip passwords from URLs, for example `https://user:****@github.com`, so credentials stay out of local log files.
  </Accordion>

  <Accordion title="What Redaction Covers">
    Redaction covers the content Entire writes into checkpoint storage. It does not cover everything Entire touches.

    | Content                                                                  | Written to                 | Redaction applied                                                                                                                   | Reaches a remote                                        |
    | ------------------------------------------------------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
    | Prompts and transcripts (`prompt.txt`, `full.jsonl`, `transcript.jsonl`) | Checkpoint storage         | Layers 1 through 8, plus the OpenAI Privacy Filter at push time on the branch backend                                               | Yes, on push                                            |
    | Checkpoint metadata (`metadata.json`, `checkpoint.json`)                 | Checkpoint storage         | Layers 1 through 8. The structural-field skip rules exempt file paths and ID fields, so `files_touched` paths are stored as written | Yes, on push                                            |
    | Externalized image assets (`assets/`)                                    | Checkpoint storage         | **None.** Every layer skips the assets subtree                                                                                      | Yes, on push, when `redaction.externalize_images` is on |
    | Inline base64 images left in a transcript                                | Checkpoint storage         | **None.** The JSONL skip rules exclude objects whose `type` starts with `image` or equals `base64`                                  | Yes, on push                                            |
    | Source-file snapshots                                                    | Shadow branch              | **None.** Raw working-tree blobs, minus gitignored paths                                                                            | No, unless you push the shadow branch yourself          |
    | Raw agent session files, for example `~/.claude/projects/<slug>/*.jsonl` | Your agent's own directory | **None.** Entire reads these files and does not rewrite them, because the agent is writing to them concurrently                     | No                                                      |
    | Diagnostic logs (`.entire/logs/entire.log`)                              | Local, gitignored          | Not redacted, but the CLI logs metadata only (IDs, ref names, counts, and timings) and strips passwords from remote URLs            | No                                                      |
    | `Entire-Checkpoint` trailer                                              | Your own commits           | Not applicable. The value is an ID                                                                                                  | Yes, on push                                            |
  </Accordion>

  <Accordion title="Redaction Layers">
    Nine layers run in this order. Layers 1 through 8 use regexes, entropy scoring, or structural validation during condensation. Layer 9 calls a local model at push time.

    <Note>
      CLI 0.10.2 uses Betterleaks for layer 2. Scanner selection first appears in `v0.10.3-nightly.202608210613.680d64782`.
    </Note>

    | # | Layer                                                                                                                                                                                                                                                                                                                            | Runs                                                 | Replacement                    |
    | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------ |
    | 1 | **Entropy scoring.** Alphanumeric runs of 10 or more characters whose Shannon entropy exceeds 4.5                                                                                                                                                                                                                                | On every write                                       | `REDACTED`                     |
    | 2 | **Secret pattern matching.** Entire runs one or both configured scanner engines: [Betterleaks](https://github.com/betterleaks/betterleaks), which covers several hundred known secret formats, and [goredact](https://github.com/lastpersonlabs/goredact), which validates a smaller set of provider and contextual token shapes | On every write, with at least one scanner enabled    | `REDACTED`                     |
    | 3 | **Provider token prefixes.** Deterministic prefix rules for low-entropy credential formats the first two layers miss in isolation, such as Supabase `sb_secret_` and `sbp_`                                                                                                                                                      | On every write                                       | `REDACTED`                     |
    | 4 | **Credentialed URIs.** URLs embedding a password, such as `postgres://user:pass@host/db` or `redis://:pass@host/0`, redacted as a unit                                                                                                                                                                                           | On every write                                       | `REDACTED`                     |
    | 5 | **Database connection strings.** JDBC URIs, database URLs, Postgres keyword DSNs, and semicolon-delimited connection strings. A string with a real password is redacted whole, because a partial fragment can still expose sensitive material                                                                                    | On every write                                       | `REDACTED`                     |
    | 6 | **User-defined rules.** Your inline rules and rule packs                                                                                                                                                                                                                                                                         | When configured                                      | `REDACTED`                     |
    | 7 | **Bounded credential values.** Assignments whose key names a credential, such as `DB_PASSWORD` or `PGPASSWORD`. Inside JSON, a generic `password` key is redacted when the surrounding object also carries a host-like and a user-like field. The key survives; the value does not                                               | On every write                                       | `REDACTED`                     |
    | 8 | **PII detection.** Email, phone, and US street address                                                                                                                                                                                                                                                                           | When configured                                      | `[REDACTED_EMAIL]` and similar |
    | 9 | **OpenAI Privacy Filter.** A token-classification model that catches names and other personal data regex misses                                                                                                                                                                                                                  | When configured, at push time, on the branch backend | Category tokens                |

    Layers 1, 3, 4, 5, and 7 run on every checkpoint write and have no setting that turns them off. Layer 2 always runs at least one scanner. Layers 6, 8, and 9 run only when you configure them.

    **Secret scanner engines.** Betterleaks runs by default and provides broader format coverage. goredact is off by default and uses validators such as token length or checksum checks to improve precision. You can run either engine or both.

    Entire reads scanner selection only from the committed `.entire/settings.json` file. It ignores scanner keys in `.entire/settings.local.json` and logs a warning because scanner choice changes the checkpoint content shared with everyone who reads the repository history.

    Entire refuses to load settings when both scanners are off. If goredact is the only active scanner and it fails during a scan, Entire stops the checkpoint write. If Betterleaks is also active, Entire completes the write with Betterleaks coverage. See [Secret Scanner Engines](/guides/configuration/privacy-and-redaction#secret-scanner-engines) for configuration.

    **Avoiding over-redaction.** Entire skips fields where a match is more likely to be noise than a secret: fields named `signature`, keys ending in `id` or `ids`, structural path fields (`filepath`, `file_path`, `cwd`, `root`, `directory`, `dir`, and `path`), and objects whose `type` starts with `image` or equals `base64`.

    It also leaves placeholders alone. Entire matches placeholders exactly (`changeme`, `example`, `placeholder`, `your_password`, `your_secret`, and prior `REDACTED` markers) and by shape: shell expansions such as `${DB_PASSWORD}`, bracketed names such as `<password>`, and mask runs of three or more `*`, `x`, `.`, or `-`. A connection string whose password is a placeholder survives intact.

    These skips trade detection coverage for a lower false-positive rate. A secret parked in a `path` field or inside a base64 blob is not redacted.
  </Accordion>

  <Accordion title="User-Defined Redaction">
    User-defined rules add a regex layer for strings the built-in detectors do not know: internal token formats, project codenames, customer names, or any other pattern you would rather keep out of session archives.

    Rules use [Go RE2 syntax](https://pkg.go.dev/regexp/syntax), so lookarounds and backreferences are unavailable. Matches become the bare `REDACTED` token. Labels serve diagnostics only.

    You can supply rules two ways, both configured in [Privacy and Redaction](/guides/configuration/privacy-and-redaction#user-defined-redaction):

    * **Inline rules** under `redaction.custom_redactions`, for a handful of patterns.
    * **Rule packs**, YAML or JSON files under `.entire/redactors/`, for reusable sets. A pack declares `name` matching its filename stem, a `version`, and one or more `rules`, each with an `id` and a `regex`.

    **Self-tests.** A rule may declare `samples` with `{ input, redacted }` expectations. Entire checks them when it loads the pack and logs a warning on a mismatch, which catches typos without disabling the rule. Entire logs an invalid regex and skips that rule rather than crashing the redactor.

    **When rules take effect.** On the next CLI or hook invocation. No reload command exists.

    **Personal rules.** Put packs you do not want to share under `.entire/redactors/local/`, which `entire enable` keeps gitignored, so a codename or a customer reference does not become shared repository configuration.
  </Accordion>

  <Accordion title="PII Redaction (Optional)">
    PII redaction runs as layer 8, in addition to secret detection. It is off by default.

    | Category                        | Default once PII is enabled                   | Replacement          |
    | ------------------------------- | --------------------------------------------- | -------------------- |
    | `email`                         | On                                            | `[REDACTED_EMAIL]`   |
    | `phone`                         | On                                            | `[REDACTED_PHONE]`   |
    | `address` (US street addresses) | Off, because it produces more false positives | `[REDACTED_ADDRESS]` |

    **Email allowlist.** Bot and CI addresses stay readable, because they appear in nearly every transcript and identify no one: `noreply@*`, `actions@*`, `*@users.noreply.github.com`, and `*@noreply.github.com`.

    **Custom patterns.** You can add your own patterns under `custom_patterns`, where the label becomes part of the token. A pattern named `employee_id` produces `[REDACTED_EMPLOYEE_ID]`.

    A custom pattern that reveals an internal ID format is itself sensitive. Put those in `.entire/settings.local.json`, which stays out of Git, rather than in the committed `.entire/settings.json`. See [PII redaction](/guides/configuration/privacy-and-redaction#pii-redaction) for the settings.
  </Accordion>

  <Accordion title="OpenAI Privacy Filter (Optional)">
    The [OpenAI Privacy Filter](https://github.com/openai/privacy-filter) (`opf`) is a 1.5B-parameter token-classification model that finds names, addresses, account numbers, and other personal data the regex layers miss. It runs as layer 9, and it is off by default.

    <Warning>
      **OPF applies to the branch backend.** The pre-push rewrite operates on `entire/checkpoints/v1`. Repositories on the ref-based backend, which is the default for repositories enabled with CLI 0.10.0 or later, push checkpoints without the OPF pass. Check `checkpoints.primary.type` before relying on OPF.
    </Warning>

    **When it runs.** OPF runs at push time, not at commit time. Local commits stay on the eight regex layers, so per-commit latency is unchanged. During `git push`, the pre-push hook re-reads each unpushed checkpoint commit, runs the model over its content, and writes new commits carrying an `Entire-OPF-Applied: true` trailer. The local ref fast-forwards to the rewritten tip, and those commits are what reach the remote. The original commits become unreachable and are swept by `git gc`.

    Two consequences follow. The remote sees only OPF-redacted content once OPF is enabled, and local-only commits carry eight-layer redaction until the moment you push. If you never push, OPF never runs.

    **The pre-push prompt.** When OPF is enabled and your terminal is interactive, the hook asks before running:

    ```
    Run OpenAI Privacy Filter on these checkpoints?
    Adds ~30s but redacts names/PII the regex layers can't catch.
    Ctrl-C to cancel the push.

      > Yes     run OPF this push
        No      skip OPF, push as-is
        Always  run OPF on every push from now on
    ```

    **Yes** runs OPF for this push. **No** skips it, and the eight-layer content reaches the remote. **Always** runs OPF and writes `prompt_default: "always"` to `.entire/settings.local.json` so later pushes stop asking. **Ctrl-C** aborts the push, and no refs reach the remote.

    Without a TTY, which covers CI and scripted pushes, Entire skips the prompt and runs OPF, printing a progress line to stderr so the wait is visible.

    **The `ENTIRE_OPF` override.** `ENTIRE_OPF` beats both the setting and the prompt, for a single push. The decision resolves in this order: `ENTIRE_OPF`, then `prompt_default` in settings, then the prompt, then the non-interactive default of running.

    ```bash theme={null}
    ENTIRE_OPF=no git push
    ```

    `ENTIRE_OPF=no` skips OPF for that push. `ENTIRE_OPF=yes` runs it without asking. Use `no` when CI pushes from a machine with no `opf` installed, or for a one-off push while you fix a broken install.

    **Failures abort the push.** If `opf` is missing from `$PATH`, fails to start, or times out, the rewrite aborts the push with `OPF runtime failed; aborting push`. Nothing reaches the remote. Enabling OPF states that you do not want unredacted content leaving the machine, so falling back to eight-layer redaction silently would break that contract.

    Enabling OPF with no category selected fails the same way. Entire cannot tag commits as OPF-applied without a scan, so the push aborts with a configuration error instead. Enable a category, set `enabled: false`, or pass `ENTIRE_OPF=no`.

    The rewrite also refuses to run when it would rewrite history it does not own. It aborts if local checkpoints have diverged from the remote, if a first push exceeds the bootstrap commit cap, if the batch exceeds the inference byte cap, or if another worktree moves the ref mid-rewrite. See [OpenAI Privacy Filter](/guides/configuration/privacy-and-redaction#openai-privacy-filter) for the caps and their overrides.

    **`command` is local-only, and the file must be untracked.** `command` names the binary Entire executes during `git push`, so whoever controls that string controls what runs on your machine. Entire honors it only when it is genuinely yours:

    1. It has to come from `.entire/settings.local.json`, not the committed `.entire/settings.json`.
    2. That file has to be **untracked**, meaning absent from both the Git index and `HEAD`.

    The second check carries the weight. A filename proves nothing on its own, because `.gitignore` does not apply to an already-tracked path: `git add -f .entire/settings.local.json` commits the file, and a fresh clone materializes it with the committed content. A pull request that pairs a `command` with a payload would then execute on every machine that checks the branch out, and a JSON settings diff does not read as executable to a reviewer.

    The rule covers the whole file. A tracked `.entire/settings.local.json` is ignored entirely, because it arrived with the repository rather than belonging to your clone, and Entire tells you to run `git rm --cached .entire/settings.local.json`. Settings still load from the project file, so a committed local-settings file cannot break the repository.

    Entire logs a rejected `command` to `.entire/logs/entire.log`, and OPF falls back to resolving `opf` on `$PATH`. If that binary is missing, the push fails closed rather than shipping content you believed OPF had scanned. Everything else in the OPF block, including `enabled`, `categories`, `timeout_seconds`, and `prompt_default`, works from the shared project file.

    **Content OPF did not reach.** Several local locations retain content that predates the OPF pass. This matters if your threat model extends past what reaches the remote.

    | Location                             | Redaction level  | Lifetime                                                              |
    | ------------------------------------ | ---------------- | --------------------------------------------------------------------- |
    | Raw agent session files              | None             | Until your agent deletes them                                         |
    | Shadow branches                      | Eight layers     | Deleted after the next successful push, once the session ends cleanly |
    | Unreachable objects from the rewrite | Eight layers     | Until `git gc --prune`, which defaults to two weeks                   |
    | Reflog for the checkpoint ref        | Eight-layer tips | `gc.reflogExpire`, which defaults to 90 days                          |

    To clear the unreachable objects sooner:

    ```bash theme={null}
    git reflog expire --expire-unreachable=now refs/heads/entire/checkpoints/v1 && git gc --prune=now
    ```

    This is I/O-heavy on a large repository, so Entire does not run it for you.
  </Accordion>

  <Accordion title="Externalized Images">
    Agents inline base64 images into their transcripts. Redaction skips those objects, so an image reaches checkpoint storage as-is either way. What `redaction.externalize_images` changes is where the bytes sit.

    With externalization on, Entire lifts each inline image out of the transcript into the checkpoint's `assets/` store and leaves a placeholder in its place:

    ```
    entire-asset:assets/img-4f3a2b1c9d8e7f60.png
    ```

    The placeholder is deliberately low-entropy so the entropy layer does not flag it, and it names the asset path so an agent reading the stored transcript still knows an image was there. `assets/manifest.json` indexes the store. Restore re-injects the images byte-exactly whether or not the flag is on, and Entire refuses to externalize any image whose bytes do not re-encode to the original base64 string.

    **Nothing redacts the assets subtree.** Every regex layer skips it, and the OPF rewrite copies it through verbatim, because byte-redacting an image would corrupt it. An image holding a credential, a customer record, or a screenshot of a dashboard reaches the remote intact, whether it sits inline in the transcript or in `assets/`.

    Externalization is off by default. Turning it on keeps large binary blobs out of the transcript files, which makes transcripts cheaper to read and diff. It does not add or remove any redaction coverage. See [Externalized images](/guides/configuration/privacy-and-redaction#externalized-images) for the setting.
  </Accordion>

  <Accordion title="Limitations of Redaction">
    * **Detection is best-effort.** Short passwords and predictable tokens carry too little entropy and match no known pattern.
    * **Filenames and binary data go unscanned.** A secret in a filename, a binary file, or a deeply nested structure may go undetected.
    * **Skip rules can hide secrets.** The structural-field and image skip rules avoid false positives at the cost of coverage, so a secret in a `path` field or a base64 blob survives.
    * **Assets are not scanned at all.** See **Externalized Images** above.
    * **You own your custom rules.** Entire logs and skips an invalid regex in `custom_redactions`, a rule pack, or `custom_patterns`. It does not check that your rules catch what you meant them to catch.
    * **Source snapshots are not covered.** Custom rules and every other layer apply to transcript, prompt, and checkpoint metadata. Shadow branches still carry raw source.
    * **Review what you push.** Redaction reduces exposure; it does not certify a checkpoint as safe to publish.
  </Accordion>

  <Accordion title="External Services and Data Egress">
    The CLI runs locally. It reaches the network in these cases:

    | When                                                                                                    | Where                                                                                       | What Entire sends                                                                                            | Redacted                                                       |
    | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
    | `git push` on an Entire-enabled repository                                                              | Your Git remote                                                                             | Redacted checkpoints, alongside your code                                                                    | Yes, before the data reached the ref                           |
    | `git push` with a [checkpoint remote](/guides/checkpoints/store-checkpoints-in-another-repo) configured | The separate checkpoint repository                                                          | Redacted checkpoints only                                                                                    | Yes                                                            |
    | `entire checkpoint explain --generate`                                                                  | The provider set by `summary_generation.provider`, typically the agent that ran the session | The compacted transcript for the checkpoint being summarized                                                 | Yes, redaction runs before the transcript reaches the provider |
    | Telemetry, unless you opt out                                                                           | PostHog at `eu.i.posthog.com`                                                               | Command name, agent name, flag names, CLI version, OS and architecture, Git version, and a hashed machine ID | Not applicable. No transcript or code content is sent          |
    | GitHub authentication during setup flows that touch GitHub                                              | GitHub                                                                                      | Delegated to the `gh` CLI. Entire stores no credentials of its own                                           | Not applicable                                                 |
    | `entire plugin install` and `entire plugin search`                                                      | The plugin's forge and the plugin index                                                     | Nothing beyond the request itself                                                                            | Not applicable                                                 |

    Entire pushes checkpoint data only when `strategy_options.push_sessions` is true, which is the default. Set it to `false` to [keep checkpoints local](/guides/checkpoints/keep-checkpoints-local).
  </Accordion>

  <Accordion title="Executables Entire Runs">
    Entire runs third-party binaries in two situations, and both give the binary your user's privileges.

    **CLI plugins.** `entire <name>` runs `entire-<name>` when the built-in commands do not match. The CLI resolves the name against `$PATH`, and at startup it prepends a managed directory to `$PATH`:

    ```
    $ENTIRE_PLUGIN_DIR/bin           # override
    $XDG_DATA_HOME/entire/plugins/bin
    ~/.local/share/entire/plugins/bin
    ```

    `entire plugin install` downloads release binaries into that directory. Two properties bound the download:

    * **The CLI requires HTTPS.** It refuses plaintext HTTP for anything off-machine, because the asset and the `checksums.txt` that authenticates it share an origin, so an attacker who can rewrite one can rewrite the other.
    * **Entire verifies checksums by default.** It fetches the release's `checksums.txt`, selects the asset for your platform from it, and verifies the digest. It refuses a release that publishes no checksums. `--allow-unverified` overrides this and installs bytes that nothing authenticates.

    Neither property tells you the code is trustworthy. A verified download of a malicious plugin is still a malicious plugin, and prepending the managed directory to `$PATH` means an installed plugin also shadows same-named binaries elsewhere on your path. Install plugins you trust, audit what `entire plugin list` reports, and see the [`entire plugin` reference](/cli-reference/plugin#checksum-verification) for the complete verification behavior.

    **Agent integrations.** An `entire-agent-<name>` executable integrates a coding agent that Entire does not ship with. The CLI invokes it during agent sessions, and it can read and write the same files as the CLI. Discovery is off by default behind the `external_agents` setting. See the [Agent Integration Protocol](/agents/agent-integration-protocol/overview).

    **Environment filtering.** Entire does not hand a plugin your whole environment. It passes an allowlist covering OS plumbing, locale, terminal and color variables, CI detection, proxies, and `SSH_AUTH_SOCK`, plus the `ENTIRE_*` variables the CLI sets. Credential-shaped variables such as `AWS_*`, `GITHUB_TOKEN`, and `OPENAI_API_KEY` do not pass through.

    This is defense in depth rather than a sandbox. A plugin runs as you and can read anything under `$HOME`, including the credentials the allowlist withheld.
  </Accordion>

  <Accordion title="Checkpoint Commit Signing">
    Entire signs checkpoint commits with the GPG or SSH key already configured for your regular commits, when three conditions hold:

    1. `commit.gpgsign = true` in your global or system Git config.
    2. A supported signer is available: GPG by default, or SSH with `gpg.format = ssh` and a running `ssh-agent`.
    3. `sign_checkpoint_commits` is `true`, which is the default when the setting is absent.

    **Best-effort behavior.** Signing does not block a commit. If the signer is unavailable, fails, or waits on a hardware token touch you did not give, Entire creates the commit **unsigned** and logs a warning to `.entire/logs/`. This keeps CI runs and automated checkpoint saves from losing data.

    To opt out, see [Checkpoint commit signing](/guides/configuration/privacy-and-redaction#checkpoint-commit-signing). Opting out does not change how your own commits are signed.
  </Accordion>

  <Accordion title="Telemetry and Analytics">
    The CLI sends anonymous usage analytics by default, to PostHog at `eu.i.posthog.com`, under the event name `cli_command_executed`.

    **What's captured per command:**

    * Command name, for example `entire enable` or `entire checkpoint explain`
    * Selected agent name, or `auto`
    * Whether Entire is enabled in the current repository
    * CLI version
    * OS and architecture, for example `darwin/arm64`
    * Installed Git version, when it can be determined
    * Names of flags passed, **not** their values

    **What's not captured:** flag values, prompt text, transcripts, file paths, repository identifiers, GitHub usernames, source code, and IP-derived location. The PostHog client sets `DisableGeoIP: true`.

    **DistinctID** is a hashed machine identifier derived from `machineid.ProtectedID`: stable per machine, not directly mappable to a person.

    **Opt out (any one of):**

    * Pass `--telemetry=false` on commands that accept it.
    * Set `"telemetry": false` in `.entire/settings.json` or `.entire/settings.local.json`.
    * Set the env var `ENTIRE_TELEMETRY_OPTOUT=1`.

    The first run of `entire enable` or `entire configure` asks for telemetry consent interactively; declining there sets the setting to `false`.
  </Accordion>

  <Accordion title="Recommendations">
    * **Use a private repository for sensitive work.** This is the shortest path to containment, and it does not depend on redaction catching anything.
    * **Keep sensitive files out of agent context.** Content that never enters a transcript cannot leak through one.
    * **Read your checkpoints before the first push.** Run [`entire checkpoint explain`](/cli-reference/checkpoint), or inspect the refs directly, the same review you would give any branch about to go public.
    * **Enable PII redaction when your agents see customer data.** It is off by default.
    * **Check whether OPF covers your backend** before you rely on it. See the warning under **OpenAI Privacy Filter (Optional)** above.
  </Accordion>

  <Accordion title="Vulnerability Disclosure (Full Policy)">
    **Reporting.** Email [security@entire.io](mailto:security@entire.io). **Do not** open a public GitHub issue for a security vulnerability.

    **Include in your report:**

    * A clear description of the vulnerability.
    * The impact, meaning what an attacker could achieve.
    * Detailed steps to reproduce.
    * Affected CLI versions if known.
    * A suggested fix if you have one (optional).

    **What to expect:**

    * Acknowledgment of receipt within 48 hours.
    * Progress updates as we investigate.
    * Resolution within 90 days for critical vulnerabilities.

    **Confidentiality.** We keep all reports confidential and will not share your information with third parties without your consent, except where the law requires it.

    **Scope.** The CLI (`entire`), official Entire GitHub repositories, and entire.io services.

    **Out of scope** (report upstream or treat as bug reports):

    * Issues in third-party dependencies.
    * Social engineering attacks.
    * Denial of service that requires local access to trigger.
    * Issues that cannot be exploited without direct access to the user's machine.

    **Bug reports vs security advisories.** We reserve security advisories for confirmed vulnerabilities that a remote or non-local actor can exploit. Because the CLI is primarily a local development tool, we track regular-expression performance issues (ReDoS) on local execution, resource exhaustion that requires local access, and issues that cannot be exploited without direct machine access as **bug reports**. File those at [github.com/entireio/cli/issues](https://github.com/entireio/cli/issues).
  </Accordion>
</AccordionGroup>