---
title: Debugging
description: How to debug an agentfootprint agent — typed events, narrative entries, time-travel checkpoints, and the agent playground viewer.
---

> An agent gives the wrong answer in production. **The first 30 seconds of debugging matter most** — was it the prompt? The tool result? A memory injection? A skill activation? agentfootprint exposes every one of those decisions as a typed event, recorded during the run, replayable later. You don't reconstruct what happened from logs; you read the trace.

## Three layers of debug surface

| Surface | When to use |
|---|---|
| **Typed event listeners** | Mid-run debugging in tests / dev — `agent.on('*', ...)` for every event, or `agent.on('agentfootprint.stream.*', ...)` per-domain |
| **Narrative recorder** | Post-run human-readable trace ("what happened, in order") |
| **Time-travel checkpoint** | Replay decisions cross-process, cross-day (Causal memory snapshot) |

## Live status — `enable.liveStatus`

For interactive debugging in terminal:

```ts
import { chatBubbleLiveStatus } from 'agentfootprint/strategies';

agent.enable.liveStatus({
  strategy: chatBubbleLiveStatus({ onLine: (s) => console.log(`⎈ ${s}`) }),
});
```

Prints one line per state transition — *"calling LLM... tool weather(SF)... LLM... done"*. The Claude-Code-style live status. Drop into your dev script.

## Structured logs — `enable.observability`

For CI / staging environments:

```ts
import { consoleObservability } from 'agentfootprint/strategies';

agent.enable.observability({
  strategy: consoleObservability(),  // or a vendor strategy: pino, OTel, CloudWatch, …
});
```

Pipes the typed event firehose to your structured logger.

## Targeted event subscription

For specific concerns:

```ts
agent.on('agentfootprint.context.injected', (e) => {
  // Every Skill / Steering / Instruction / Fact / Memory / RAG that activates
  console.log(`[ctx] ${e.payload.source} → ${e.payload.slot}`);
});

agent.on('agentfootprint.permission.halt', (e) => {
  console.log(`[BLOCKED] ${e.payload.target}: ${e.payload.reason}`);
});

agent.on('agentfootprint.cost.tick', (e) => {
  console.log(`[$] +${e.payload.estimatedUsd} (cum ${e.payload.cumulative.estimatedUsd})`);
});
```

59 typed events across 16 domains. Your IDE auto-completes payload shapes per event name. See [Observability guide](/agentfootprint/guides/observability/) for the full taxonomy.

## Cross-run replay — Causal memory

For "why did the agent make that decision two weeks ago?":

```ts
import { defineMemory, MEMORY_TYPES, MEMORY_STRATEGIES, SNAPSHOT_PROJECTIONS } from 'agentfootprint';

const causal = defineMemory({
  id: 'causal',
  type: MEMORY_TYPES.CAUSAL,
  strategy: { kind: MEMORY_STRATEGIES.TOP_K, topK: 1, threshold: 0.7, embedder },
  store,
  projection: SNAPSHOT_PROJECTIONS.DECISIONS,
});

agent.memory(causal);
```

Every run persists its decision evidence as a snapshot. Two weeks later, when the customer comes back asking why, the matching snapshot loads into the next prompt. The follow-up answer is grounded in the EXACT past facts — not reconstruction. See [Memory guide § Causal](/agentfootprint/guides/memory/#causal-memory--replay-decisions-not-just-messages).

## Agent playground (visual time-travel)

A deep-link from any recorded trace into the [agent playground](https://footprintjs.github.io/agent-playground/) for visual time-travel debugging is on the roadmap. Until then, the typed events + Causal memory are the textual equivalents.

## Anti-patterns

- Don't `console.log` inside tool `execute`. Subscribe to `agentfootprint.stream.tool_*` events instead — typed, filterable, sinkable.
- Don't try to reconstruct what happened from `JSON.stringify(agent)`. Use the typed event stream — the agent's internal state isn't a stable inspection surface.
- Don't enable EVERY event domain in production. Filter. Logs add up.

## Next steps

- [Observability guide](/agentfootprint/guides/observability/) — the full event taxonomy
- [Memory guide](/agentfootprint/guides/memory/) — Causal memory for cross-run debugging
- [Testing guide](/agentfootprint/guides/testing/) — mocks-first means most bugs surface in CI, not prod
