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

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