# clarify token profile usage scope

`5db9821`·

peyton-alt·3w ago·4 files·+35 added/-10 removed

## Sessions

aa9d6a1ab8b0View transcript

## Changes

4

- MCLAUDE.md+12/-6
- cmd/entire/cli

- Msession_tokens.go+5/-1
  - Mtokens_profile.go+8/-1
  - Mtokens_profile_test.go+10/-2

```
21 unmodified lines
```

### Command Layout

The CLI is organized around five noun groups plus a small set of top-level verbs. The groups are the canonical home for each verb; legacy top-level shortcuts remain functional but hidden, and emit a deprecation hint pointing at the canonical group form.

The visible CLI is organized around five noun groups plus a small set of top-level verbs. The groups are the canonical home for each verb; legacy top-level shortcuts remain functional but hidden, and emit a deprecation hint pointing at the canonical group form. Newer experimental command families are discoverable through `entire labs` and may remain hidden from root help while their canonical paths are still runnable.

- `session` (alias: `sessions`): `list`, `info`, `stop`, `attach`, `resume`, `current`.
- `session` (alias: `sessions`): `list`, `info`, `tokens`, `stop`, `attach`, `resume`, `current`.
  `resume` with a branch arg switches to it and resumes its session; with no arg it opens an interactive picker of stopped sessions (across all worktrees), resolving each to its branch and pointing at the owning worktree when the branch is checked out elsewhere. Resume keeps an existing local session log as-is by default (`--force` overwrites it from the checkpoint).
- `checkpoint` (aliases: `cp`, `checkpoints`): `list`, `explain`, `search`, plus
- `checkpoint` (aliases: `cp`, `checkpoints`): `list`, `explain`, `tokens`, `search`, plus
the deprecated `rewind` (functional, prints a cobra deprecation message, will be removed in a future release)
- `agent`: bare opens the interactive agent selector, plus `list`, `add`, `remove`

Experimental command families advertised through `entire labs`:

- `tokens`: `profile` (hidden from root help while token diagnostics mature)

Top-level lifecycle and standalone commands: `enable`, `disable`, `status`, `login`, `logout`, `clean`, `version`, `dispatch`, `activity`, `help`, `configure`.

```
MCLAUDE.md+12/-6
```

```
513 unmodified lines
```

```go
func writeTokenUsageSection(w io.Writer, tokens *sessionTokensUsage) {
	writeTokenUsageSectionWithTitle(w, "Token usage", tokens)
}

func writeTokenUsageSectionWithTitle(w io.Writer, title string, tokens *sessionTokensUsage) {
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Token usage")
	fmt.Fprintln(w, title)
	if tokens != nil {
		fmt.Fprintf(w, "Total:  %s tokens\n", formatTokenCount(tokens.Total))
		parts := []string{
```

```
Mcmd/entire/cli/session_tokens.go+5/-1
```

```
14 unmodified lines
```

```
360 unmodified lines
```

```
type tokensProfileReport struct {
	Source                   string                        `json:"source"`
	UsageScope               string                        `json:"usage_scope"`
	CheckpointsAvailable     int                           `json:"checkpoints_available"`
	CheckpointsAnalyzed      int                           `json:"checkpoints_analyzed"`
	CheckpointsWithTokenData int                           `json:"checkpoints_with_token_data"`
}
```

```
const tokensProfileUsageScopeCheckpointObserved = "checkpoint_observed"
```

```
        "Checkpoints analyzed: 4",
        "With token data:      3",
        "Missing token data:   1",
        "Token usage",
        "Checkpoint-observed token usage",
        "Total:  3.5k tokens",
        "Cache read: 800",
        "API calls: 33",
        "Missing token data: 1 checkpoint",
        "Recommendations",
        "Use `entire search` for prior decisions/checkpoints before broad re-investigation.",
        "Token totals are summed from analyzed checkpoints and may include overlapping checkpoint history",
        "Tool-level search/read spend is not captured yet",
    }
```

``` 
14 unmodified lines
```