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

# 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 for the current 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>