clarify token profile usage scope

ad985be·

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

Sessions

aa9d6a1ab8b0View transcript

?\ okay proceedCodex·GPT-5.5·4 steps

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.
• checkpoint (aliases: cp, checkpoints): list, explain, 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

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

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

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

if report.MetadataReadWarnings > 0 {
    limitations = append(limitations, fmt.Sprintf("%d checkpoint%s had incomplete session metadata; profile used root token summaries or readable sessions where available.", report.MetadataReadWarnings, pluralSuffix(report.MetadataReadWarnings)))
}