debug

Documentation

Index

• Variables
• func Active() bool
• func Close()
• func EnableForTest(t interface{ ... }, categories ...string)
• func Init()
• func IsVerbose(pkg string) bool
• 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, sub-agents",
		Tags:        []string{"agent", "precompact", "subagent", "acp"},
	},
	{
		Name: "context", EnvSuffix: "CONTEXT",
		Description: "Context window management, summarize, microcompact",
		Tags:        []string{"ctx"},
	},

	{
		Name: "openai", EnvSuffix: "OPENAI",
		Description: "OpenAI provider — chat, streaming, message conversion",
		Tags:        []string{"openai", "openai-stream", "openai-chat", "openai-probe"},
	},
	{
		Name: "anthropic", EnvSuffix: "ANTHROPIC",
		Description: "Anthropic provider — chat, streaming, message conversion",
		Tags:        []string{"anthropic", "anthropic-stream", "anthropic-chat", "anthropic-probe"},
	},
	{
		Name: "gemini", EnvSuffix: "GEMINI",
		Description: "Gemini provider — chat, streaming, message conversion",
		Tags:        []string{"gemini", "gemini-stream", "gemini-chat", "gemini-probe"},
	},
	{
		Name: "provider", EnvSuffix: "PROVIDER",
		Description: "Provider registry, token estimation, adaptive cap, generic streaming",
		Tags:        []string{"provider", "adaptive_cap", "stream", "llm-classifier"},
	},
	{
		Name: "probe", EnvSuffix: "PROBE",
		Description: "Context window probing and cache",
		Tags:        []string{"probe"},
	},

	{
		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: "whatsapp", EnvSuffix: "WHATSAPP",
		Description: "WhatsApp IM adapter (whatsmeow)",
		Tags:        []string{"whatsapp"},
	},
	{
		Name: "matrix", EnvSuffix: "MATRIX",
		Description: "Matrix IM adapter",
		Tags:        []string{"matrix"},
	},
	{
		Name: "wechat", EnvSuffix: "WECHAT",
		Description: "WeChat (微信) IM adapter",
		Tags:        []string{"wechat"},
	},
	{
		Name: "wecom", EnvSuffix: "WECOM",
		Description: "WeCom (企业微信) IM adapter",
		Tags:        []string{"wecom"},
	},
	{
		Name: "signal", EnvSuffix: "SIGNAL",
		Description: "Signal IM adapter",
		Tags:        []string{"signal"},
	},
	{
		Name: "mattermost", EnvSuffix: "MATTERMOST",
		Description: "Mattermost IM adapter",
		Tags:        []string{"mattermost"},
	},
	{
		Name: "twitch", EnvSuffix: "TWITCH",
		Description: "Twitch IM adapter",
		Tags:        []string{"twitch"},
	},
	{
		Name: "nostr", EnvSuffix: "NOSTR",
		Description: "Nostr IM adapter",
		Tags:        []string{"nostr"},
	},
	{
		Name: "irc", EnvSuffix: "IRC",
		Description: "IRC IM adapter",
		Tags:        []string{"irc"},
	},
	{
		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: "tui", EnvSuffix: "TUI",
		Description: "TUI model updates, repl, completion, submit",
		Tags:        []string{"tui", "repl", "completion", "command-gate", "layout"},
	},
	{
		Name: "webui", EnvSuffix: "WEBUI",
		Description: "WebUI HTTP server, WebSocket chat, bridges",
		Tags:        []string{"webui", "tui-bridge"},
	},
	{
		Name: "daemon", EnvSuffix: "DAEMON",
		Description: "Daemon mode, daemon bridge, restart",
		Tags:        []string{"daemon", "daemon-bridge", "restart"},
	},

	{
		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: "harness", EnvSuffix: "HARNESS",
		Description: "Harness workflow engine, tasks, worktrees, review",
		Tags:        []string{"harness", "auto-run"},
	},
	{
		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, OAuth, mDNS, registry",
		Tags:        []string{"a2a", "a2a.oauth", "a2a.mdns", "a2a.registry"},
	},
	{
		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 IsVerbose

func IsVerbose(pkg string) bool

IsVerbose reports whether verbose (level 2) logging is enabled for the given category. Use this to gate high-volume trace logs:

if debug.IsVerbose("openai") { debug.Log("openai", ...) }

Enabled via GGCODE_DEBUG_OPENAI=2, GGCODE_DEBUG_OPENAI=verbose, or GGCODE_DEBUG_OPENAI=trace.

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>.