Skip to main content
Use debug and trace logging when you need to understand what kg is doing internally. This is most useful when you are troubleshooting:
  • unexpected inheritance results
  • missing or duplicated config
  • agent generation that does not match what you expected
  • diff output that seems surprising

​
Debug mode

Enable debug output with -d or --debug: 
kg validate --debug
kg generate --debug
kg diff --debug
Debug mode is a good first step when you want higher-level visibility. It shows things like:
  • configuration file loading
  • agent resolution
  • basic merge operations

​
Trace mode

Enable detailed trace logging for a specific agent with -t or --trace: 
kg validate --trace rust
Trace mode is much more verbose. It is the right tool when you need the step-by-step story. Example trace output: 
TRACE main{dry_run=true}:discover{fs= location=[global,local]}:agent{name="rust"}: matching location
TRACE main{dry_run=true}:discover{fs= location=[global,local]}:agent{name="rust"}: found inline global and global file source
TRACE main{dry_run=true}:discover{fs= location=[global,local]}:agent{name="rust"}: merge start self_name=rust self_template=false other_name=rust other_template=false
TRACE main{dry_run=true}:discover{fs= location=[global,local]}:agent{name="rust"}: inherits: extended count=1
TRACE main{dry_run=true}:discover{fs= location=[global,local]}:agent{name="rust"}: subagents: merging
To trace everything: 
kg validate --trace all
That is usually overkill, but it can help when the problem is not isolated to one agent.

​
What trace output helps you see

Trace output is useful for:
  • configuration file loading
  • inheritance resolution
  • detailed merge operations
  • force-allow behavior
  • step-by-step agent construction

​
Common use cases

Debug inheritance issues: 
kg validate --trace rust
Debug generation: 
kg generate --trace rust
Debug diff behavior: 
kg diff --trace rust
Debug everything: 
kg validate --trace all

​
Output goes to stderr

Trace and debug output goes to stderr, so you can still pipe stdout: 
kg validate --debug --format json | jq '.agents'
That makes it easier to inspect machine-readable output without losing the logs.