debug

Documentation

Index

• Variables
• func Active() bool
• func Close()
• func EnableForTest(t interface{ ... }, categories ...string)
• func Init()
• func Log(pkg, format string, args ...interface{})
• func Logf(format string, args ...interface{})
• type Category

Variables

var Categories = []Category{
	{
		Name: "agent", EnvSuffix: "AGENT",
		Description: "Agent loop, tool execution, autopilot, compaction",
		Tags:        []string{"agent", "precompact"},
	},
	{
		Name: "context", EnvSuffix: "CONTEXT",
		Description: "Context window management, summarize, microcompact",
		Tags:        []string{"ctx"},
	},
	{
		Name: "openai", EnvSuffix: "OPENAI",
		Description: "OpenAI provider streaming and message conversion",
		Tags:        []string{"openai"},
	},
	{
		Name: "anthropic", EnvSuffix: "ANTHROPIC",
		Description: "Anthropic provider streaming",
		Tags:        []string{"anthropic"},
	},
	{
		Name: "gemini", EnvSuffix: "GEMINI",
		Description: "Gemini provider",
		Tags:        []string{"gemini"},
	},
	{
		Name: "provider", EnvSuffix: "PROVIDER",
		Description: "Provider creation, token estimation, adaptive cap",
		Tags:        []string{"provider", "adaptive_cap"},
	},
	{
		Name: "qq", EnvSuffix: "QQ",
		Description: "QQ IM adapter",
		Tags:        []string{"qq"},
	},
	{
		Name: "tg", EnvSuffix: "TG",
		Description: "Telegram IM adapter",
		Tags:        []string{"tg"},
	},
	{
		Name: "discord", EnvSuffix: "DISCORD",
		Description: "Discord IM adapter",
		Tags:        []string{"discord"},
	},
	{
		Name: "slack", EnvSuffix: "SLACK",
		Description: "Slack IM adapter",
		Tags:        []string{"slack"},
	},
	{
		Name: "dingtalk", EnvSuffix: "DINGTALK",
		Description: "DingTalk IM adapter",
		Tags:        []string{"dingtalk"},
	},
	{
		Name: "feishu", EnvSuffix: "FEISHU",
		Description: "Feishu/Lark IM adapter",
		Tags:        []string{"feishu", "feishu-sdk"},
	},
	{
		Name: "pc", EnvSuffix: "PC",
		Description: "PC relay adapter and client",
		Tags:        []string{"pc", "pc_adapter", "pc_relay"},
	},
	{
		Name: "im", EnvSuffix: "IM",
		Description: "IM runtime, emitter, STT, dummy adapter",
		Tags:        []string{"im", "emitter", "stt", "dummy", "im-send"},
	},
	{
		Name: "knight", EnvSuffix: "KNIGHT",
		Description: "Knight scheduler, analyzer, runner",
		Tags:        []string{"knight"},
	},
	{
		Name: "swarm", EnvSuffix: "SWARM",
		Description: "Swarm multi-agent teammates and task board",
		Tags:        []string{"swarm"},
	},
	{
		Name: "tui", EnvSuffix: "TUI",
		Description: "TUI model updates, repl, completion, submit",
		Tags:        []string{"tui", "repl", "completion", "command-gate", "layout"},
	},
	{
		Name: "mcp", EnvSuffix: "MCP",
		Description: "MCP client, discovery, connect, HTTP, OAuth",
		Tags:        []string{"mcp", "mcp-oauth", "mcp-discover", "mcp-connect", "mcp-http"},
	},
	{
		Name: "plugin", EnvSuffix: "PLUGIN",
		Description: "Plugin and MCP loader",
		Tags:        []string{"plugin"},
	},
	{
		Name: "a2a", EnvSuffix: "A2A",
		Description: "Agent-to-agent server and handler",
		Tags:        []string{"a2a"},
	},
	{
		Name: "daemon", EnvSuffix: "DAEMON",
		Description: "Daemon mode checkpointing",
		Tags:        []string{"daemon"},
	},
	{
		Name: "config", EnvSuffix: "CONFIG",
		Description: "Config loading",
		Tags:        []string{"config"},
	},
	{
		Name: "permission", EnvSuffix: "PERMISSION",
		Description: "Permission policy decisions",
		Tags:        []string{"permission"},
	},
	{
		Name: "run-command", EnvSuffix: "RUN_COMMAND",
		Description: "Command execution (foreground/background)",
		Tags:        []string{"run_command"},
	},
	{
		Name: "safego", EnvSuffix: "SAFEGO",
		Description: "Goroutine panic recovery",
		Tags:        []string{"safego"},
	},
	{
		Name: "bubbletea", EnvSuffix: "BUBBLETEA",
		Description: "Bubble Tea framework internal trace (TEA_TRACE), controlled independently via GGCODE_DEBUG_BUBBLETEA",
		Tags:        []string{},
	},
}

Categories is the ordered list of all debug log categories. Order matters: listed first = checked first when building tag routing.

Functions

func Active

func Active() bool

Active reports whether the debug logger is enabled.

func Close

func Close()

Close flushes, closes, and removes all debug log files for the current process.

func EnableForTest

func EnableForTest(t interface{ Cleanup(func()) }, categories ...string)

EnableForTest forces the debug system on for the given categories. If categories is empty, all categories are enabled.

func Init

func Init()

Init initializes the debug logging system.

## Global control

GGCODE_DEBUG=1|true|all — enable ALL categories. GGCODE_DEBUG=<cat1>,<cat2> — enable only listed categories. GGCODE_DEBUG unset or empty — logging disabled (default).

## Per-category control (overrides global)

If any GGCODE_DEBUG_<SUFFIX> variable is set to a truthy value, that category is enabled regardless of the global GGCODE_DEBUG value. When per-category env vars exist, the global GGCODE_DEBUG is ignored entirely for the filter decision.

Examples:

GGCODE_DEBUG_AGENT=1         — only agent logs
GGCODE_DEBUG_OPENAI=1 GGCODE_DEBUG_AGENT=1 — openai + agent logs
GGCODE_DEBUG=1               — all logs (every category)
GGCODE_DEBUG=agent,provider  — agent + provider categories

## Category environment variable names

Each category has an EnvSuffix; the env var is GGCODE_DEBUG_<SUFFIX>. See the Categories variable for the full list.

func Log

func Log(pkg, format string, args ...interface{})

Log writes a formatted message with a package tag to the appropriate category-specific log file and the main log file. Format: [HH:MM:SS.mmm] [pkg] message

func Logf

func Logf(format string, args ...interface{})

Logf writes a raw formatted message (no package tag).

Types

type Category

type Category struct {
	Name        string   // e.g. "agent"
	EnvSuffix   string   // e.g. "AGENT" → GGCODE_DEBUG_AGENT=1
	Description string   // human-readable
	Tags        []string // debug.Log tags routed to this category
	// contains filtered or unexported fields
}

Category represents a debug log output channel. Each category maps to its own log file and can be independently enabled via GGCODE_DEBUG_<CATEGORY>.