# Debugging Agent Execution Flow in Codebuff: Recommended Strategies

> Debug agent execution flow in Codebuff effectively. Learn strategies: enable full logging, use structured logger, and inspect JSONL logs with comparison scripts.

- Repository: [Codebuff/codebuff](https://github.com/CodebuffAI/codebuff)
- Tags: how-to-guide
- Published: 2026-03-09

---

**To debug agent execution flow in Codebuff, enable the `CACHE_DEBUG_FULL_LOGGING` flag, use the structured `logger` utility with context-aware logging, and inspect the JSONL debug logs and cache snapshots using built-in comparison scripts.**

Codebuff’s agents execute through a tightly-coupled loop that builds prompts, streams LLM responses, processes tool calls, and persists state. Because this flow is highly dynamic, the repository provides several built-in mechanisms to make debugging transparent and reproducible. This guide covers the architectural hooks and practical workflows for debugging agent execution flow in Codebuff.

## Core Debugging Architecture

The debugging system centers on a **Pino-based logger** that writes structured JSON lines to `debug/web.jsonl` during local development. This logger is configured in [`web/src/util/logger.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/util/logger.ts) (lines 18-49), where it creates the debug folder and sets up the destination stream. When running in development mode (`IS_DEV && !IS_CI`), logs also fall back to console output for real-time monitoring.

For correlating messages across asynchronous steps, the `loggerWithContext` function (lines 71-88 in the same file) injects static context—such as `runId` and `agentId`—into every log entry. This makes it trivial to grep for a specific execution trace across thousands of log lines.

## Enabling Full Request Logging

The most powerful switch for debugging agent execution flow is `CACHE_DEBUG_FULL_LOGGING`, defined in [`packages/agent-runtime/src/constants.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/constants.ts) (lines 5-12). When set to `true`, the runtime persists the complete LLM request—including the system prompt, tool definitions, and message history—to `debug/cache-debug/<runId>-<iteration>.json`.

This is the only mechanism that provides a per-prompt snapshot of exactly what the runtime sends to the provider, making it essential for diagnosing prompt-cache misses or unexpected token counts.

To enable it:

```typescript
// packages/agent-runtime/src/constants.ts
export const CACHE_DEBUG_FULL_LOGGING = true; // <-- enable full request logging

```

## Structured Logging in the Execution Loop

The core agent execution logic resides in [`packages/agent-runtime/src/run-agent-step.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/run-agent-step.ts), which contains granular `logger.debug` statements at critical junctures:

- **Iteration start** (lines 310-327): Logs the iteration number, model configuration, token counts, and the compiled prompt.
- **Compact-command handling** (lines 430-444): Emits debug entries when the `/compact` command truncates message history.
- **End-of-turn decision** (lines 470-485): Records why the agent decided to end the turn (e.g., `task_completed` tool called, no tool calls present, or think-only response).

These logs flow through the Pino pipeline and appear in `debug/web.jsonl` with full context attached.

## Analyzing Cache Snapshots

When debugging prompt-cache behavior, use the [`scripts/compare-cache-debug.ts`](https://github.com/CodebuffAI/codebuff/blob/main/scripts/compare-cache-debug.ts) utility. This script reads the cached request snapshots from `debug/cache-debug/` and prints a unified diff between successive prompts.

This is the definitive tool for locating why a prompt-cache miss occurred—whether due to a new tool being added, a timestamp in the system prompt, or message ordering changes.

To compare two snapshots:

```bash
bun scripts/compare-cache-debug.ts \
  debug/cache-debug/run-123-1.json \
  debug/cache-debug/run-123-2.json

```

## Debugging Tool Call Processing

Tool call parsing happens in [`packages/agent-runtime/src/tools/stream-parser.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/tools/stream-parser.ts) within the `processStream` function. This module emits `logger.debug` statements that surface:

- Raw tool call chunks from the LLM stream
- Parsing errors or malformed JSON
- Final `ToolMessage` construction

If an agent fails to execute a tool or appears to ignore a tool result, inspect the logs from this module to verify that the stream was parsed correctly.

## Environment-Level Debug Toggles

Additional granular control is available through environment flags defined in [`common/src/env.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/env.ts). The most relevant is `DEBUG_ANALYTICS` (line 23), which logs raw analytics payloads to the console before they are sent to the telemetry endpoint.

Other modules, such as [`packages/agent-runtime/src/system-prompt/truncate-file-tree.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/system-prompt/truncate-file-tree.ts), check a generic `DEBUG` flag to emit additional console output without affecting the structured production logs.

## Practical Debugging Workflow

Follow this sequence to diagnose issues in agent execution flow:

1. **Enable full cache logging** by setting `CACHE_DEBUG_FULL_LOGGING = true` in [`packages/agent-runtime/src/constants.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/constants.ts).

2. **Run the agent in debug mode**:
   ```bash
   bun dev -- --debug
   ```

   This forces `IS_DEV` mode, creating the `debug/` folder and enabling console output.

3. **Inspect iteration logs** to verify prompt composition:
   ```bash
   cat debug/web.jsonl | jq -c 'select(.level=="DEBUG")' | less
   ```

   Search for "Start agent" entries to confirm the correct prompt and tool set were assembled.

4. **Diff cache snapshots** if experiencing cache misses:
   ```bash
   bun scripts/compare-cache-debug.ts
   ```

   This reveals exactly which fields changed between iterations.

5. **Trace tool call flow** by grepping for `"toolCalls"` or `"toolResults"` in `debug/web.jsonl`. Check [`packages/agent-runtime/src/tools/stream-parser.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/tools/stream-parser.ts) debug statements for parsing errors.

6. **Use contextual logging** in custom agents:
   ```typescript
   const log = loggerWithContext({ runId, agentId });
   log.debug({ step: 1 }, 'Custom agent step started');
   ```

7. **Enable analytics debugging** by setting `DEBUG_ANALYTICS=true` in your environment to see raw telemetry payloads.

This workflow provides end-to-end visibility into prompt construction, token counting, LLM streaming, tool-call handling, and turn-ending logic.

## Summary

- **Enable `CACHE_DEBUG_FULL_LOGGING`** in [`packages/agent-runtime/src/constants.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/constants.ts) to capture complete LLM request snapshots for every iteration.
- **Use the Pino-based logger** in [`web/src/util/logger.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/util/logger.ts) with `loggerWithContext` to correlate logs across asynchronous agent steps using `runId` and `agentId`.
- **Inspect [`run-agent-step.ts`](https://github.com/CodebuffAI/codebuff/blob/main/run-agent-step.ts)** debug statements (lines 310-327, 430-444, 470-485) to verify iteration starts, compact commands, and turn-ending decisions.
- **Run [`compare-cache-debug.ts`](https://github.com/CodebuffAI/codebuff/blob/main/compare-cache-debug.ts)** to diff cached request snapshots and diagnose prompt-cache misses.
- **Check [`stream-parser.ts`](https://github.com/CodebuffAI/codebuff/blob/main/stream-parser.ts)** debug logs to trace tool call parsing and identify malformed LLM outputs.
- **Toggle environment flags** like `DEBUG_ANALYTICS` in [`common/src/env.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/env.ts) for additional console visibility without affecting production logs.

## Frequently Asked Questions

### How do I enable detailed logging for a specific agent run?

Set `CACHE_DEBUG_FULL_LOGGING` to `true` in [`packages/agent-runtime/src/constants.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/constants.ts) and run the agent with the `--debug` flag. This writes complete LLM request snapshots to `debug/cache-debug/` and streams structured logs to `debug/web.jsonl`. Use `loggerWithContext({ runId, agentId })` in your agent code to ensure every log entry is tagged with identifiers for easy filtering.

### Why is my prompt cache missing even though the prompt looks identical?

Prompt-cache misses usually occur due to non-obvious differences in the request payload. Use the [`scripts/compare-cache-debug.ts`](https://github.com/CodebuffAI/codebuff/blob/main/scripts/compare-cache-debug.ts) utility to diff successive snapshots from `debug/cache-debug/`. This script reveals exact changes in system prompts, tool definitions, or message ordering that invalidate the cache. Even minor changes like timestamps in metadata or different tool ordering can cause misses.

### How can I trace why a tool call failed to execute?

Tool call execution issues are typically logged in [`packages/agent-runtime/src/tools/stream-parser.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/tools/stream-parser.ts). Search your `debug/web.jsonl` for entries containing `"toolCalls"` or `"toolResults"` to see the raw LLM output and parsed results. The `processStream` function emits debug statements when it encounters malformed JSON or parsing errors. Additionally, check [`run-agent-step.ts`](https://github.com/CodebuffAI/codebuff/blob/main/run-agent-step.ts) (lines 430-444) to verify if the compact command or message truncation affected the tool call context.

### What is the difference between the logger and console output in development?

In development mode (`IS_DEV && !IS_CI`), the logger configured in [`web/src/util/logger.ts`](https://github.com/CodebuffAI/codebuff/blob/main/web/src/util/logger.ts) writes structured JSON lines to both `debug/web.jsonl` and the console. The file output preserves the full structured data for programmatic analysis with tools like `jq`, while the console output provides immediate visual feedback. Production mode only writes to rotating files or analytics endpoints, omitting console output entirely. Use `DEBUG_ANALYTICS` in [`common/src/env.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/env.ts) to see raw analytics payloads in the console without affecting the structured log stream.