Previous article：Context Builder for AI Coding Agents
Next article：Git Diff Tools for AI Coding Agents: Status, Parsed Patches, and Change Summaries
中文版：Context Explorer：调试 Prompt 与 Token 使用

Introduction

Day 09: inspect an agent prompt, token budget, and the context parts that consume it. This chapter keeps the implementation deliberately small: the point is to make one boundary explicit, testable, and easy to inspect before adding more autonomy.

Questions a context explorer should answer

A coding agent is more than a model response. It needs a runtime that can turn a request into controlled work, preserve the intermediate state, and explain what happened afterwards. Day 09 focuses on that runtime boundary instead of hiding it behind a single prompt.

context parts → token estimates → grouped report → budget warning → targeted fix

Estimating and grouping token use

The implementation uses explicit data structures and narrow interfaces. The model proposes the next step; the harness owns validation, execution, limits, and structured results. That separation lets the same capability work in a CLI today and in a richer product surface later.

• Show total estimated tokens and the remaining budget.
• Group parts by kind so disproportionate context is obvious.
• Surface the largest individual parts before changing selection logic.

Using a budget to find pressure

Reliability comes from treating failure paths as normal paths. Inputs are bounded, unsafe or malformed requests produce recoverable errors, and the run records enough evidence to let a developer understand the decision. This is especially important when later steps can touch a real workspace.

npm run dev -- --context-report --context-budget 8000 "inspect context usage"

Context Explorer

Total estimated tokens: ~6,018 tokens
Token budget:           ~8,000 tokens (75.2% used, ~1,982 tokens remaining)

By kind
conversation    ~2,410 tokens    40.0%  3 parts  [######----------]
tool-results    ~1,702 tokens    28.3%  1 part  [#####-----------]
system          ~1,023 tokens    17.0%  1 part  [###-------------]
files             ~492 tokens     8.2%  1 part  [#---------------]
tools             ~391 tokens     6.5%  1 part  [#---------------]

What context was selected?
Where did it come from?
How much budget does each category consume?
Which part is crowding out the rest?
Is the model request close to the budget limit?

Keeping production and diagnostics separate

With this layer in place, later chapters can add capability without weakening the boundary: tools can be registered and observed, context can be measured, writes can require approval, and every run can be replayed. The result is not a general autonomous system; it is a compact harness whose behavior remains understandable.

Key takeaways

• Build the execution boundary before adding more tools or model freedom.
• Keep model intent separate from runtime authority.
• Make limits, validation, and failure results visible.
• Use structured observations to support debugging and future extensions.

Demo

The accompanying implementation and runnable examples are available in the cli-harness repository.