clarify token profile usage scope · Entire

clarify token profile usage scope

e1c1afc·

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

Sessions

aa9d6a1ab8b0View transcript

Changes

4

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`
- `doctor`: bare runs the scan-and-fix flow, plus `trace`, `logs`, `bundle`

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

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

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"

func newTokensGroupCmd() *cobra.Command {
    cmd := &cobra.Command{
        Use:   "tokens",
}

// Additional code omitted for brevity

Mcmd/entire/cli/tokens_profile.go+8/-1

54 unmodified lines

"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",

Mcmd/entire/cli/tokens_profile_test.go+10/-2