Debugging AI Coding Agents: How to See Prompts, Tool Call...

When a coding agent fails, the visible error is rarely the whole story.

You might see:

a tool call that never ran
a command repeated again and again
a sudden token spike
a provider rejecting a request with 400 Bad Request
an agent that says it edited a file but did not
a long session that starts producing shallow or confused answers

The usual reaction is to tweak the prompt and try again.

Sometimes that works. But for agentic coding tools, guessing is not enough. You need to inspect what the agent actually sent to the model.

That is the problem ccglass is built for.

GitHub: https://github.com/jianshuo/ccglass

The debugging problem with coding agents

Modern coding agents are not simple chatbots.

Tools like Claude Code, Codex, OpenCode, CodeBuddy, Qoder, and similar systems usually run a loop like this:

user request
  -> model request
  -> tool call
  -> local command / file read / edit / search
  -> tool result
  -> next model request
  -> final answer

When something goes wrong, the bug can be in any part of that loop.

For example:

The model never saw the tool schema you thought it saw.
The tool schema was too large or malformed.
The model returned a malformed tool call.
The local client dropped part of the tool result.
A huge tool result entered the next request and inflated token usage.
The provider rejected a request shape that another provider accepts.
A proxy or gateway translated Anthropic and OpenAI formats incorrectly.

You cannot debug that reliably from the final answer alone.

What to inspect first

When an agent behaves strangely, I usually want to see five things.

1. The system prompt

The system prompt often explains behavior that looks mysterious from the outside.

It may contain rules about:

when to ask permission
when to use tools
how much work to do before stopping
whether to run tests
whether to preserve existing files
how to summarize results

If the agent ignores your instruction, first check whether the system prompt is pushing it in a different direction.

2. The tool schema

Tool calling depends heavily on the schema sent to the model.

If a tool is described vaguely, has confusing parameter names, or contains a schema shape the provider does not like, the model may choose the wrong tool or produce invalid arguments.

This matters even more with MCP servers and custom tools.

The question is not "what did my code define?" The real question is:

What tool schema was actually sent in the model request?

3. The tool call

A tool call bug can come from the model, the client, or the provider adapter.

You want to inspect:

tool name
call id
arguments
malformed fields
missing required fields
whether the tool call was emitted as structured data or plain text

For example, if the model emits something that looks like a tool call but the client renders it as text, the agent may continue as if the tool ran even though no tool result exists.

4. The tool result

Tool results are often the hidden source of context bloat.

A single file read, search result, stack trace, or command output can add thousands of tokens to the next turn.

If the agent suddenly becomes expensive or confused, check what tool results were fed back into the model.

5. Token usage and latency

Token totals are useful, but per-request token usage is better.

You want to know:

which request got expensive
whether input, output, or cache tokens dominated
whether a request was slow before the first token
whether repeated turns reused the same large context
whether a provider returned usage data at all

That is the difference between "this session was expensive" and "this specific tool result caused the spike."

Using ccglass for request-level debugging

ccglass is a local proxy and dashboard for coding-agent traffic.

It lets you inspect what supported agents actually send to the model:

system prompts
messages
tool schemas
tool calls
tool results
raw request and response bodies
token/cache/cost
latency
turn-to-turn diffs

It works locally. It is open source.

Install:

npm install -g ccglass

Start it:

ccglass

Or choose a client directly:

ccglass claude
ccglass codex
ccglass opencode
ccglass qoder
ccglass codebuddy

For generic OpenAI-compatible or Anthropic-compatible clients, you can also run proxy-only mode:

ccglass proxy --provider openai
ccglass proxy --provider claude

Then point your client or IDE at the printed local base URL.

Example debugging workflow

Suppose an agent repeatedly fails to call a tool correctly.

Instead of changing the prompt first, inspect the actual request flow:

Open the ccglass dashboard.
Find the request where the model was expected to call the tool.
Expand the system prompt and tool schema.
Check whether the tool was visible to the model.
Check the model response for the tool call.
Check whether the tool result was paired correctly.
Compare the next request to see what context was carried forward.

That gives you a factual answer to questions like:

Did the model see the tool?
Did it call the wrong tool?
Were the arguments malformed?
Did the client drop the tool result?
Did the next turn include the right result?

Example: debugging token spikes

Another common problem:

Why did this one coding-agent session use so many tokens?

In ccglass, inspect the request list and session summary.

Look for:

a request with unusually high input tokens
a large tool result entering the next request
many repeated requests with similar context
cache usage that is lower than expected
a slow request with high input size

Then use turn-to-turn diff to see what changed between two requests.

This is often more useful than looking only at the final cost.

Example: debugging provider 400 errors

Provider errors are another good use case.

If an Anthropic-compatible or OpenAI-compatible endpoint rejects a request, you need the exact payload.

Check:

request body
tool schema
message order
tool_use / tool_result pairing
response or error body
provider/model name

This is useful when working with:

internal gateways
OpenRouter
Ollama-compatible endpoints
Bedrock or Vertex routes
Anthropic-compatible translation layers
OpenAI-compatible coding-agent backends

The failure is often not "the model is bad." It is often a request-shape problem.

Exporting evidence

ccglass can export captured requests:

ccglass export <session>/<seq> --format raw
ccglass export <session>/<seq> --format md
ccglass export <session>/<seq> --format json
ccglass export <session>/<seq> --format har

That is useful when reporting bugs to an agent project, provider, or proxy maintainer.

Instead of saying:

The agent failed.

You can show:

This exact request contained this tool schema, this model response emitted this malformed tool call, and this provider returned this error.

That is much easier to debug.

A few practical notes

ccglass is not a universal network sniffer.

It works best when the client can be pointed at a local base URL or local proxy. For example, API-key based OpenAI-compatible and Anthropic-compatible traffic is a good fit.

Some clients have special transports. For example, Codex authenticated through ChatGPT login may use a WebSocket path that does not honor OPENAI_BASE_URL, so local base URL inspection will not see that traffic.

For CodeBuddy, ccglass uses a forward-proxy mode because CodeBuddy hardcodes its upstream endpoint.

Why this matters

As coding agents become more autonomous, debugging needs to move one layer deeper.

It is no longer enough to ask:

Did the agent produce the right diff?

You also need to ask:

What did the agent see, what tool did it choose, what result came back, and what context entered the next turn?

That is what ccglass tries to make visible.

GitHub:

https://github.com/jianshuo/ccglass