Repository navigation
feat(cli): add a read-only /context diagnostics view #1423
Description
Problem
Maka’s TUI status line shows a compact context-usage indicator, but users cannot inspect what is consuming the current context window or understand whether the displayed values are measured or estimated.
This becomes increasingly important in long-running agent sessions involving tool calls, large results, and context compaction. Diagnostics should also remain consistent after switching, restarting, or resuming a session.
Comparable tools expose this as a read-only command:
Desired outcome
Add a read-only /context command to the Maka TUI that describes the latest completed model request.
It should:
- Show context used, total, free space, and percentage when reliable data is available.
- Clearly distinguish provider-reported totals from locally estimated categories.
- Provide a high-level breakdown such as system instructions, tool definitions, and messages.
- Show compaction information relevant to the displayed request when available.
- Produce the same result after session switch, restart, or resume.
- Degrade clearly when historical or trace data is unavailable.
The command must not send a model message, modify context, or trigger compaction.
Implementation direction
Prefer existing Runtime and provider-request trace data rather than introducing a second request-snapshot system.
The latest completed provider request should be the source for request usage and breakdown. Historical values must not be interpreted using the session’s currently selected model.
Existing promptSegments should not be treated as a complete latest-request snapshot because its inputs may represent different phases of a turn.
The exact rendering and internal projection API are intentionally left open.
Acceptance criteria
-
/contextis available as a local, read-only TUI command. - The view represents the latest completed provider request.
- Actual and estimated values are visibly distinguished.
- Missing data results in an explicit unavailable or empty state rather than inferred values.
- Session switch, restart, and resume preserve the same available snapshot.
- Output remains readable in narrow terminals.
- The feature does not introduce context-management actions.
Non-goals
- Exact tokenizer-level category accounting.
- Per-file or per-message drill-down.
- Separate accounting for Skills, MCP servers, memory, or workspace instructions.
- Optimization recommendations.
/compactintegration or context editing.- Session-wide cumulative tool-call or compaction statistics.
Related work
- fix(runtime): preserve token usage fields across replay #1422 preserves token-usage fields across persistence and replay.
- [MM-13] Migrate desktop and CLI context assembly to ContextEngine #792 tracks shared ContextEngine ownership and cross-surface diagnostics.
中文说明
问题
Maka TUI 状态栏已有简略的上下文占用信息,但用户无法查看当前上下文主要被什么占用,也无法判断展示的数据是 provider 实际 token 还是本地估算。
在包含大量工具调用、工具结果和上下文压缩的长会话中,这类诊断尤其重要。切换、重启或恢复 session 后,结果也应保持一致。
Claude Code 和 Grok Build 已提供类似的只读 /context 能力。
期望结果
为 Maka TUI 增加只读 /context,描述最新一次已完成的模型请求。
它应当:
- 在数据可靠时展示 used、total、free 和百分比。
- 明确区分 provider 实际总量与本地分类估算。
- 提供 System instructions、Tool definitions、Messages 等高层分类。
- 在可用时展示与当前请求相关的压缩信息。
- 在 session switch、restart 和 resume 后保持一致。
- 数据不足时明确降级,不推算或伪造结果。
该命令不能发送模型消息、修改上下文或触发压缩。
实现方向
优先复用现有 Runtime 和 provider-request trace,不新增第二套 request snapshot。
请求用量和 breakdown 应以最新一次已完成的 provider request 为准。历史数据不能使用 session 当前选择的模型进行解释。
现有 promptSegments 可能包含 turn 不同阶段的数据,因此不能直接视为完整的 latest-request snapshot。
具体渲染和内部投影 API 不在本 issue 中提前锁定。
验收标准
-
/context是本地只读 TUI 命令。 - 展示最新一次已完成的 provider request。
- 实际值与估算值有明确标识。
- 数据缺失时显示 unavailable 或 empty state,不进行推算。
- session switch、restart、resume 后可恢复相同的可用快照。
- 窄终端下保持可读。
- 不引入上下文管理动作。
非目标
- 精确 tokenizer 级分类。
- 逐文件或逐消息下钻。
- Skills、MCP、Memory、workspace instructions 独立计量。
- 优化建议。
/compact联动或上下文编辑。- session 累计 tool-call、compaction 统计。
相关工作
- fix(runtime): preserve token usage fields across replay #1422 修复 token usage 字段的持久化与 replay。
- [MM-13] Migrate desktop and CLI context assembly to ContextEngine #792 跟踪统一 ContextEngine ownership 和跨 surface diagnostics。
Activity
[-]feat(tui): add a read-only /context diagnostics view[/-][+]feat(cli): add a read-only /context diagnostics view[/+]Astro-Han commentedon Jul 24, 2026
It would be great if we have it in Desktop as well! We could add a follow-up after it is implemented in TUI.