ggcode.example.yaml

# ggcode.example.yaml
# Full configuration example for ggcode
# Copy to ~/.ggcode/ggcode.yaml, or pass it explicitly with --config ./ggcode.yaml

# Active vendor / endpoint / model
vendor: zai
endpoint: cn-coding-openai
model: glm-5-turbo

# Fallback provider - automatically switches when the primary fails
# with quota exhaustion, auth errors, or sustained transient failures.
# The fallback vendor/endpoint must be configured in the vendors section above.
# fallback:
#   enabled: true
#   vendor: anthropic
#   endpoint: default
#   model: claude-sonnet-4-20250514

# TUI language: en or zh-CN
language: en

# Output style controls agent response verbosity:
#   default   - standard balanced responses
#   concise   - terse, minimal output
#   detailed  - include reasoning and context
#   socratic  - guided learning with questions
# output_style: default

# Runtime mode: supervised, plan, auto, bypass, or autopilot
default_mode: supervised

# System prompt injected at the start of every conversation
# system_prompt: "You are a helpful coding assistant."

# Vendor-specific settings
vendors:
  zai:
    display_name: Z.ai
    api_key: ${ZAI_API_KEY}
    endpoints:
      cn-coding-openai:
        display_name: 国内 Coding Plan
        protocol: openai
        base_url: https://open.bigmodel.cn/api/coding/paas/v4
        default_model: glm-5-turbo
        selected_model: glm-5-turbo
        context_window: 200000
        max_tokens: 128000
        models: [glm-5, glm-5-turbo, glm-5.1, glm-4.7, glm-4.7-flashx, glm-4.6, glm-4.5-air]
        tags: [coding, cn]
      cn-coding-anthropic:
        display_name: 国内 Coding Plan (Anthropic)
        protocol: anthropic
        base_url: https://open.bigmodel.cn/api/anthropic
        default_model: glm-5-turbo
        selected_model: glm-5-turbo
        context_window: 200000
        max_tokens: 128000
        models: [glm-5, glm-5-turbo, glm-5.1, glm-4.7, glm-4.7-flashx, glm-4.6, glm-4.5-air]
        tags: [coding, cn, anthropic]
      global-coding-openai:
        display_name: 国外 Coding Plan
        protocol: openai
        base_url: https://api.z.ai/api/coding/paas/v4
        default_model: glm-5-turbo
        selected_model: glm-5-turbo
        context_window: 200000
        max_tokens: 128000
        models: [glm-5, glm-5-turbo, glm-5.1, glm-4.7, glm-4.7-flashx, glm-4.6, glm-4.5-air]
        tags: [coding, global]
      global-coding-anthropic:
        display_name: 国外 Coding Plan (Anthropic)
        protocol: anthropic
        base_url: https://api.z.ai/api/anthropic
        default_model: glm-5-turbo
        selected_model: glm-5-turbo
        context_window: 200000
        max_tokens: 128000
        models: [glm-5, glm-5-turbo, glm-5.1, glm-4.7, glm-4.7-flashx, glm-4.6, glm-4.5-air]
        tags: [coding, global, anthropic]
      global-api-openai:
        display_name: 国外普通 API
        protocol: openai
        base_url: https://api.z.ai/api/paas/v4
        default_model: glm-4.5-air
        selected_model: glm-4.5-air
        max_tokens: 8192
        models: [glm-5, glm-5-turbo, glm-5.1, glm-4.7, glm-4.7-flashx, glm-4.6, glm-4.5-air]
        tags: [api, global]
  anthropic:
    display_name: Anthropic
    api_key: ${ANTHROPIC_API_KEY}
    endpoints:
      api:
        display_name: Anthropic API
        protocol: anthropic
        base_url: https://api.anthropic.com
        default_model: claude-3-5-sonnet-latest
        selected_model: claude-3-5-sonnet-latest
        max_tokens: 8192
        models: [claude-3-5-sonnet-latest, claude-3-5-haiku-latest]
        tags: [official, anthropic]
  openai:
    display_name: OpenAI
    api_key: ${OPENAI_API_KEY}
    endpoints:
      api:
        display_name: OpenAI API
        protocol: openai
        base_url: https://api.openai.com/v1
        default_model: gpt-4o-mini
        selected_model: gpt-4o-mini
        max_tokens: 8192
        models: [gpt-4o-mini, gpt-4o]
        tags: [official, openai]
  google:
    display_name: Google Gemini
    api_key: ${GEMINI_API_KEY}
    endpoints:
      api:
        display_name: Gemini API
        protocol: gemini
        base_url: https://generativelanguage.googleapis.com
        default_model: gemini-1.5-flash
        selected_model: gemini-1.5-flash
        max_tokens: 8192
        models: [gemini-1.5-flash, gemini-1.5-pro]
        tags: [official, gemini]
  openrouter:
    display_name: OpenRouter
    api_key: ${OPENROUTER_API_KEY}
    endpoints:
      api:
        display_name: OpenRouter API
        protocol: openai
        base_url: https://openrouter.ai/api/v1
        default_model: openai/gpt-4o-mini
        selected_model: openai/gpt-4o-mini
        max_tokens: 8192
        models: [openai/gpt-4o-mini, anthropic/claude-3.5-sonnet, google/gemini-flash-1.5]
        tags: [router, openai-compatible]
  aihubmix:
    display_name: AIHubMix
    api_key: ${AIHUBMIX_API_KEY}
    endpoints:
      api:
        display_name: AIHubMix API
        protocol: openai
        base_url: https://aihubmix.com/v1
        default_model: gpt-4o-mini
        selected_model: gpt-4o-mini
        max_tokens: 8192
        models: [gpt-4o-mini]
        tags: [official, openai-compatible, router]
  getgoapi:
    display_name: GetGoAPI
    api_key: ${GETGOAPI_API_KEY}
    endpoints:
      api:
        display_name: GetGoAPI API
        protocol: openai
        base_url: https://api.getgoapi.com/v1
        default_model: gpt-4o-mini
        selected_model: gpt-4o-mini
        max_tokens: 8192
        models: [gpt-4o-mini]
        tags: [official, openai-compatible, router]
  groq:
    display_name: Groq
    api_key: ${GROQ_API_KEY}
    endpoints:
      api:
        display_name: Groq API
        protocol: openai
        base_url: https://api.groq.com/openai/v1
        default_model: llama-3.1-8b-instant
        selected_model: llama-3.1-8b-instant
        max_tokens: 8192
        models: [llama-3.1-8b-instant, llama-3.1-70b-versatile]
        tags: [official, openai-compatible, fast]
  mistral:
    display_name: Mistral
    api_key: ${MISTRAL_API_KEY}
    endpoints:
      api:
        display_name: Mistral API
        protocol: openai
        base_url: https://api.mistral.ai/v1
        default_model: mistral-small-latest
        selected_model: mistral-small-latest
        max_tokens: 8192
        models: [mistral-small-latest, mistral-large-latest]
        tags: [official, openai-compatible]
  deepseek:
    display_name: DeepSeek
    api_key: ${DEEPSEEK_API_KEY}
    endpoints:
      api:
        display_name: DeepSeek API
        protocol: openai
        base_url: https://api.deepseek.com/v1
        default_model: deepseek-chat
        selected_model: deepseek-chat
        max_tokens: 8192
        models: [deepseek-chat, deepseek-reasoner]
        tags: [official, openai-compatible, reasoning]
  moonshot:
    display_name: Moonshot AI
    api_key: ${MOONSHOT_API_KEY}
    endpoints:
      api:
        display_name: Moonshot API
        protocol: openai
        base_url: https://api.moonshot.cn/v1
        default_model: moonshot-v1-8k
        selected_model: moonshot-v1-8k
        max_tokens: 8192
        models: [moonshot-v1-8k, moonshot-v1-32k]
        tags: [official, openai-compatible, cn]
  novita:
    display_name: Novita AI
    api_key: ${NOVITA_API_KEY}
    endpoints:
      api:
        display_name: Novita AI API
        protocol: openai
        base_url: https://api.novita.ai/openai/v1
        default_model: gpt-4o-mini
        selected_model: gpt-4o-mini
        max_tokens: 8192
        models: [gpt-4o-mini]
        tags: [official, openai-compatible, router]
  aliyun:
    display_name: Aliyun Bailian Coding Plan
    api_key: ${DASHSCOPE_API_KEY}
    endpoints:
      coding-openai:
        display_name: Aliyun Bailian Coding Plan
        protocol: openai
        base_url: https://coding.dashscope.aliyuncs.com/v1
        default_model: qwen3-coder-plus
        selected_model: qwen3-coder-plus
        max_tokens: 8192
        models: [qwen3-coder-plus]
        tags: [official, coding, cn, openai-compatible]
      coding-anthropic:
        display_name: Aliyun Bailian Coding Plan (Anthropic)
        protocol: anthropic
        base_url: https://coding.dashscope.aliyuncs.com/apps/anthropic
        default_model: qwen3-coder-plus
        selected_model: qwen3-coder-plus
        max_tokens: 8192
        models: [qwen3-coder-plus]
        tags: [official, coding, cn, anthropic]
  poe:
    display_name: Poe
    api_key: ${POE_API_KEY}
    endpoints:
      api:
        display_name: Poe API
        protocol: openai
        base_url: https://api.poe.com/v1
        default_model: gpt-4o-mini
        selected_model: gpt-4o-mini
        max_tokens: 8192
        models: [gpt-4o-mini]
        tags: [official, openai-compatible, router]
  requesty:
    display_name: Requesty
    api_key: ${REQUESTY_API_KEY}
    endpoints:
      api:
        display_name: Requesty API
        protocol: openai
        base_url: https://router.requesty.ai/v1
        default_model: gpt-4o-mini
        selected_model: gpt-4o-mini
        max_tokens: 8192
        models: [gpt-4o-mini]
        tags: [official, openai-compatible, router]
  vercel:
    display_name: Vercel AI Gateway
    api_key: ${VERCEL_AI_GATEWAY_API_KEY}
    endpoints:
      api:
        display_name: Vercel AI Gateway
        protocol: openai
        base_url: https://ai-gateway.vercel.sh/v1
        default_model: gpt-4o-mini
        selected_model: gpt-4o-mini
        max_tokens: 8192
        models: [gpt-4o-mini]
        tags: [official, openai-compatible, gateway]
  kimi:
    display_name: Kimi Coding Plan
    api_key: ${KIMI_API_KEY}
    endpoints:
      coding-openai:
        display_name: Kimi Coding Plan
        protocol: openai
        base_url: https://api.kimi.com/coding/v1
        default_model: kimi-for-coding
        selected_model: kimi-for-coding
        context_window: 262144
        max_tokens: 32768
        models: [kimi-for-coding]
        tags: [official, coding, openai-compatible]
      coding-anthropic:
        display_name: Kimi Coding Plan (Anthropic)
        protocol: anthropic
        base_url: https://api.kimi.com/coding/
        default_model: kimi-for-coding
        selected_model: kimi-for-coding
        context_window: 262144
        max_tokens: 32768
        models: [kimi-for-coding]
        tags: [official, coding, anthropic]
  minimax:
    display_name: MiniMax Token Plan
    api_key: ${MINIMAX_API_KEY}
    endpoints:
      token-plan-openai:
        display_name: MiniMax Token Plan
        protocol: openai
        base_url: https://api.minimaxi.com/v1
        default_model: MiniMax-M2.7
        selected_model: MiniMax-M2.7
        context_window: 204800
        max_tokens: 2048
        models: [MiniMax-M2.7]
        tags: [official, coding, openai-compatible]
      token-plan-anthropic:
        display_name: MiniMax Token Plan (Anthropic)
        protocol: anthropic
        base_url: https://api.minimaxi.com/anthropic
        default_model: MiniMax-M2.7
        selected_model: MiniMax-M2.7
        context_window: 204800
        max_tokens: 2048
        models: [MiniMax-M2.7]
        tags: [official, coding, anthropic]
      global-openai:
        display_name: MiniMax Global
        protocol: openai
        base_url: https://api.minimax.io/v1
        default_model: MiniMax-M2.7
        selected_model: MiniMax-M2.7
        context_window: 204800
        max_tokens: 2048
        models: [MiniMax-M2.7]
        tags: [official, coding, openai-compatible, global]
      global-anthropic:
        display_name: MiniMax Global (Anthropic)
        protocol: anthropic
        base_url: https://api.minimax.io/anthropic
        default_model: MiniMax-M2.7
        selected_model: MiniMax-M2.7
        context_window: 204800
        max_tokens: 2048
        models: [MiniMax-M2.7]
        tags: [official, coding, anthropic, global]
  ark:
    display_name: Volcengine Ark Coding Plan
    api_key: ${ARK_API_KEY}
    endpoints:
      coding-openai:
        display_name: Ark Coding Plan
        protocol: openai
        base_url: https://ark.cn-beijing.volces.com/api/coding/v3
        default_model: ark-code-latest
        selected_model: ark-code-latest
        context_window: 200000
        max_tokens: 8192
        models: [ark-code-latest]
        tags: [official, coding, cn, openai-compatible]
      coding-anthropic:
        display_name: Ark Coding Plan (Anthropic)
        protocol: anthropic
        base_url: https://ark.cn-beijing.volces.com/api/coding
        default_model: ark-code-latest
        selected_model: ark-code-latest
        context_window: 200000
        max_tokens: 8192
        models: [ark-code-latest]
        tags: [official, coding, cn, anthropic]
  together:
    display_name: Together AI
    api_key: ${TOGETHER_API_KEY}
    endpoints:
      api:
        display_name: Together API
        protocol: openai
        base_url: https://api.together.xyz/v1
        default_model: meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo
        selected_model: meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo
        max_tokens: 8192
        models:
          - meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo
          - meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo
        tags: [official, openai-compatible, open-models]
  perplexity:
    display_name: Perplexity
    api_key: ${PERPLEXITY_API_KEY}
    endpoints:
      api:
        display_name: Perplexity API
        protocol: openai
        base_url: https://api.perplexity.ai
        default_model: llama-3.1-sonar-small-128k-online
        selected_model: llama-3.1-sonar-small-128k-online
        max_tokens: 8192
        models:
          - llama-3.1-sonar-small-128k-online
          - llama-3.1-sonar-large-128k-online
        tags: [official, openai-compatible, search]

# Directories the agent is allowed to access (relative to config file or absolute)
allowed_dirs:
  - .

# Write-protection patterns: glob patterns that block write tools (write_file,
# edit_file, etc.) from modifying matching files, even within allowed_dirs.
# Defaults (if omitted): [".env", ".env.*", ".git/"]
# Setting this explicitly replaces the defaults.
# Supports: glob (".env*", "*.lock"), directory prefix (".git/"), and ** ("src/secrets/**")
# protected_paths:
#   - ".env"
#   - ".env.*"
#   - ".git/"
#   - "*.lock"
#   - "go.sum"

# OS-level containment for agent-driven shell commands (run_command /
# start_command). When enabled, spawned commands run inside a kernel sandbox
# (macOS Seatbelt via sandbox-exec). Writes are limited to the workspace,
# temp directories, and the extra roots below; on platforms without native
# sandboxing this is a no-op. This complements protected_paths: the policy
# decides WHAT is allowed, the kernel enforces it at the OS level.
# sandbox:
#   enabled: true
#   # Allow outbound network inside the sandbox (default: true).
#   allow_network: false
#   # Additional writable directories, e.g. for module builds:
#   extra_write_paths:
#     - "~/go/pkg/mod"
#     - "~/.cache/go-build"

# ------------------------------------------------------------------
# IM (Instant Messaging) integration
# Connect ggcode to chat platforms for remote coding via IM.
# Use /im in the TUI to manage bindings, or configure adapters here.
# ------------------------------------------------------------------
im:
  enabled: true

  # Streaming: deliver agent output to IM channels in real-time
  streaming:
    enabled: true
    transport: message          # "message" (edit updates) or "reaction" (emoji ticker)
    edit_interval_sec: 2.0      # seconds between edit updates
    buffer_threshold: 500       # characters before flushing

  # Output mode: controls how tool results are delivered to IM channels.
  # Can also be changed at runtime via IM panel (v/q/s keys) or daemon follow (v/q/s hotkeys).
  #   verbose  - every tool result sent individually (default)
  #   quiet    - aggregated tool summary at round end; errors sent immediately
  #   summary  - only final LLM response text + tool count summary
  output_mode: verbose

  # Speech-to-text for voice messages (optional)
  # stt:
  #   provider: openai
  #   base_url: https://api.openai.com/v1
  #   api_key: ${OPENAI_API_KEY}
  #   model: whisper-1
  #   # Path to a ggml-*.bin model for local whisper.cpp fallback STT.
  #   # Auto-detected from common locations when omitted; required only if
  #   # the local binary is whisper.cpp and no model is found automatically.
  #   local_model: /path/to/ggml-base.en-q5_1.bin

  adapters:
    # QQ - requires a running QQ bot gateway
    qq:
      enabled: true
      platform: qq
      transport: ws
      extra:
        app_id: "your-qq-app-id"
        token: "your-qq-bot-token"

    # Telegram - uses long-polling or webhook
    telegram:
      enabled: true
      platform: telegram
      transport: polling
      extra:
        bot_token: ${TELEGRAM_BOT_TOKEN}

    # Discord - uses Discord Gateway
    discord:
      enabled: true
      platform: discord
      extra:
        bot_token: ${DISCORD_BOT_TOKEN}

    # Feishu / Lark - uses Feishu SDK WebSocket long connection.
    #
    # Prerequisites in Feishu Developer Console (开发者后台):
    #   1. Under "Events & Callbacks" (事件与回调), ensure the connection mode
    #      is set to "Long Connection / WebSocket" (长连接).
    #   2. Under "Events & Callbacks" → "Callback Configuration" (回调配置),
    #      add the callback: card.action.trigger (卡片回传交互回调).
    #      NOTE: This is in "Callback Configuration" (回调配置), NOT in
    #      "Event Subscription" (事件订阅). The card callback and event
    #      subscription are separate sections.
    #      Without this step, card buttons will render but clicking them
    #      will produce error 200340 (card callback not configured).
    feishu:
      enabled: true
      platform: feishu
      extra:
        app_id: "your-feishu-app-id"
        app_secret: ${FEISHU_APP_SECRET}

    # DingTalk - uses DingTalk Stream mode
    dingtalk:
      enabled: true
      platform: dingtalk
      extra:
        client_id: "your-dingtalk-client-id"
        client_secret: ${DINGTALK_CLIENT_SECRET}

    # Slack - uses Slack Socket Mode
    slack:
      enabled: true
      platform: slack
      extra:
        bot_token: ${SLACK_BOT_TOKEN}
        app_token: ${SLACK_APP_TOKEN}

# Maximum agentic loop iterations per user turn (0 = unlimited)
max_iterations: 0

# Maximum total tokens (input + output) per agent run (0 = unlimited)
# Progressive warnings at 80% and 95%, hard stop at 100%.
# Sub-agent spend (spawn_agent / use_namedagent) counts toward this budget.
# session_token_budget: 0

# Per-run USD spend cap for metered models with known pricing (0 = unlimited).
# Same 80%/95%/100% ladder as the token budget, priced from the cost table
# (input/output/cache rates). Subscription/bundled/free or unknown-pricing
# models accumulate $0 - use session_token_budget for those instead.
# session_cost_limit_usd: 0

# Per-run wall-clock soft budget (e.g. 10m, 1h; 0 = unlimited). Unlike
# session_timeout (a hard deadline), this steers: convergence guidance at
# 80%, finalize pressure at 95%, wind-down at 100%.
# session_time_budget: 0

# Maximum total tool calls per agent run (0 = auto-derive from max_iterations)
# When auto-derived: max_iterations * 8 (or 500 for unlimited iterations).
# Warnings at 80% and 95%, hard stop at 100%.
# tool_call_budget: 0

# Post-loop verification and success-claim supervision. Both are OFF by
# default: the system prompt already requires the model to verify its own
# changes inside the loop (scoped to what changed), which current models
# do reliably. Enable these only for weaker models that claim success
# without testing.
# verify:
#   # Run build/test verification after the agent loop finishes editing.
#   auto_after_run: false
#   # Re-enable the success-claim heuristic detectors (premature success
#   # declarations, unverified/phantom verification claims). Their lexical
#   # intermediate-state matching is noise for models that verify in-loop.
#   claims_supervision: false

# Per-tool permission rules: ask (prompt user), allow (auto-approve), deny (block)
tool_permissions:
  read_file: allow
  multi_file_read: allow
  write_file: ask
  edit_file: ask
  multi_edit_file: ask
  multi_file_edit: ask
  list_directory: allow
  search_files: allow
  glob: allow
  run_command: ask
  git_status: allow
  git_diff: allow
  git_log: allow

# Knight - background auto-evolution agent
# Knight analyzes sessions, creates/validates skills, generates tests,
# and maintains project health during idle time.
# Enabled by default; set enabled: false to disable.
knight:
  # Knight is disabled by default. Enable with /knight on or set to true.
  enabled: false
  # Trust level: readonly (analyze only), staged (write, user approves), auto (auto-promote)
  # trust_level: staged
  # Daily token budget (default 5M tokens; set to 0 for unlimited)
  # daily_token_budget: 5000000
  # Idle delay before Knight starts tasks (default 300 seconds)
  # idle_delay_sec: 300
  # Quiet hours - no tasks or notifications during these ranges
  # quiet_hours:
  #   - "23:00-07:00"
  # Capabilities - which tasks Knight is allowed to perform
  # capabilities:
  #   - skill_creation
  #   - skill_validation
  #   - test_generation
  #   - regression_testing
  #   - doc_sync
  # Optional: use a different LLM for Knight tasks
  # vendor: openai
  # endpoint: gpt-4o
  # model: gpt-4o-mini

# MCP servers for extended tool sets
mcp_servers:
  - name: filesystem
    command: npx
    args:
      - -y
      - "@anthropic/mcp-filesystem"
      - /path/to/allowed/dir
    env:
      NODE_ENV: production

  - name: github
    command: npx
    args:
      - -y
      - "@anthropic/mcp-github"
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}

# Hooks: run shell commands or HTTP webhooks on agent lifecycle events.
#
# Events (5):
#   on_user_message  - before LLM call (sync, can block)
#   pre_tool_use     - before tool execution (sync, can block)
#   post_tool_use    - after tool execution (sync, can inject output)
#   on_agent_stop    - agent loop ends (async fire-and-forget)
#   on_stream_stop   - LLM stream completes (async fire-and-forget)
#
# Hook types:
#   command (default) - local shell command
#   http              - HTTP POST webhook
#
# Blocking semantics:
#   command: exit code 2 = block (stderr → agent as block reason)
#   http:    HTTP 403    = block (response body → agent as block reason)
#   Non-blocking events (post_tool_use, on_agent_stop, on_stream_stop) ignore block.
#
# Standardized payload (JSON):
#   Sent as POST body (http), GGCODE_HOOK_PAYLOAD env var + stdin (command).
#   See docs/guide/hooks.md for full schema.
#
# Match patterns (for tool events):
#   "write_file"              - exact tool name
#   "write_*"                 - glob
#   "write_file|edit_file"    - pipe (OR)
#   "run_command(git commit*)"- tool name + argument substring
#   "*"                       - match all (for non-tool events)
#
# Environment variables (all hooks):
#   GGCODE_HOOK_PAYLOAD  - full JSON payload (see docs/guide/hooks.md)
#   GGCODE_HOOK_EVENT    - event name
#   GGCODE_TOOL_NAME     - tool name (tool events only)
#   GGCODE_RAW_INPUT     - raw JSON tool arguments
#   GGCODE_TOOL_SUCCESS  - "true"/"false" (post_tool_use only)
#   GGCODE_TOOL_ERROR    - error message (post_tool_use only)
#   GGCODE_TOOL_RESULT   - tool output, 4KB max (post_tool_use only)
#   GGCODE_TOOL_DURATION - execution duration (post_tool_use only)
#
# Template variables (use ${VAR} in command string):
#   ${TOOL_NAME}, ${FILE_PATH}, ${WORKING_DIR}, ${RAW_INPUT}, ${EVENT}
#   ${TOOL_SUCCESS}, ${TOOL_ERROR}, ${TOOL_RESULT}, ${TOOL_DURATION}, ${PAYLOAD}
# Ambient file-watch triggers (fire-on-change, not on schedule):
# when a file matching any glob settles after a change, the prompt is
# enqueued on the session like a cron firing. {files} is replaced with
# the changed paths. Polling-based (2s detection window); globs use
# filepath.Glob semantics (no ** recursion - use directory-scoped
# patterns). Changes during the cooldown (default 10s) are dropped.
watch:
  - globs: ["internal/permission/*_test.go"]
    prompt: "Permission tests changed ({files}) - run `go test -tags goolm ./internal/permission/` and fix any failures."
    queue_if_busy: false   # skip if agent busy (default); true = queue
    cooldown_sec: 10       # min seconds between fires (default 10)

# Sleep-time compute (idle maintenance): when the session has been idle
# for after_min minutes, ggcode uses the window to pre-compact the
# context (if usage >= precompact_ratio) so the next message doesn't pay
# the compaction latency. Disabled unless enabled: true.
idle:
  enabled: false
  after_min: 10          # idle window before maintenance fires (default 10)
  precompact_ratio: 0.6  # only pre-compact when usage is at/above this (default 0.6)

hooks:
  # Before user message reaches the LLM - sync, can block.
  on_user_message:
    - match: "*"
      type: http
      url: "https://audit.example.com/message"
      secret: "my-hmac-key"  # HMAC-SHA256 signature in X-GGCode-Signature header

  # Before tool execution - sync, can block (exit 2 / HTTP 403).
  pre_tool_use:
    # Block destructive shell commands (command type)
    - match: "run_command(rm -rf *)"
      command: "echo 'Destructive command blocked' >&2; exit 2"

    # Security scan before write (http type)
    - match: "write_file"
      type: http
      url: "https://security.example.com/scan"
      timeout: "5s"

  # After tool execution - sync, can inject output.
  post_tool_use:
    # Auto-format Go files after writing
    - match: "write_file|edit_file"
      command: "gofmt -w ${FILE_PATH} 2>/dev/null; goimports -w ${FILE_PATH} 2>/dev/null"

    # Notify external service on any tool completion (http type)
    - match: "*"
      type: http
      url: "https://hooks.slack.com/services/..."

  # Agent loop ends - async fire-and-forget.
  on_agent_stop:
    - match: "*"
      type: http
      url: "https://ci.example.com/agent-done"

  # LLM stream completes - async fire-and-forget.
  on_stream_stop:
    - match: "*"
      command: "echo 'stream complete' >> /tmp/ggcode-streams.log"

# External tool plugins
plugins:
  - name: my-tools
    type: command
    commands:
      - name: deploy
        description: Deploy the application to staging
        execute: ./scripts/deploy.sh
        args: ["--env", "staging"]
      - name: lint_check
        description: Run custom linter
        execute: npm
        args: ["run", "lint"]

  # gRPC plugin - independent process, any language (Go, Python, Node.js, etc.)
  # Zero version coupling with the host. The plugin exposes tools via gRPC.
  # See docs/guide/grpc-plugins.md for the full development guide.
  #
  # - name: jira-tools
  #   type: grpc
  #   command: ["./bin/jira-plugin"]        # or ["python", "-m", "my_jira_plugin"]
  #   env:
  #     JIRA_URL: "https://company.atlassian.net"
  #     JIRA_TOKEN: "${JIRA_API_TOKEN}"     # ${VAR} syntax for env var expansion

# A2A protocol server - expose this ggcode instance as an A2A agent
# so other ggcode instances (or any A2A client) can discover and collaborate.
# Enabled by default on port 0 (auto-assign). Set disabled: true to opt out.
#
# a2a:
#   enabled: true
#   port: 0                    # 0 = auto-assign (recommended for multi-instance)
#   host: ""                   # defaults to 0.0.0.0 (always LAN accessible)
#                               # Loopback addresses (127.0.0.1, ::1, localhost) are
#                               # automatically overridden to 0.0.0.0 because mDNS
#                               # and LAN Chat require LAN reachability.
#   max_tasks: 5               # concurrent task limit
#   task_timeout: "5m"         # per-task timeout
#   interfaces: []             # mDNS advertise interfaces (default: auto-detect default route)
#                               # Example: ["en0"] to advertise on Wi-Fi only.
#                               # Useful on multi-NIC machines to avoid advertising
#                               # Docker bridge (172.17.0.1) or VPN tunnel IPs.
#   lan_discovery: true          # mDNS LAN discovery (default: true). Set false to disable.
#                               # When enabled, ggcode broadcasts its presence on the LAN
#                               # and discovers other instances automatically. This powers
#                               # the LAN Chat feature and A2A peer discovery.
#
#   # mDNS discovery is always on - no configuration needed.
#   # ggcode uses a built-in community key (ggcode-lan-a2a-v1) that lets
#   # any ggcode instance on the same network connect automatically.
#   # NOTE: the community key only works while NO custom api_key is set.
#   # Setting your own api_key disables community-key access entirely;
#   # all team members must then share the custom key (#986).
#
#   # Authentication - multiple schemes can be enabled simultaneously.
#   # Server advertises enabled schemes in the agent card; clients auto-negotiate.
#   # Host is always 0.0.0.0 (LAN accessible) since mDNS discovery is always on.
#   # Loopback addresses are overridden to 0.0.0.0 to ensure LAN Chat and peer
#   # discovery work correctly.
#   auth:
#     # --- API Key (simplest) ---
#     api_key: "my-secret-key"   # shared secret (supports ${ENV_VAR} expansion)
#
#     # --- Additional API Keys (multi-key support) ---
#     api_keys:                  # list of additional keys; any match authenticates
#       - "team-alpha-key"
#       - "team-beta-key"
#       - "${TEAM_GAMMA_KEY}"    # env var expansion supported
#
#     # --- OAuth2 + PKCE / Device Flow ---
#     # Use "provider" for built-in presets (github, google, auth0, azure)
#     # or "issuer_url" for any custom OIDC-compliant IdP.
#     oauth2:
#       provider: "github"              # built-in preset - zero config
#       # client_id: "my-app"           # override preset (optional)
#       # client_secret: "xxx"          # required for confidential clients
#       # flow: "pkce"                  # "pkce" (default) or "device"
#       # scopes: "read:org"            # custom scopes (preset provides defaults)
#       # issuer_url: "https://idp.example.com"  # custom IdP
#
#     # --- OpenID Connect (layer on OAuth2, adds ID token + userinfo) ---
#     # oidc:
#     #   provider: "google"
#     #   client_id: "xxx"
#     #   client_secret: "xxx"
#
#     # --- mTLS (mutual TLS - no tokens, strongest transport auth) ---
#     # mtls:
#     #   cert_file: ".ggcode/certs/server.pem"
#     #   key_file: ".ggcode/certs/server.key"
#     #   ca_file: ".ggcode/certs/ca.pem"
#
#   # Legacy top-level api_key still works (auth.api_key takes priority)
#   # api_key: "legacy-key"
#
# Instance-level override: place .ggcode/a2a.yaml in the workspace root.
# It merges into the global a2a config, allowing per-project auth settings.
#
# Token cache: OAuth2/OIDC tokens are cached per-client at
#   ~/.ggcode/oauth-tokens/{provider}-{clientID}.json
# with 0600 permissions. Cache is checked before prompting for re-auth.
# Same client_id = shared token (intentional). Different client_id = isolated.

# LSP (Language Server Protocol) server overrides.
# By default, ggcode auto-detects language servers from PATH and workspace files.
# Use this section to override the binary path or add custom arguments.
# The key is the language ID: go, rust, clang, lua, swift, terraform, yaml,
# json, dockerfile, shell, zig, java, typescript, python, csharp.
#
# lsp_servers:
#   go:
#     binary: /usr/local/bin/gopls  # override auto-detected path
#     args: ["-vv"]                 # additional CLI arguments
#   rust:
#     binary: ~/.cargo/bin/rust-analyzer
#   typescript:
#     binary: typescript-language-server
#     args: ["--stdio"]