debug

The debug extension emits structured JSONL diagnostics to ~/.tallow/debug.log. Useful for inspecting tool performance, extension lifecycle, model changes, subagent activity, and errors.

Zero-cost when disabled — no file I/O, no object allocation.

Activation

Debug mode activates when any of these are true (checked once at session start):

Method	Example
--debug CLI flag	tallow --debug
TALLOW_DEBUG env var	TALLOW_DEBUG=1 tallow
Development mode	NODE_ENV=development or running via tsx

To stream to stderr instead of a file:

TALLOW_DEBUG=stderr tallow

Log format

Each line in the log is a self-contained JSON object:

{"ts":"2026-02-11T12:00:00.000Z","cat":"session","evt":"start","data":{"cwd":"/dev/project","sessionId":"abc","model":"anthropic/claude-sonnet-4"}}
{"ts":"2026-02-11T12:00:01.200Z","cat":"tool","evt":"call","data":{"toolCallId":"tc_1","name":"bash","args":{"command":"ls"}}}
{"ts":"2026-02-11T12:00:01.850Z","cat":"tool","evt":"result","data":{"toolCallId":"tc_1","name":"bash","durationMs":650,"ok":true,"contentLength":245}}

Categories

Category	Events logged
session	start, shutdown (with duration and totals), hooks_merge
tool	call (name, args), result (name, duration ms, success/failure, content length)
turn	start/end with turn index and tool result count
agent	before_start (prompt size, estimated tokens), end (message count)
model	select (provider, model ID, previous model, source)
subagent	start/stop (agent type, task, exit code)
error	uncaught_exception, unhandled_rejection (with full stack traces)

Sensitive-looking fields are automatically redacted before persistence.

• Key matching is case-insensitive and pattern-based (token, key, secret, authorization, cookie, password, etc.)
• Redaction is recursive for nested objects and arrays
• Redaction runs before string truncation to avoid partial secret leakage

String values longer than 500 characters are automatically truncated.

Commands

Manage debug mode from within a session:

Command	Description
/diagnostics	Show local tail; when wezterm_pane is available, choose local tail or live follow in a new pane
/diagnostics-on	Enable debug mode mid-session
/diagnostics-off	Disable debug mode mid-session
/diagnostics-clear	Truncate the log file
/diagnostics-tail [n]	Show last N log entries (default: 20)

Diagnostics vs debugger (/debug)

These are related, but not the same tool:

• Diagnostics (/diagnostics*) are the raw event stream (JSONL logs).
• Debugger (/debug) is model-assisted analysis on top of those logs.

Think of it like this:

• Diagnostics = the flight recorder (what happened, exactly when).
• /debug = the investigator (what pattern likely explains it).

Use diagnostics when you need concrete evidence:

• verify whether an event happened
• inspect exact timing and ordering
• tail live output while reproducing an issue

Use /debug when you need interpretation:

• summarize large logs quickly
• cluster recurring errors
• identify likely bottlenecks and next checks

Typical workflow: enable diagnostics, reproduce the issue, then run /debug for guided analysis.

Examples

Inspect tool performance

tallow --debug -p "Refactor the auth module"
# After the session:
cat ~/.tallow/debug.log | jq 'select(.cat == "tool" and .evt == "result")' | jq '{name: .data.name, ms: .data.durationMs}'

Watch live in another terminal

tail -f ~/.tallow/debug.log | jq .

Filter by category

cat ~/.tallow/debug.log | jq 'select(.cat == "error")'