DOCSEARCHbyAlgolia
Submit Docs

Entire CLI

repository·main·Indexed 26 days ago

https://github.com/entireio/cli

A tool that integrates with Git workflows to capture and index AI agent sessions, creating searchable, versioned records of prompts, responses, and file changes. It supports various agents including Claude Code, Gemini CLI, Cursor, and Copilot CLI, allowing users to track session metadata and restore checkpoints without polluting active branch commits.

Tokens
50.7K
Snippets
85
Records
284
Agent score
90%

What's inside entireio-cli

  1. Overview of Entire CLI Hooks for Claude Code

    main

    Entire integrates with Claude Code by installing six hooks into .claude/settings.json. These hooks allow Entire to track AI-assisted development sessions by triggering at specific lifecycle events.

    | Hook | Trigger | Purpose |
| :--- | :--- | :--- |
| `SessionStart` | New chat session begins | Generate and persist Entire session ID |
| `UserPromptSubmit` | User submits a prompt | Capture pre-prompt state, check for conflicts |
| `Stop` | Claude finishes responding | Create checkpoint with code + metadata |
| `PreToolUse[Agent]` | Subagent is about to start | Capture pre-task state for diff computation |
| `PostToolUse[Agent]` | Subagent finishes | Create final checkpoint for subagent work |
| `PostToolUse[TaskCreate\|TaskUpdate]` | Subagent updates its task list | Create incremental checkpoint if files changed |

  2. Understand the Session and Checkpoint domain model

    main

    The Entire CLI uses a domain model to manage AI coding sessions and their associated points-in-time (checkpoints). This system is agent-agnostic and works with tools like Claude Code, Cursor, and Copilot CLI.

    Session

    A Session represents a single unit of work. It contains:

    • ID: A unique identifier (e.g., 2025-12-01-8f76b0e8-b8f1-4a87-9186-848bdd83d62e).
    • Description: A human-readable summary.
    • Strategy: The strategy that created the session.
    • StartTime: When the session began.
    • Checkpoints: A list of checkpoints within this session.

    Checkpoint

    A Checkpoint captures a specific point-in-time within a session. It contains:

    • CheckpointID: A stable identifier (12-hex or ULID).
    • Message: A description or commit message.
    • Timestamp: When the checkpoint was created.
    • IsTaskCheckpoint: Boolean indicating if it is a subagent task checkpoint vs. a session checkpoint.
    • ToolUseID: The ID for tool use (only populated for task checkpoints).

  3. Understand how Entire stores transcript and checkpoint data

    main

    When using Entire with an AI agent, session transcripts, user prompts, and checkpoint metadata are committed to a dedicated git branch named entire/checkpoints/v1.

    Key Security Considerations:

    • Visibility: Anyone with access to your repository can view the full prompt/response history and session metadata on this branch. If your repository is public, this data is visible to the entire internet.
    • Shadow Branches: Entire creates temporary local branches (e.g., entire/<short-hash>) for working storage. Metadata in these branches is redacted, but code-file snapshots are written as raw, unredacted blobs.
    • Warning: Do not manually push shadow branches, as they contain unredacted source content. They are automatically cleaned up when data is condensed into entire/checkpoints/v1 at commit time.

  4. Understand Entire security and privacy implications

    main

    Session transcripts are stored in your git repository on the entire/checkpoints/v1 branch. If your repository is public, this data is visible to anyone.

    Entire attempts to automatically redact detected secrets (API keys, tokens, credentials) when writing to entire/checkpoints/v1, but this is a best-effort process.

    Warning: Temporary shadow branches used during a session may contain unredacted data and should not be pushed to remote repositories.

  5. Understand Entire Attribution

    main

    Attribution tracks the percentage of code changes in a commit that were written by an AI agent versus the human user. This metric is recorded in the Entire-Attribution trailer of the git commit message.

    Example commit trailer:

    feat: Add user authentication

Entire-Checkpoint: a3b2c4d5e6f7
Entire-Attribution: 73% agent (146/200 lines)

    Attribution is calculated by untangling interleaved work: capturing user edits between agent prompts and comparing the final state against the accumulated agent checkpoints.

  6. Understand the git-refs checkpoint backend

    main

    The git-refs backend is a checkpoint storage system that uses individual Git references instead of a single long-lived branch. Unlike the legacy git-branch backend which stores all checkpoints as subtrees under a single entire/checkpoints/v1 branch, git-refs creates one Git ref per checkpoint.

    Key characteristics:

    • Ref Format: refs/entire/checkpoints/<shard>/<id>
    • Independence: Checkpoints are written, pushed, and fetched independently, reducing contention on a single shared tip.
    • Storage: Each ref points to a commit where the tree root is the checkpoint's contents (metadata.json, 0/, 1/, tasks/…).
    • Compatibility: Both git-branch and git-refs are git-backed and store records in the repository's own object store without touching the working branch's history.

  7. Understand Entire CLI Auth Contexts and Host Resolution

    main

    The Entire CLI uses a unified identity model based on auth contexts. An auth context is a login to a specific core (the identity provider/login server).

    When the CLI makes an upstream call, it resolves the target host to an authentication method:

    1. Core Host: If the host is a core (e.g., the control plane), the CLI uses the active context's core directly.
    2. Resource Server: If the host is a resource server (e.g., Git cluster or Web/Data API), the host advertises which cores it trusts via a /.well-known endpoint. The CLI then selects the context whose core is trusted and exchanges that context's token for the resource.

    Key Concepts:

    • Auth Context: Stored in $ENTIRE_CONFIG_DIR/contexts.json. Each entry contains {Name, CoreURL, Handle, KeychainService}.
    • CoreURL: The JWT iss (issuer) — the specific core that minted the token.
    • CurrentContext: A pointer in contexts.json indicating the active login.
    • Switching Contexts: Use entire auth use <ctx> to change the active context.

  8. Understand the Entire Checkpoint System and State Machine

    main

    The Entire CLI uses a one-to-one checkpoint system to track changes made during AI sessions. It relies on Shadow branches (prefixed with entire/) for temporary storage, a FilesTouched list to track modified files, and unique checkpoint IDs for every commit.

    Session States

    • IDLE: The default state between prompts.
    • ACTIVE: The state during a prompt turn (from UserPromptSubmit to Stop hook).
    • ENDED: The state after a session is stopped, allowing for session resumption.

    Core Mechanisms

    • Shadow branches (entire/<commit-hash>-<worktree-hash>): Temporary storage for checkpoint data.
    • FilesTouched: An accumulator that tracks files modified during a session. This list is not cleared at the start of a new prompt; it accumulates changes across multiple prompts until a commit occurs.
    • Content-aware overlap: Prevents incorrect checkpoint linking by ensuring staged files overlap with the FilesTouched list.

  9. Understand Checkpoint Signing Best-Effort Behavior

    main

    Checkpoint signing follows a best-effort policy. The SignCommitBestEffort process will never block a commit from being created.

    If signing fails due to a signer being unavailable, an encoding error, or a signing error, the commit will proceed unsigned and a warning will be logged to .entire/logs/. This prevents automation from blocking due to:

    • Hardware tokens requiring physical touch.
    • Temporary ssh-agent unavailability.
    • CI environments lacking signing keys.

  10. Enable remote discovery for checkpoint listing

    main

    By default, List operations only show local checkpoints. To discover checkpoints written on other machines/remotes, you must enable remote discovery.

    In the CLI, this is typically handled by the entire checkpoint list command. Programmatically, this is achieved by marking the context with WithRemoteListDiscovery.

    When enabled, the system runs git ls-remote refs/entire/checkpoints/* to find remote refs. These are returned as non-hydrated CheckpointInfo objects (containing only the ID and a timestamp derived from the ULID) and are lazily hydrated upon the next read.

  11. Configure Entire CLI log levels

    main

    You can control the verbosity of the structured JSON logs written to .entire/logs/entire.log. The environment variable ENTIRE_LOG_LEVEL takes precedence over the configuration in .entire/settings.json.

    Log Levels:

    • DEBUG: Wrapper breadcrumbs (hook invoked/completed) and detailed diagnostics.
    • INFO: Handler logs with full context (primary level for tracing).
    • WARN: Unexpected conditions that do not block execution.
    • ERROR: Failures that prevent operation completion.
    # Using an environment variable (highest precedence)
export ENTIRE_LOG_LEVEL=debug

# Or in .entire/settings.json
{"log_level": "debug"}

  12. Handle partial staging with `git add -p`

    main

    The Entire CLI supports partial staging using git add -p. The system uses content-aware carry-forward by comparing git blob hashes rather than just filenames.

    If you stage only part of a file, the system detects that the committed hash does not match the shadow branch hash. It will then mark the file as having uncommitted changes and carry the full version (the current worktree state) forward to the next checkpoint. This ensures that even when splitting a single file's changes across multiple commits, each commit receives proper attribution.