### Clone and Setup EntireIO CLI

Source: https://github.com/entireio/cli/blob/main/README.md

Clone the repository, navigate to the directory, install dependencies with mise, trust the configuration, and build the CLI.

```bash
# Clone the repository
git clone <repo-url>
cd cli

# Install dependencies (including Go)
mise install

# Trust the mise configuration (required on first setup)
mise trust

# Build the CLI
mise run build
```

--------------------------------

### Install Entire CLI via Go

Source: https://github.com/entireio/cli/blob/main/README.md

Installs the latest stable version of the Entire CLI using Go. This method is intended for development or manual setup and requires Go to be installed.

```bash
# Or install via Go (development/manual setup)
go install github.com/entireio/cli/cmd/entire@latest
```

--------------------------------

### Clone and Install Entire CLI

Source: https://github.com/entireio/cli/blob/main/CONTRIBUTING.md

Steps to clone the repository, set up the development environment using mise, and install dependencies.

```bash
git clone https://github.com/entireio/cli.git
cd cli

mise trust

mise install

go mod download

mise run build

mise run test
```

--------------------------------

### Install Entire CLI via Homebrew (Stable)

Source: https://github.com/entireio/cli/blob/main/README.md

Installs the stable version of the Entire CLI using Homebrew. Ensure you have Homebrew installed and the entireio/tap repository added.

```bash
# Install stable via Homebrew
brew tap entireio/tap
brew install --cask entire
```

--------------------------------

### Set Up EntireIO CLI Development Environment

Source: https://github.com/entireio/cli/blob/main/docs/first-time-contributors.md

Install `mise` if you don't have it, trust the repository's configuration, and install the required Go version. Then, build the CLI and run tests.

```bash
# Install mise (skip if you already have it)
curl https://mise.run | sh

# Trust this repo's mise config and install Go 1.26
mise trust
mise install

# Build the CLI and run the tests
mise run build
mise run test
```

--------------------------------

### Install Entire CLI via Scoop (Windows)

Source: https://github.com/entireio/cli/blob/main/README.md

Installs the stable version of the Entire CLI on Windows using the Scoop package manager. Ensure Scoop is installed and the entireio/scoop-bucket repository is added.

```bash
# Or install stable via Scoop (Windows)
scoop bucket add entire https://github.com/entireio/scoop-bucket.git
scoop install entire/cli
```

--------------------------------

### Cursor Agent Hook Configuration Example

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/cursor/AGENT.md

Example of a project-local `.cursor/hooks.json` file registering a command for the `sessionStart` hook.

```json
{
  "sessionStart": [
    {"command": "echo 'Session started!'"}
  ]
}
```

--------------------------------

### Enable Entire CLI with a Specific Agent

Source: https://github.com/entireio/cli/blob/main/README.md

Use this command for first-time setup to install hooks for a particular AI agent.

```bash
entire enable --agent claude-code
```

--------------------------------

### Install Entire CLI via install.sh (Nightly)

Source: https://github.com/entireio/cli/blob/main/README.md

Installs the nightly version of the Entire CLI using a shell script. Use the --channel nightly flag to specify the prerelease channel.

```bash
# Or install nightly via install.sh
curl -fsSL https://entire.io/install.sh | bash -s -- --channel nightly
```

--------------------------------

### Start and Execute in Dev Container

Source: https://github.com/entireio/cli/blob/main/README.md

Commands to start the dev container and execute a script within it, ensuring the keyring is handled.

```bash
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash -lc '.devcontainer/run-with-keyring.sh'
```

--------------------------------

### Install mise

Source: https://github.com/entireio/cli/blob/main/README.md

Install the mise tool using the provided curl command.

```bash
curl https://mise.run | sh
```

--------------------------------

### install-hooks [--local-dev] [--force]

Source: https://github.com/entireio/cli/blob/main/docs/architecture/external-agent-protocol.md

Installs agent hooks for Entire integration. Outputs JSON indicating the number of hooks installed.

```APIDOC
## install-hooks [--local-dev] [--force]

### Description
Installs agent hooks for Entire integration.

### Arguments
- `--local-dev` (boolean) - Optional - Use local development binary path.
- `--force` (boolean) - Optional - Overwrite existing hooks.

### Output (stdout)
JSON

```json
{"hooks_installed": 3}
```
```

--------------------------------

### Install Entire CLI via install.sh (Stable)

Source: https://github.com/entireio/cli/blob/main/README.md

Installs the stable version of the Entire CLI using a shell script. This method is suitable for systems where Homebrew is not available.

```bash
# Or install stable via install.sh
curl -fsSL https://entire.io/install.sh | bash
```

--------------------------------

### Install Mise

Source: https://github.com/entireio/cli/blob/main/CONTRIBUTING.md

Ensure `mise` is properly installed by running this command. After installation, reload your shell configuration.

```bash
curl https://mise.run | sh
source ~/.zshrc  # or ~/.bashrc
```

--------------------------------

### Install Entire CLI via Homebrew (Nightly)

Source: https://github.com/entireio/cli/blob/main/README.md

Installs the nightly (prerelease) version of the Entire CLI using Homebrew. This channel provides the latest changes but may be less stable.

```bash
# Or install nightly via Homebrew
brew tap entireio/tap
brew install --cask entire@nightly
```

--------------------------------

### Install Cursor Agent CLI

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/cursor/AGENT.md

Use this command to install the Cursor agent. It can also be installed via the Cursor IDE.

```bash
curl -fsSL https://cursor.com/install-agent | bash
```

--------------------------------

### Example Calculation Breakdown

Source: https://github.com/entireio/cli/blob/main/docs/architecture/attribution.md

Demonstrates a detailed calculation scenario, highlighting the benefit of per-file tracking for accurate attribution.

```text
base → shadow: 15 lines added (10 agent + 5 user in snapshot)
accumulatedUserAdded: 5 (from PromptAttribution)
totalAgentAdded: 15 - 5 = 10

shadow → head: +3 added, -3 removed (user's modification)
postCheckpointUserAdded: 3
postCheckpointUserRemoved: 3

totalUserAdded: 5 + 3 = 8
totalUserRemoved: 3
totalHumanModified: min(8, 3) = 3

// Per-file tracking kicks in:
userSelfModified: min(3 removed from main.go, 5 user added to main.go) = 3
humanModifiedAgent: 3 - 3 = 0  // No agent lines were modified!

agentLinesInCommit: 10 - 0 = 10  // Agent attribution preserved
totalCommitted: 10 + 5 = 15
agentPercentage: 10/15 = 66.7%
```

--------------------------------

### Install OpenAI Privacy Filter (OPF)

Source: https://github.com/entireio/cli/blob/main/docs/security-and-privacy.md

Install the OPF package using pip. Ensure the CLI can resolve the binary via your system's PATH.

```bash
pip install opf
```

--------------------------------

### Install Hooks Confirmation

Source: https://github.com/entireio/cli/blob/main/docs/architecture/external-agent-protocol.md

This JSON output indicates the number of hooks successfully installed by the `install-hooks` command.

```json
{"hooks_installed": 3}
```

--------------------------------

### Start Interactive Mode

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/copilotcli/AGENT.md

Initiate a standard interactive Copilot CLI session.

```bash
copilot
```

--------------------------------

### Example Flow: Commit and Condensation

Source: https://github.com/entireio/cli/blob/main/docs/architecture/sessions-and-checkpoints.md

Illustrates the end-to-end flow from a user creating a commit with a checkpoint trailer to the subsequent condensation process creating a checkpoint commit.

```git
Example Flow:

                    User creates commit
                           ↓
           prepare-commit-msg hook adds trailer
                           ↓
┌──────────────────────────────────────────────────┐
│ Commit on main branch:                           │
│   "Implement login feature                       │
│                                                   │
│   Entire-Checkpoint: a3b2c4d5e6f7"               │
└──────────────────────────────────────────────────┘
                           ↓
                  post-commit hook runs
                           ↓
          Condense shadow → entire/checkpoints/v1
                           ↓
┌──────────────────────────────────────────────────┐
│ Commit on entire/checkpoints/v1:                 │
│   Subject: "Checkpoint: a3b2c4d5e6f7"            │
│                                                   │
│   Tree: a3/b2c4d5e6f7/                           │
│     ├── metadata.json                            │
│     │   (checkpoint_id: "a3b2c4d5e6f7")          │
│     ├── 0/                                       │
│     │   ├── full.jsonl                           │
│     │   └── prompt.txt                           │
│     └── ...                                      │
│                                                   │
│   Trailers:                                      │
│     Entire-Session: 2026-01-20-uuid              │
│     Entire-Strategy: manual-commit               │
└──────────────────────────────────────────────────┘
```

--------------------------------

### JSONL Transcript Entry Examples

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/copilotcli/AGENT.md

Examples of different event types within a Copilot CLI transcript, formatted as JSONL.

```jsonl
{"type":"session.start","data":{"sessionId":"4de47255-...",
```

```jsonl
{"type":"user.message","data":{"content":"exit","transformedContent":"...","attachments":[],"interactionId":"6cd0..."},"id":"20fa...","timestamp":"...","parentId":"00ac..."}
```

```jsonl
{"type":"assistant.turn_start","data":{"turnId":"0","interactionId":"6cd0..."},"id":"3b61...","timestamp":"...","parentId":"20fa..."}
```

```jsonl
{"type":"assistant.message","data":{"messageId":"a078...","content":"To exit...","toolRequests":[],"interactionId":"6cd0...","reasoningText":"..."},"id":"c892...","timestamp":"...","parentId":"aaeb..."}
```

```jsonl
{"type":"assistant.turn_end","data":{"turnId":"0"},"id":"0ae4...","timestamp":"...","parentId":"4989..."}
```

--------------------------------

### Post Tool Use Payload Example

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/cursor/AGENT.md

An example of the payload structure after a tool use operation, including details like tool name, input, output, duration, and tool use ID.

```json
{
  "tool_name": "Write",
  "tool_input": {"file_path": "/path", "content": "..."},
  "tool_output": "{\"success\":true}",
  "duration": 36.841,
  "tool_use_id": "call_xxx\nctc_xxx"
}
```

--------------------------------

### Hook Log Example

Source: https://github.com/entireio/cli/blob/main/docs/architecture/logging.md

Illustrates the structure of a log entry generated by a hook.

```json
{
  "time": "2025-12-31T12:27:52.853381+11:00",
  "level": "INFO",
  "msg": "post-task",
  "session_id": "2025-12-31-abc123",
  "component": "hooks",
  "hook": "post-task",
  "hook_type": "subagent",
  "tool_use_id": "toolu_abc123",
  "agent_id": "agent_xyz",
  "subagent_type": "general-purpose"
}
```

--------------------------------

### PreToolUse Hook Input Example

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/codex/AGENT.md

Provides an example of the JSON input for the `PreToolUse` hook, specific to shell/Bash execution. It includes details about the tool being used, its input, and the tool use ID.

```json
{
  "session_id": "...",
  "turn_id": "turn-uuid",
  "transcript_path": "...",
  "cwd": "...",
  "hook_event_name": "PreToolUse",
  "model": "gpt-4.1",
  "permission_mode": "default",
  "tool_name": "Bash",
  "tool_input": {"command": "ls -la"},
  "tool_use_id": "tool-call-uuid"
}
```

--------------------------------

### Checkpoint Log Example

Source: https://github.com/entireio/cli/blob/main/docs/architecture/logging.md

Shows the format of a log entry for a saved checkpoint.

```json
{
  "time": "2025-12-31T12:28:00.123456+11:00",
  "level": "INFO",
  "msg": "checkpoint saved",
  "session_id": "2025-12-31-abc123",
  "component": "checkpoint",
  "strategy": "manual-commit",
  "checkpoint_type": "session",
  "checkpoint_count": 3,
  "modified_files": 2,
  "new_files": 1,
  "deleted_files": 0,
  "shadow_branch": "entire/a1b2c3d",
  "branch_created": false
}
```

--------------------------------

### Enable Entire in Repository

Source: https://github.com/entireio/cli/blob/main/README.md

Runs the initial enable flow for a repository, creating settings and installing git hooks. Use `--agent <name>` to enable a specific agent non-interactively.

```bash
entire enable
```

--------------------------------

### Task Checkpoint Log Example

Source: https://github.com/entireio/cli/blob/main/docs/architecture/logging.md

Details the structure of a log entry for a saved task checkpoint.

```json
{
  "time": "2025-12-31T12:28:30.789012+11:00",
  "level": "INFO",
  "msg": "task checkpoint saved",
  "session_id": "2025-12-31-abc123",
  "component": "checkpoint",
  "strategy": "manual-commit",
  "checkpoint_type": "task",
  "tool_use_id": "toolu_xyz789",
  "subagent_type": "general-purpose",
  "modified_files": 5,
  "new_files": 2,
  "deleted_files": 0,
  "shadow_branch": "entire/a1b2c3d",
  "branch_created": false
}
```

--------------------------------

### General and Command-Specific Help

Source: https://github.com/entireio/cli/blob/main/README.md

Use the `--help` flag to get general help or specific help for any command. This is useful for understanding available options and subcommands.

```bash
entire --help              # General help
```

```bash
entire <command> --help    # Command-specific help
```

--------------------------------

### Commit Changes

Source: https://github.com/entireio/cli/blob/main/CONTRIBUTING.md

Example of how to commit changes with a descriptive message.

```bash
git commit -m "Add feature: description of what you added"
```

--------------------------------

### Interactive OPF Prompt Options

Source: https://github.com/entireio/cli/blob/main/docs/security-and-privacy.md

Example of the interactive prompt shown before a Git push when OPF is enabled. Offers options to run, skip, or always run OPF, with Ctrl-C to cancel the push.

```text
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
```

--------------------------------

### Test Hook Installation Creates Settings File

Source: https://github.com/entireio/cli/blob/main/docs/architecture/agent-guide.md

Verifies that the InstallHooks function correctly creates a settings file within the agent's configuration directory. It checks that hooks are installed and that the settings file is populated.

```go
func TestInstallHooks_CreatesSettingsFile(t *testing.T) {
    t.Parallel()

    dir := t.TempDir()
    // ... set up test repo, create .youragent/ directory ...

    ag := &YourAgent{}
    count, err := ag.InstallHooks(false, false)

    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
    if count == 0 {
        t.Error("expected hooks to be installed")
    }

    // Verify settings file was created and contains hooks
    data, err := os.ReadFile(filepath.Join(dir, ".youragent", "settings.json"))
    // ... assert hooks are present ...
}
```

--------------------------------

### Log Metadata Safely

Source: https://github.com/entireio/cli/blob/main/docs/architecture/logging.md

Example of logging metadata safely using `slog.String` to avoid including sensitive user data. This is the recommended practice.

```go
// GOOD - logs metadata only
logging.Info(ctx, "post-task",
    slog.String("hook", "post-task"),
    slog.String("tool_use_id", input.ToolUseID),
    slog.String("subagent_type", subagentType),  // e.g., "general-purpose"
)
```

--------------------------------

### Transcript Example Entries

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/cursor/AGENT.md

Illustrates the format of entries within the agent's transcript file, showing user queries and assistant responses.

```jsonl
{"role":"user","message":{"content":[{"type":"text","text":"<user_query>\ncreate a file\n</user_query>"}]}}
{"role":"assistant","message":{"content":[{"type":"text","text":"Created the file."}]}}
```

--------------------------------

### SessionStart Hook Input Example

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/codex/AGENT.md

Illustrates the JSON payload received by the Codex agent when the `SessionStart` hook is triggered. This includes session details, transcript path, working directory, and the source of the session.

```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "transcript_path": "/Users/user/.codex/rollouts/01/01/rollout-20260324-550e8400.jsonl",
  "cwd": "/path/to/repo",
  "hook_event_name": "SessionStart",
  "model": "gpt-4.1",
  "permission_mode": "default",
  "source": "startup"
}
```

--------------------------------

### Example Attribution Trailer

Source: https://github.com/entireio/cli/blob/main/docs/architecture/attribution.md

This trailer is added to commits to indicate the attribution percentage of agent vs. user contributions.

```git
feat: Add user authentication

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

--------------------------------

### Root Checkpoint Summary Metadata JSON

Source: https://github.com/entireio/cli/blob/main/docs/architecture/sessions-and-checkpoints.md

Example of the root metadata.json file for a checkpoint, containing aggregated statistics and session mapping.

```json
{
  "checkpoint_id": "abc123def456",
  "strategy": "manual-commit",
  "branch": "main",
  "checkpoints_count": 3,
  "files_touched": ["file1.txt", "file2.txt"],
  "sessions": [
    {
      "metadata": "/ab/c123def456/0/metadata.json",
      "transcript": "/ab/c123def456/0/full.jsonl",
      "content_hash": "/ab/c123def456/0/content_hash.txt",
      "prompt": "/ab/c123def456/0/prompt.txt"
    }
  ],
  "token_usage": {
    "input_tokens": 1500,
    "cache_creation_tokens": 200,
    "cache_read_tokens": 800,
    "output_tokens": 500,
    "api_call_count": 3
  }
}
```

--------------------------------

### Log User Content Insecurely

Source: https://github.com/entireio/cli/blob/main/docs/architecture/logging.md

Example demonstrating what NOT to log, specifically including user prompt content which violates privacy guidelines.

```go
// BAD - logs user content
logging.Info(ctx, "post-task",
    slog.String("task_description", taskDescription),  // Contains user prompt!
    slog.String("prompt", input.Prompt),               // User data!
)
```

--------------------------------

### Check Binary Path

Source: https://github.com/entireio/cli/blob/main/CONTRIBUTING.md

Use these commands to check which `entire` binary is being used. This is helpful when a binary is not updating after a rebuild, as you may have multiple installations.

```bash
which entire
type -a entire
```

--------------------------------

### Configure Entire CLI - Show Help

Source: https://github.com/entireio/cli/blob/main/README.md

Displays help information and hints, including guidance on using `entire agent`.

```bash
entire configure
```

--------------------------------

### Reload Shell After Mise Install

Source: https://github.com/entireio/cli/blob/main/docs/first-time-contributors.md

If `mise install` fails, reload your shell configuration and retry the installation.

```bash
# Reload your shell after installing mise
source ~/.zshrc  # or ~/.bashrc

# Then retry
mise install
```

--------------------------------

### Local Device Auth Testing Setup

Source: https://github.com/entireio/cli/blob/main/README.md

Steps to set up local device authentication testing against a local entire.io checkout. This involves navigating to repositories, running development servers, and configuring the CLI to point to a local API.

```bash
# In your app repo
cd ../entire.io-1
mise run dev

# In this repo, point the CLI at the local API. The login flow targets
# the local server via --server (the default is the production
# us.auth.entire.io).
cd ../cli
export ENTIRE_API_BASE_URL=http://localhost:8787
entire login --server https://localhost:8180

# Run the smoke test
./scripts/local-device-auth-smoke.sh
```

--------------------------------

### Load and Use CLI Settings

Source: https://github.com/entireio/cli/blob/main/AGENTS.md

Access CLI settings by importing the 'settings' package. Load the full settings object or use convenience functions for specific settings.

```go
import "github.com/entireio/cli/cmd/entire/cli/settings"

// Load full settings object
s, err := settings.Load()
if err != nil {
    // handle error
}
if s.Enabled {
    // ...
}

// Or use convenience functions
if settings.IsSummarizeEnabled() {
    // ...
}

```

--------------------------------

### Build Entire CLI Natively on Windows

Source: https://github.com/entireio/cli/blob/main/WINDOWS.md

Build the Entire CLI directly on a Windows machine using the Go toolchain. The output binary will be named 'entire.exe'.

```bash
go build -o entire.exe ./cmd/entire/
```

--------------------------------

### are-hooks-installed

Source: https://github.com/entireio/cli/blob/main/docs/architecture/external-agent-protocol.md

Checks whether hooks are currently installed. Outputs JSON indicating the installation status.

```APIDOC
## are-hooks-installed

### Description
Checks whether hooks are currently installed.

### Arguments
None

### Output (stdout)
JSON

```json
{"installed": true}
```
```

--------------------------------

### Check Hooks Installation Status

Source: https://github.com/entireio/cli/blob/main/docs/architecture/external-agent-protocol.md

This JSON output from the `are-hooks-installed` command indicates whether agent hooks are currently installed.

```json
{"installed": true}
```

--------------------------------

### Codex CLI Interactive Mode

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/codex/AGENT.md

Start the Codex CLI in interactive mode (TUI). You can also provide a prompt to start directly.

```bash
codex
```

```bash
codex "<prompt>"
```

--------------------------------

### Package Structure for Session and Checkpoint Management

Source: https://github.com/entireio/cli/blob/main/docs/architecture/sessions-and-checkpoints.md

Provides an overview of the Go package structure for managing sessions and checkpoints, highlighting key files and their responsibilities.

```go
strategy/
├── session.go           # Session and Checkpoint types

session/
├── state.go             # Active session state (StateStore, .git/entire-sessions/)
├── phase.go             # Session phase state machine (ACTIVE, IDLE, ENDED, etc.)

checkpoint/
├── checkpoint.go        # checkpoint.Type, checkpoint.Store interface, CheckpointSummary, etc.
├── store.go             # GitStore implementation
├── temporary.go         # Shadow branch storage
├── committed.go         # Metadata branch storage
├── id/                  # CheckpointID type and generation
│   └── id.go
```

--------------------------------

### Configure and Run E2E Tests on Windows

Source: https://github.com/entireio/cli/blob/main/WINDOWS.md

Set up environment variables and run End-to-End tests for the Entire CLI on Windows. Ensure the agent binary is in your PATH.

```bash
# Set required env vars
set E2E_ENTIRE_BIN=entire.exe
set E2E_AGENT=claude-code        # or gemini-cli, opencode

# Run all E2E tests
go test -tags=e2e -count=1 -timeout=30m ./e2e/tests/...

# Run a specific test
go test -tags=e2e -count=1 -timeout=30m -run TestSingleSessionManualCommit ./e2e/tests/...
```

--------------------------------

### Test Hook Installation Idempotency

Source: https://github.com/entireio/cli/blob/main/docs/architecture/agent-guide.md

Ensures that calling InstallHooks multiple times is idempotent. The second call should not report any new hooks being installed, returning a count of 0.

```go
func TestInstallHooks_Idempotent(t *testing.T) {
    t.Parallel()

    // Install twice, second call should return count=0
    ag := &YourAgent{}
    ag.InstallHooks(false, false)
    count, _ := ag.InstallHooks(false, false)
    if count != 0 {
        t.Errorf("expected 0 new hooks on second install, got %d", count)
    }
}
```

--------------------------------

### Configure Summarize Provider

Source: https://github.com/entireio/cli/blob/main/docs/architecture/external-agent-protocol.md

This bash command configures an external agent to be used as a summary provider for the `entire explain --generate` command.

```bash
entire configure --summarize-provider <agent-name> [--summarize-model <model>]
```

--------------------------------

### Basic `entire review` Command Usage

Source: https://github.com/entireio/cli/blob/main/docs/architecture/review-command.md

Run the `entire review` command with default configuration. This loads the configured skills and runs them within an agent session.

```bash
entire review
```

--------------------------------

### Test Agent Event Parsing for Session Start

Source: https://github.com/entireio/cli/blob/main/docs/architecture/agent-guide.md

Unit test for parsing the session start event. Verifies correct event type, session ID, and transcript path are extracted from the input.

```go
package youragent

import (
	"strings"
	"testing"

	"github.com/entireio/cli/cmd/entire/cli/agent"
)

func TestParseHookEvent_SessionStart(t *testing.T) {
	t.Parallel()

	ag := &YourAgent{}
	input := `{"session_id": "test-session", "transcript_path": "/tmp/transcript.jsonl"}`

	event, err := ag.ParseHookEvent(HookNameSessionStart, strings.NewReader(input))

	if err != nil {
		t.Fatalf("unexpected error: %v", err)
	}
	if event == nil {
		t.Fatal("expected event, got nil")
	}
	if event.Type != agent.SessionStart {
		t.Errorf("expected SessionStart, got %v", event.Type)
	}
	if event.SessionID != "test-session" {
		t.Errorf("expected session_id 'test-session', got %q", event.SessionID)
	}
}

```

--------------------------------

### Create Disposable Git Repository

Source: https://github.com/entireio/cli/blob/main/docs/architecture/copilot-token-validation.md

Initializes a temporary git repository for testing Copilot CLI interactions, including setting user information and enabling the Copilot agent.

```bash
tmpdir="$(mktemp -d)"
cd "$tmpdir"
git init
git config user.name "Entire Test"
git config user.email "entire@example.com"
printf 'start\n' > README.md
git add README.md
git commit -m "init"
entire enable --agent copilot-cli
```

--------------------------------

### Agent Implementation Skeleton

Source: https://github.com/entireio/cli/blob/main/docs/architecture/agent-guide.md

A basic agent implementation including registration, name, type, description, protected directories, presence detection, and transcript handling.

```go
package youragent

import (
	"errors"
	"fmt"
	"io"
	"os"
	"path/filepath"

	"github.com/entireio/cli/cmd/entire/cli/agent"
	"github.com/entireio/cli/cmd/entire/cli/paths"
)

//nolint:gochecknoinits // Agent self-registration is the intended pattern
func init() {
	agent.Register("your-agent", NewYourAgent)
}

type YourAgent struct{}

func NewYourAgent() agent.Agent { return &YourAgent{} }

func (a *YourAgent) Name() agent.AgentName  { return "your-agent" }
func (a *YourAgent) Type() agent.AgentType   { return "Your Agent" }
func (a *YourAgent) Description() string     { return "Your Agent - brief description" }
func (a *YourAgent) ProtectedDirs() []string { return []string{'.youragent'}
}

func (a *YourAgent) DetectPresence() (bool, error) {
	repoRoot, err := paths.RepoRoot()
	if err != nil {
		repoRoot = "."
	}
	if _, err := os.Stat(filepath.Join(repoRoot, ".youragent")); err == nil {
		return true, nil
	}
	return false, nil
}

func (a *YourAgent) ReadTranscript(sessionRef string) ([]byte, error) {
	data, err := os.ReadFile(sessionRef) //nolint:gosec // Path from agent hook
	if err != nil {
		return nil, fmt.Errorf("failed to read transcript: %w", err)
	}
	return data, nil
}

func (a *YourAgent) ChunkTranscript(content []byte, maxSize int) ([][]byte, error) {
	return agent.ChunkJSONL(content, maxSize)
}

func (a *YourAgent) ReassembleTranscript(chunks [][]byte) ([]byte, error) {
	return agent.ReassembleJSONL(chunks), nil
}

// --- Session Management ---
func (a *YourAgent) GetHookConfigPath() string                                          { return "" }
func (a *YourAgent) SupportsHooks() bool                                                { return true }
func (a *YourAgent) ParseHookInput(_ agent.HookType, r io.Reader) (*agent.HookInput, error) {
	raw, err := agent.ReadAndParseHookInput[sessionInfoRaw](r)
	if err != nil {
		return nil, err
	}
	return &agent.HookInput{SessionID: raw.SessionID, SessionRef: raw.TranscriptPath}, nil
}
func (a *YourAgent) GetSessionID(input *agent.HookInput) string                         { return input.SessionID }
func (a *YourAgent) GetSessionDir(_ string) (string, error)                             { return "", errors.New("not implemented") }
func (a *YourAgent) ResolveSessionFile(dir, id string) string                           { return filepath.Join(dir, id+".jsonl") }
func (a *YourAgent) ReadSession(_ *agent.HookInput) (*agent.AgentSession, error)        { return nil, errors.New("not implemented") }
func (a *YourAgent) WriteSession(_ *agent.AgentSession) error                           { return errors.New("not implemented") }
func (a *YourAgent) FormatResumeCommand(id string) string                               { return "youragent --resume " + id }
```

--------------------------------

### uninstall-hooks

Source: https://github.com/entireio/cli/blob/main/docs/architecture/external-agent-protocol.md

Removes installed agent hooks. Exits with 0 on success.

```APIDOC
## uninstall-hooks

### Description
Removes installed agent hooks.

### Arguments
None

### Output
Exit 0 on success.
```

--------------------------------

### Run Full CI Suite

Source: https://github.com/entireio/cli/blob/main/CONTRIBUTING.md

Command to run the complete Continuous Integration test suite.

```bash
mise run test:ci
```

--------------------------------

### Enable Specific Agent Non-interactively

Source: https://github.com/entireio/cli/blob/main/README.md

Enables a specific agent non-interactively during the initial setup.

```bash
entire enable --agent <name>
```

--------------------------------

### Enable Entire in Project

Source: https://github.com/entireio/cli/blob/main/README.md

Enables the Entire service within your project directory. Navigate to your project's root directory before running this command.

```bash
# Enable in your project
cd your-project && entire enable
```

--------------------------------

### Calculation Flow Diagram

Source: https://github.com/entireio/cli/blob/main/docs/architecture/attribution.md

Illustrates the step-by-step process of calculating attribution from session start to final commit.

```text
Session Start (base commit)
    │
    ▼
┌─────────────────────────────────┐
│ User edits files                │
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ Prompt submitted                │
│ → CalculatePromptAttribution()  │
│ → Capture user edits per file   │
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ Agent runs, creates checkpoint  │
│ → Shadow branch updated         │
└─────────────────────────────────┘
    │
    ▼
    ... (repeat for multiple prompts) ...
    │
    ▼
┌─────────────────────────────────┐
│ User makes final edits          │
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ User commits                    │
│ → CalculateAttributionWith-     │
│   Accumulated()                 │
│ → Sum all PromptAttributions    │
│ → Add post-checkpoint edits     │
│ → Estimate self-modifications   │
│ → Calculate final percentage    │
└─────────────────────────────────┘
    │
    ▼
Commit with Entire-Attribution trailer
```

--------------------------------

### Interactive Prompt with Initial Prompt

Source: https://github.com/entireio/cli/blob/main/cmd/entire/cli/agent/copilotcli/AGENT.md

Start an interactive session with an initial prompt using the `-i` flag.

```bash
copilot -i "prompt"
```

--------------------------------

### Enable Entire CLI and Save Settings Locally

Source: https://github.com/entireio/cli/blob/main/README.md

Use this flag to write settings to `settings.local.json` instead of the default `settings.json`, preventing them from being committed to git.

```bash
entire enable --local
```

--------------------------------

### Event Object Example

Source: https://github.com/entireio/cli/blob/main/docs/architecture/external-agent-protocol.md

The Event object is returned by `parse-hook` and represents a normalized lifecycle event within an agent session.

```json
{
  "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"
}
```

--------------------------------

### Run Mock Session Harness for Copilot Token Metadata

Source: https://github.com/entireio/cli/blob/main/docs/architecture/copilot-token-validation.md

Use this script to create a reproducible two-turn Copilot session and inspect the raw metadata directly. It sets up a repository, writes mock transcripts, runs Copilot CLI hooks, creates commits, and prints checkpoint and session state payloads. It fails if token counts regress.

```bash
scripts/test-copilot-token-metadata.sh --keep-temp
```

--------------------------------

### JSONL Format Example (Claude)

Source: https://github.com/entireio/cli/blob/main/docs/architecture/agent-guide.md

Each line is a JSON object representing a transcript entry. Use agent.ChunkJSONL for chunking and agent.ReassembleJSONL for reassembly.

```json
{"type":"user","message":{"role":"user","content":"Fix the bug"},"timestamp":"..."}
{"type":"assistant","message":{"role":"assistant","content":[...]},"timestamp":"..."}
```