clarify token profile usage scope · Entire
clarify token profile usage scope
d024a58·
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
22
23
24
25
26
27
28
25
26
27
28
29
30
31
30
32
33
34
35
36
37
36
38
39
40
41
5 unmodified lines
47
48
49
50
51
52
53
54
55
56
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
506 unmodified lines
507
508
509
510
511
512
513
514
511
515
516
517
518
506 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
15
16
17
18
19
20
21
25 unmodified lines
47
48
49
50
51
52
53
54
81 unmodified lines
136
137
138
139
140
141
142
217 unmodified lines
360
361
362
363
364
365
366
367
368
21 unmodified lines
390
391
392
386
393
394
395
396
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"`
25 unmodified lines
{id: "missing-token-data", label: "Missing token data"},
}
const tokensProfileUsageScopeCheckpointObserved = "checkpoint_observed"
func newTokensGroupCmd() *cobra.Command {
cmd := &cobra.Command{
Use: "tokens",
81 unmodified lines
infos = limitTokensProfileCheckpoints(infos, limit)
report := tokensProfileReport{
Source: "committed_checkpoints",
UsageScope: tokensProfileUsageScopeCheckpointObserved,
CheckpointsAvailable: checkpointsAvailable,
CheckpointsAnalyzed: len(infos),
}
217 unmodified lines
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)))
}
if report.Tokens != nil {
limitations = append(limitations, "Token totals are summed from analyzed checkpoints and may include overlapping checkpoint history; treat them as checkpoint-observed volume, not guaranteed unique session spend.")
}
if report.CheckpointsAnalyzed > 0 {
limitations = append(limitations, "Tool-level search/read spend is not captured yet; this profile infers patterns from token totals, cache/context replay, API call counts, and subagent totals.")
}
21 unmodified lines
fmt.Fprintf(w, "Metadata warnings: %d\n", report.MetadataReadWarnings)
}
writeTokenUsageSection(w, report.Tokens)
writeTokenUsageSectionWithTitle(w, "Checkpoint-observed token usage", report.Tokens)
writeTokensProfileSignals(w, report.Signals)
if len(report.Recommendations) > 0 {
writeTokenRecommendations(w, report.Recommendations)
Mcmd/entire/cli/tokens_profile.go+8/-1
54 unmodified lines
55
56
57
58
58
59
60
61
4 unmodified lines
66
67
68
69
70
71
72
2 unmodified lines
75
76
77
77
78
79
80
81
32 unmodified lines
114
115
116
117
118
119
120
121
122
123
124
125
126
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",
4 unmodified lines
"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",
}
for _, check := range checks {
2 unmodified lines
}
}
tokenUsageIndex := strings.Index(out, "Token usage")
tokenUsageIndex := strings.Index(out, "Checkpoint-observed token usage")
recommendationsIndex := strings.Index(out, "Recommendations")
if tokenUsageIndex == -1 || recommendationsIndex == -1 {
t.Fatalf("expected token usage and recommendations sections, got:\n%s", out)
32 unmodified lines
if err := json.Unmarshal(stdout.Bytes(), &result); err != nil {
t.Fatalf("expected valid JSON, got parse error: %v\noutput: %s", err, stdout.String())
}
var raw map[string]interface{}
if err := json.Unmarshal(stdout.Bytes(), &raw); err != nil {
t.Fatalf("expected valid JSON object, got parse error: %v\noutput: %s", err, stdout.String())
}
if raw["usage_scope"] != "checkpoint_observed" {
t.Fatalf("usage_scope = %v, want checkpoint_observed", raw["usage_scope"])
}
if result.CheckpointsAnalyzed != 2 {
t.Fatalf("checkpoints_analyzed = %d, want 2", result.CheckpointsAnalyzed)
}