config.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/hijera/foxxy-agent/main/docs/config.schema.json",
  "title": "FoxxyCode config.yaml",
  "description": "Configuration file for the FoxxyCode agent (default location: ~/.foxxycode/config.yaml). Reference: docs/config-reference.md. Any string value may reference environment variables with ${VAR_NAME}; ${FOXXYCODE_HOME} and ${CWD} are expanded by the loader.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "providers": {
      "type": "array",
      "title": "LLM providers",
      "description": "API credentials and transport selection for upstream LLM vendors. When api_key is empty, the runtime reads the NAME_API_KEY environment variable (NAME is the provider name in uppercase with hyphens mapped to underscores).",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "type"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Logical id used as the first segment of models[].model. ASCII letters, digits, hyphen, underscore; must start with a letter.",
            "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$"
          },
          "type": {
            "type": "string",
            "description": "Wire protocol for this provider. Use \"openai\" for configurable OpenAI-compatible endpoints, \"anthropic\" for Anthropic, \"neuraldeep\" for NeuralDeep's fixed endpoint, or \"codex\" for ChatGPT OAuth against the official Codex backend.",
            "enum": ["openai", "anthropic", "neuraldeep", "codex"]
          },
          "api_base": {
            "type": "string",
            "description": "Optional base URL override. For type \"openai\" include /v1; for type \"anthropic\" use an Anthropic-compatible gateway. Ignored for type \"neuraldeep\" and type \"codex\", which use fixed official endpoints."
          },
          "api_key": {
            "type": "string",
            "description": "Provider secret. A literal key, a \"${ENV}\" reference expanded at load time, or empty to read NAME_API_KEY at LLM call time. Resolution order: api_key -> api_key_command stdout -> NAME_API_KEY."
          },
          "api_key_command": {
            "type": "string",
            "description": "Optional credential-helper command. When api_key is empty it runs via the detected host shell (pwsh, powershell, or cmd on Windows; bash or sh elsewhere) and the trimmed stdout is used as the key. On failure resolution falls back to NAME_API_KEY."
          },
          "proxy": {
            "type": "string",
            "description": "Optional per-provider outbound proxy URL: http://, https://, socks5://, or socks5h:// (socks5h resolves hostnames via the proxy). Overrides a proxy inherited from the environment (HTTP_PROXY/HTTPS_PROXY, e.g. forwarded by the IDE plugin); NO_PROXY is still honored and local addresses always connect directly. When empty, the environment proxy is used."
          }
        }
      }
    },
    "models": {
      "type": "array",
      "title": "Logical models",
      "description": "Named model entries the agent and UI can select.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["model"],
        "properties": {
          "model": {
            "type": "string",
            "description": "\"provider_name/api_model_id\": the first path segment must match a providers[].name; the remainder is sent to the LLM API (may itself contain slashes).",
            "pattern": "^[^/]+/.+$"
          },
          "max_tokens": {
            "type": "integer",
            "description": "Upper bound on completion tokens per assistant message. Ignored by Codex because its backend does not accept max_output_tokens."
          },
          "temperature": {
            "type": "number",
            "description": "Sampling temperature (0 = deterministic; higher = more random)."
          },
          "max_context_tokens": {
            "type": "integer",
            "description": "Optional UI hint for the composer context bar; 0 derives it from provider metadata when available.",
            "default": 0
          },
          "multimodal": {
            "type": "boolean",
            "description": "Model accepts image/file inputs in addition to text; the UI shows a file attachment button for this model.",
            "default": false
          },
          "reasoning_levels": {
            "type": "array",
            "description": "Override the reasoning levels offered for this model. Omit to auto-detect from the model id (gpt-5* -> minimal,low,medium,high; o-series and Claude thinking models -> low,medium,high). An explicit empty list hides the selector.",
            "items": { "type": "string" }
          },
          "reasoning_default": {
            "type": "string",
            "description": "Reasoning level pre-selected for new chats; must be one of the resolved levels, otherwise ignored."
          }
        }
      }
    },
    "agent": {
      "type": "object",
      "title": "ReAct agent loop",
      "description": "Defaults for the main agent loop (model id and safety caps).",
      "additionalProperties": false,
      "properties": {
        "model": {
          "type": "string",
          "description": "Default models[].model id used until the client overrides the model per session. Required when models is non-empty."
        },
        "max_turns": {
          "type": "integer",
          "description": "Hard cap on LLM calls per prompt turn.",
          "default": 30,
          "minimum": 0
        },
        "max_tokens_per_turn": {
          "type": "integer",
          "description": "Max tokens across all LLM calls in one turn.",
          "default": 200000,
          "minimum": 0
        },
        "llm_retry_max": {
          "type": "integer",
          "description": "Retries after retryable LLM errors such as HTTP 429.",
          "default": 3,
          "minimum": 0
        },
        "llm_retry_base_ms": {
          "type": "integer",
          "description": "Initial backoff between LLM retries, in milliseconds.",
          "default": 1000,
          "minimum": 0
        },
        "llm_min_interval_ms": {
          "type": "integer",
          "description": "Minimum gap between consecutive LLM calls in milliseconds (0 disables pacing; e.g. 12000 on strict free tiers).",
          "default": 0,
          "minimum": 0
        },
        "loop_guard": {
          "type": "boolean",
          "description": "Runaway-loop protection: cut a streamed response that degenerates into repeating itself, and block a tool called over and over with identical arguments.",
          "default": true
        },
        "loop_tool_repeat_limit": {
          "type": "integer",
          "description": "Consecutive identical tool calls (same name, same canonical arguments) before the loop guard steps in. 0 disables the tool-repeat check.",
          "default": 3,
          "minimum": 0
        },
        "loop_stream_repeat_cycles": {
          "type": "integer",
          "description": "Identical back-to-back output cycles inside one streamed response before the stream is cut. 0 disables the stream check.",
          "default": 5,
          "minimum": 0
        },
        "loop_nudge_max": {
          "type": "integer",
          "description": "How many times one turn may be nudged back on track before the loop guard stops it with a notice.",
          "default": 2,
          "minimum": 0
        }
      }
    },
    "prompts": {
      "type": "object",
      "title": "System prompt templates",
      "description": "Override the built-in system prompt templates (Go text/template).",
      "additionalProperties": false,
      "properties": {
        "dir": {
          "type": "string",
          "description": "Directory containing prompt template files. Empty uses embedded defaults. Supports ~ and ${CWD} (session cwd at render time).",
          "default": ""
        },
        "agent_prompt": {
          "type": "string",
          "description": "File name inside prompts.dir for agent mode.",
          "default": "agent.md"
        },
        "plan_prompt": {
          "type": "string",
          "description": "File name inside prompts.dir for plan mode.",
          "default": "plan.md"
        },
        "docs_prompt": {
          "type": "string",
          "description": "File name inside prompts.dir for docs mode.",
          "default": "docs.md"
        },
        "per_provider": {
          "type": "object",
          "title": "Per-provider prompts",
          "description": "Select a system prompt tuned to the active model family (agent.<family>.md), falling back to the shared prompt.",
          "additionalProperties": false,
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Use a per-family prompt file when one exists. Defaults to true.",
              "default": true
            }
          }
        }
      }
    },
    "instructions": {
      "type": "object",
      "title": "Project instructions",
      "description": "Files read from the session working directory and appended to the system prompt (AGENTS.md convention).",
      "additionalProperties": false,
      "properties": {
        "files": {
          "type": "array",
          "description": "Filenames relative to the session CWD.",
          "default": ["AGENTS.md"],
          "items": { "type": "string" }
        }
      }
    },
    "skills": {
      "type": "object",
      "title": "Skills",
      "description": "Directories scanned for skills (SKILL.md and root .md/.mdc files).",
      "additionalProperties": false,
      "properties": {
        "dirs": {
          "type": "array",
          "description": "Search paths; later entries win on name conflicts. Defaults (lowest to highest priority): ~/.agents/skills, ${FOXXYCODE_HOME}/skills, ${CWD}/.foxxycode/skills. ${FOXXYCODE_HOME} and ${CWD} expand at runtime.",
          "default": ["~/.agents/skills", "${FOXXYCODE_HOME}/skills", "${CWD}/.foxxycode/skills"],
          "items": { "type": "string" }
        },
        "sources": {
          "type": "array",
          "description": "Remote skill sources to install from: GitHub owner/repo[@ref], a git URL, or an http(s) URL to an agents-standard marketplace.json. Fetched on demand via Sync (never automatically) into the managed skills dir.",
          "items": { "type": "string" }
        },
        "auto_discovery": {
          "type": "boolean",
          "description": "Offer the model-driven load_skill tool so the agent can pull a catalogued skill's instructions into a turn on its own. Unset defaults to true.",
          "default": true
        }
      }
    },
    "rules": {
      "type": "object",
      "title": "Project rules",
      "description": "Discovery of rule files from .foxxycode/rules, .cursor/rules, .claude/rules, .codex/rules, and nested **/AGENTS.md under the session CWD. See docs/rules.md.",
      "additionalProperties": false,
      "properties": {
        "auto_discover": {
          "type": "boolean",
          "description": "Scan the session CWD rule roots automatically.",
          "default": true
        },
        "systems": {
          "type": "array",
          "description": "Restrict which rule systems are loaded: foxxycode, cursor, claude, codex, agents. Empty means all.",
          "default": [],
          "items": { "type": "string" }
        }
      }
    },
    "mcp_servers": {
      "type": "array",
      "title": "MCP servers",
      "description": "Model Context Protocol servers connected for every new session.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name"],
        "properties": {
          "type": {
            "type": "string",
            "description": "Transport. \"stdio\" (default when empty; url-only entries default to \"http\") runs a local command; \"http\" speaks streamable HTTP to url (with automatic legacy-SSE fallback); \"sse\" forces the legacy HTTP+SSE transport.",
            "enum": [
              "stdio",
              "http",
              "sse"
            ]
          },
          "name": {
            "type": "string",
            "description": "Stable id referenced by the agent; must be unique in this list."
          },
          "command": {
            "type": "string",
            "description": "Executable for stdio transport (leave empty when using an http url)."
          },
          "args": {
            "type": "array",
            "description": "Argv passed after command for stdio servers. ${CWD} expands to the session cwd.",
            "items": { "type": "string" }
          },
          "env": {
            "type": "array",
            "description": "Extra environment variables for the stdio child process.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["name", "value"],
              "properties": {
                "name": { "type": "string", "description": "Environment variable name." },
                "value": { "type": "string", "description": "Environment variable value. ${CWD} expands to the session cwd." }
              }
            }
          },
          "url": {
            "type": "string",
            "description": "HTTP(S) endpoint when type is \"http\"."
          },
          "headers": {
            "type": "array",
            "description": "Optional headers sent with MCP HTTP requests.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["name", "value"],
              "properties": {
                "name": { "type": "string", "description": "HTTP header name." },
                "value": { "type": "string", "description": "HTTP header value." }
              }
            }
          },
          "disabled": {
            "type": "boolean",
            "description": "Skip connecting this server without removing its definition."
          },
          "disabled_tools": {
            "type": "array",
            "description": "Tool names of this server hidden from the agent.",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "mcp": {
      "type": "object",
      "title": "MCP discovery",
      "description": "MCP settings that are not tied to a single server entry.",
      "additionalProperties": false,
      "properties": {
        "project_trust": {
          "type": "string",
          "description": "Trust policy for the project-local <cwd>/.foxxycode/mcp.json, which travels with the checkout: \"ask\" keeps its servers cold until the operator approves that exact declaration for that workspace; \"allow\" starts them automatically (trusted workspaces only); \"deny\" never loads them.",
          "default": "ask",
          "enum": [
            "ask",
            "allow",
            "deny"
          ]
        }
      }
    },
    "tools": {
      "type": "object",
      "title": "Tools and permissions",
      "description": "Filesystem and shell policy for built-in tools.",
      "additionalProperties": false,
      "properties": {
        "permission_mode": {
          "type": "string",
          "description": "When the agent asks for user approval: \"ask\" prompts for commands and file writes; \"accept_edits\" auto-approves writes but prompts for commands; \"bypass\" never asks (trusted environments only).",
          "default": "ask",
          "enum": ["ask", "accept_edits", "bypass"]
        },
        "command_allowlist": {
          "type": "array",
          "description": "Commands that never require permission. Exact or prefix match (prefix + space + any args). \"*\" allows all commands.",
          "items": { "type": "string" }
        },
        "ssh_connect_timeout": {
          "type": "integer",
          "description": "TCP dial timeout for SSH connections (ssh_run_command tool), in seconds.",
          "default": 30
        },
        "plan_no_self_run": {
          "type": "boolean",
          "description": "Forbid the model from starting to execute a plan on its own: in plan mode plan_exit is not offered and any tool outside the plan allowlist is refused instead of run. Only the user can start the implementation (Run plan). Editor plugins pass --plan-no-self-run to turn it on by default.",
          "default": false
        },
        "ask_disable_extended_tools": {
          "type": "boolean",
          "description": "When true, Ask mode hides read-only shell commands, web research, read-only MCP tools, and scheduler inspection tools, leaving only the basic repository-reading surface. Defaults to false.",
          "default": false
        },
        "output_limits": {
          "type": "object",
          "title": "Tool output limits",
          "description": "Maximum lines each tool result or error may return into the LLM context. Positive limits also apply a 64 KiB byte ceiling. 0 disables both limits; unset uses the built-in default.",
          "additionalProperties": false,
          "properties": {
            "read": { "type": "integer", "default": 1000, "minimum": 0 },
            "grep": { "type": "integer", "default": 200, "minimum": 0 },
            "glob": { "type": "integer", "default": 300, "minimum": 0 },
            "print_tree": { "type": "integer", "default": 400, "minimum": 0 },
            "run_command": { "type": "integer", "default": 500, "minimum": 0 },
            "ssh_run_command": { "type": "integer", "default": 500, "minimum": 0 },
            "webfetch": { "type": "integer", "default": 800, "minimum": 0 },
            "websearch": { "type": "integer", "default": 200, "minimum": 0 },
            "default": { "type": "integer", "default": 1000, "minimum": 0 }
          }
        },
        "background": {
          "type": "object",
          "title": "Background tasks",
          "description": "Commands the agent runs detached in the session task pool instead of blocking a turn. The pool dies with the foxxycode process; each task's metadata and captured output stay in the session bundle, and a task interrupted by a restart is reported as orphaned.",
          "additionalProperties": false,
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Offer the background option on run_command and expose the background task tools.",
              "default": true
            },
            "max_concurrent": {
              "type": "integer",
              "description": "How many background tasks one session may run at once. 0 uses the default.",
              "default": 5
            },
            "default_timeout_seconds": {
              "type": "integer",
              "description": "Hard limit for a task started without an explicit timeout and without a duration estimate. 0 uses the default.",
              "default": 900
            },
            "max_timeout_seconds": {
              "type": "integer",
              "description": "Ceiling applied to any requested or estimate-derived timeout. 0 uses the default.",
              "default": 3600
            },
            "output_buffer_bytes": {
              "type": "integer",
              "description": "How much of each task's output stays in memory for the status ticker. The full log is still written to the session bundle. 0 uses the default.",
              "default": 262144
            }
          }
        }
      }
    },
    "logger": {
      "type": "object",
      "title": "Logging",
      "description": "Process log level, outputs, format, and file rotation.",
      "additionalProperties": false,
      "properties": {
        "level": {
          "type": "string",
          "description": "Minimum severity written to the configured outputs (\"warning\" is accepted as an alias of \"warn\").",
          "default": "info",
          "enum": ["debug", "info", "warn", "warning", "error"]
        },
        "outputs": {
          "type": "array",
          "description": "Where log records go; any combination of stdout, stderr, file. Empty means stderr only.",
          "default": ["stderr"],
          "items": {
            "type": "string",
            "enum": ["stdout", "stderr", "file"]
          }
        },
        "file": {
          "type": "string",
          "description": "Path for the file sink; required when outputs includes \"file\". Supports ${FOXXYCODE_HOME}."
        },
        "format": {
          "type": "string",
          "description": "Log record format.",
          "default": "text",
          "enum": ["text", "json"]
        },
        "rotation": {
          "type": "object",
          "description": "Size-based rotation for the file sink.",
          "additionalProperties": false,
          "properties": {
            "max_size_mb": {
              "type": "integer",
              "description": "Rotate after the file reaches this size in MB; 0 disables size-based rotation.",
              "default": 0,
              "minimum": 0
            },
            "max_files": {
              "type": "integer",
              "description": "Rotated backups to keep when max_size_mb > 0.",
              "default": 0,
              "minimum": 0
            }
          }
        }
      }
    },
    "sessions": {
      "type": "object",
      "title": "Session storage",
      "description": "Where persisted session bundles are stored.",
      "additionalProperties": false,
      "properties": {
        "dir": {
          "type": "string",
          "description": "Sessions root directory. Empty resolves to ${FOXXYCODE_HOME}/sessions. Supports ${FOXXYCODE_HOME} and ~.",
          "default": ""
        }
      }
    },
    "memory": {
      "type": "object",
      "title": "Long-term memory copilot",
      "description": "Optional memory copilot (implementation in external/memory; enable at runtime with memory.enabled).",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Turn on the memory copilot.",
          "default": false
        },
        "model": {
          "type": "string",
          "description": "Exact models[].model id used only for recall/persist LLM calls; empty falls back to agent.model or the session override.",
          "default": ""
        },
        "dir": {
          "type": "string",
          "description": "Long-term memory root. Empty resolves to ${FOXXYCODE_HOME}/memory. Supports ${FOXXYCODE_HOME} and ~.",
          "default": ""
        },
        "recall_max_turns": {
          "type": "integer",
          "description": "Bounds recall-side LLM rounds in the memory loop.",
          "default": 6
        },
        "persist_max_turns": {
          "type": "integer",
          "description": "Bounds persist-side LLM rounds in the memory loop.",
          "default": 12
        },
        "copilot_max_tokens": {
          "type": "integer",
          "description": "Completion token cap for memory copilot LLM calls.",
          "default": 4096
        },
        "max_search_hits": {
          "type": "integer",
          "description": "Maximum snippets returned by memory_search.",
          "default": 8
        }
      }
    },
    "compaction": {
      "type": "object",
      "title": "Automatic context compaction",
      "description": "Summarize older turns when the conversation approaches the model's context window.",
      "additionalProperties": false,
      "properties": {
        "engine": {
          "type": "string",
          "description": "Compaction implementation: \"coddy\" (default) keeps a summary row and replays only the window after it (supports /compact); \"opencode\" flags older turns and filters them from the payload.",
          "enum": ["coddy", "opencode"],
          "default": "coddy"
        },
        "enabled": {
          "type": "boolean",
          "description": "Turn on auto-compaction. Unset defaults to true; set false to disable.",
          "default": true
        },
        "model": {
          "type": "string",
          "description": "Exact models[].model id used for the summarization pass; empty falls back to agent.model.",
          "default": ""
        },
        "threshold_percent": {
          "type": "integer",
          "description": "Trigger when context usage exceeds this percent of the model context window. Default 80 (coddy) / 85 (opencode); the opencode engine clamps to 50..99.",
          "default": 80
        },
        "keep_recent_turns": {
          "type": "integer",
          "description": "Number of most recent user turns preserved verbatim (never summarized). Default 2.",
          "default": 2
        },
        "max_tokens": {
          "type": "integer",
          "description": "Completion token cap for the summary generation (opencode engine only).",
          "default": 4096
        },
        "result_eviction": {
          "type": "object",
          "title": "Read/grep result eviction",
          "description": "Collapses superseded read/grep results in the LLM projection while keeping the persisted transcript complete.",
          "additionalProperties": false,
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Master switch for result eviction.",
              "default": true
            },
            "keep_recent": {
              "type": "integer",
              "description": "Most recent evictable results kept as a working window.",
              "default": 2,
              "minimum": 0
            },
            "min_result_bytes": {
              "type": "integer",
              "description": "Results at or below this size are never evicted.",
              "default": 2000,
              "minimum": 0
            }
          }
        }
      }
    },
    "title": {
      "type": "object",
      "title": "Automatic session title generation",
      "description": "Generate a short LLM thread title after the first exchange in a fresh, non-pinned session. Runs backend-side for all clients.",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Turn on auto-title generation. Unset defaults to true; set false to disable.",
          "default": true
        },
        "model": {
          "type": "string",
          "description": "Exact models[].model id used for the title pass; empty falls back to agent.model. A small, cheap model is a good choice.",
          "default": ""
        },
        "max_tokens": {
          "type": "integer",
          "description": "Completion token cap for the title generation.",
          "default": 64
        }
      }
    },
    "httpserver": {
      "type": "object",
      "title": "HTTP gateway",
      "description": "OpenAI-compatible HTTP API defaults (used only by binaries built with -tags http; the embedded SPA needs -tags http,ui). See docs/http-api.md.",
      "additionalProperties": false,
      "properties": {
        "host": {
          "type": "string",
          "description": "Default bind address when foxxycode http does not pass -H/--host. Empty falls back to 0.0.0.0.",
          "default": ""
        },
        "port": {
          "type": "integer",
          "description": "Default listen port when foxxycode http does not pass -P/--port. 0 falls back to 12345.",
          "default": 0,
          "minimum": 0,
          "maximum": 65535
        },
        "auth_token": {
          "type": "string",
          "description": "Optional bearer credential for the HTTP API. Empty means no authentication. ${ENV} references are expanded at load; prefer --auth-token / FOXXYCODE_HTTP_TOKEN. Redacted from GET /foxxycode/config. See docs/remote-control.md.",
          "default": ""
        },
        "public_docs": {
          "type": "boolean",
          "description": "Keep /docs and /openapi.* reachable without a token even when auth is enabled.",
          "default": false
        },
        "allow_insecure": {
          "type": "boolean",
          "description": "Silence the startup warning about a non-loopback bind without authentication.",
          "default": false
        },
        "cors": {
          "type": "object",
          "description": "Cross-origin policy so a browser UI on another origin can call this API.",
          "additionalProperties": false,
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Turn on CORS handling (preflight + Access-Control-* headers).",
              "default": false
            },
            "allowed_origins": {
              "type": "array",
              "description": "Exact origins permitted to call the API. A single \"*\" allows any origin (bearer auth still applies).",
              "items": { "type": "string" }
            }
          }
        },
        "remotes": {
          "type": "array",
          "description": "Remote foxxycode http servers offered in the UI environment selector. Tokens are not stored here; the UI keeps them client-side per remote.",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "name": { "type": "string", "description": "Display name in the environment selector." },
              "url": { "type": "string", "description": "Base URL of the remote foxxycode http server." }
            }
          }
        }
      }
    },
    "scheduler": {
      "type": "object",
      "title": "Cron scheduler",
      "description": "Cron-driven scheduled jobs (used only by binaries built with -tags scheduler). Jobs are flat *.md files with YAML frontmatter under scheduler.dir; five-field crontab in UTC.",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Run the scheduler daemon and expose the foxxycode_scheduler_* tools. Can also be forced per process with foxxycode acp|http -scheduler-enabled.",
          "default": false
        },
        "dir": {
          "type": "string",
          "description": "Directory with *.md job definitions. Empty resolves to ${FOXXYCODE_HOME}/scheduler.",
          "default": ""
        },
        "max_queue": {
          "type": "integer",
          "description": "Concurrent scheduled runs; when saturated, extra firings are skipped until a slot frees.",
          "default": 10
        },
        "timeout": {
          "type": "string",
          "description": "Wall-clock limit for one scheduled agent run, as a Go duration (e.g. \"30m\", \"1h30m\").",
          "default": "30m"
        },
        "retain_sessions": {
          "type": "integer",
          "description": "Completed scheduler-run session directories kept per job_id under sessions.dir; older runs are pruned.",
          "default": 5
        }
      }
    },
    "gateways": {
      "type": "object",
      "title": "Messenger gateways",
      "description": "Messenger bot adapters (used only by binaries built with -tags gateway or -tags gateway.telegram; run with foxxycode gateway). See docs/gateway.md.",
      "additionalProperties": false,
      "properties": {
        "telegram": {
          "type": "object",
          "description": "Telegram bot adapter.",
          "additionalProperties": false,
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Activate the Telegram adapter when foxxycode gateway starts.",
              "default": false
            },
            "token": {
              "type": "string",
              "description": "Bot token from @BotFather. Leave empty to read the TELEGRAM_BOT_TOKEN environment variable (e.g. via ~/.foxxycode/.env).",
              "default": ""
            },
            "proxy": {
              "type": "string",
              "description": "Optional outbound proxy for Telegram API requests: http, https, socks5, or socks5h URL.",
              "default": ""
            },
            "rich_messages": {
              "type": "boolean",
              "description": "Use Bot API 10.1 Rich Messages (native Markdown, streamed thinking placeholder, collapsible tool list). Falls back to legacy formatting when unsupported.",
              "default": false
            },
            "admins": {
              "type": "array",
              "description": "Telegram user IDs with elevated rights; admins always pass access checks.",
              "items": { "type": "integer" }
            },
            "default_access": {
              "type": "string",
              "description": "Fallback access level for chats without an override: \"all\", \"admins\", or \"group:<name>\".",
              "default": "all"
            },
            "default_isolation": {
              "type": "string",
              "description": "Fallback session isolation for group chats: \"individual\" (session per user), \"shared\" (one session for all), \"admin\" (admins only, shared session).",
              "default": "individual",
              "enum": ["individual", "shared", "admin"]
            },
            "user_groups": {
              "type": "array",
              "description": "Named sets of user IDs referenced from access fields as group:<name>.",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "description": "Group name referenced as group:<name>." },
                  "user_ids": {
                    "type": "array",
                    "description": "Telegram numeric user IDs in this group.",
                    "items": { "type": "integer" }
                  }
                }
              }
            },
            "chats": {
              "type": "array",
              "description": "Per-chat overrides; chat_id is negative for groups and supergroups.",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": ["chat_id"],
                "properties": {
                  "chat_id": { "type": "integer", "description": "Telegram chat id (negative for groups/supergroups)." },
                  "isolation": {
                    "type": "string",
                    "description": "Per-chat session isolation override.",
                    "enum": ["individual", "shared", "admin"]
                  },
                  "access": {
                    "type": "string",
                    "description": "Per-chat access override: \"all\", \"admins\", or \"group:<name>\"."
                  }
                }
              }
            }
          }
        }
      }
    },
    "ui": {
      "type": "object",
      "title": "UI",
      "description": "Embedded SPA preferences for desktop and HTTP UI.",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Serve the embedded web UI at GET /. Turn off to run foxxycode http as an API-only server; /v1/* and /foxxycode/* stay available. Unset defaults to true.",
          "default": true
        },
        "locale": {
          "type": "string",
          "description": "UI locale for the embedded SPA. Empty means auto-detect from the system or browser locale.",
          "enum": ["", "en", "ru"],
          "default": ""
        },
        "send_mode": {
          "type": "string",
          "description": "How the main chat composer submits a message. \"enter\": Enter sends (Shift/Ctrl+Enter insert a newline). \"ctrl_enter\": Ctrl/Cmd+Enter sends (Enter inserts a newline). \"off\": disable keyboard send (Send button only).",
          "enum": ["enter", "ctrl_enter", "off"],
          "default": "enter"
        },
        "status_line": {
          "type": "boolean",
          "description": "Show a live status line next to the typing dots while the agent works: the current tool and its target, waiting for the model, and elapsed time. Set false to show only the animated dots. Unset defaults to true.",
          "default": true
        }
      }
    },
    "browser": {
      "type": "object",
      "title": "Browser tool",
      "description": "Interactive browser automation tool (requires the browser build tag; drives a local Chrome/Chromium via chromedp).",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Turns on the interactive browser tools (navigate, click, fill, screenshot, ...) for eligible builds.",
          "default": false
        },
        "headless": {
          "type": "boolean",
          "description": "Run the browser without a visible window. Enabled by default; disable to watch the automated session.",
          "default": true
        },
        "executable_path": {
          "type": "string",
          "description": "Optional path to a specific Chrome/Chromium binary. Empty lets chromedp auto-detect an installed browser.",
          "default": ""
        },
        "timeout_seconds": {
          "type": "integer",
          "description": "Per-action timeout for navigation, clicks, and other browser operations.",
          "default": 30
        }
      }
    },
    "vcs": {
      "type": "object",
      "title": "Version control",
      "description": "Version control integration. Git works out of the box; Subversion adds the SVN chip next to the git chip and the svn_* tools when a working copy is detected.",
      "additionalProperties": false,
      "properties": {
        "svn": {
          "type": "object",
          "title": "Subversion",
          "description": "Subversion support for SVN working copies and branch folders.",
          "additionalProperties": false,
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Turns Subversion support on. Enabled by default; turning it off hides the SVN chip and removes every svn_* tool from the model.",
              "default": true
            },
            "binary": {
              "type": "string",
              "description": "Optional path to the svn client. Empty resolves \"svn\" on PATH; set it when the client is installed outside PATH.",
              "default": ""
            },
            "timeout_seconds": {
              "type": "integer",
              "description": "Per-command timeout for svn invocations such as update, commit, and merge.",
              "default": 120
            },
            "branch_lookup": {
              "type": "boolean",
              "description": "Allows listing trunk and branches/ for the SVN chip menu. This contacts the server; turn it off on slow links.",
              "default": true
            }
          }
        }
      }
    }
  }
}