> ## Documentation Index
> Fetch the complete documentation index at: https://jonathansantilli-codegate-92.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration reference

> Complete reference for every key in the CodeGate config file, with types, defaults, and behavioral notes.

All keys documented here are valid in both `~/.codegate/config.json` (global) and `<scan-target>/.codegate.json` (project override), unless noted otherwise. See [Configuration overview](/configuration/overview) for precedence and merge rules.

## Scan behavior

<ParamField body="severity_threshold" type="string" default="high">
  The minimum severity level at which a scan exits with code `2` (blocking). Findings at or above this level trigger blocking behavior in `codegate run`.

  Allowed values: `critical`, `high`, `medium`, `low`, `info`
</ParamField>

<ParamField body="auto_proceed_below_threshold" type="boolean" default="true">
  When `true`, `codegate run` proceeds to launch the selected tool without prompting if all findings are below `severity_threshold`. When `false`, any finding — even a non-blocking one — prompts for confirmation before launch.
</ParamField>

<ParamField body="output_format" type="string" default="terminal">
  Default output format for `codegate scan`. Can be overridden at runtime with `--format`.

  Allowed values: `terminal`, `json`, `sarif`, `markdown`, `html`
</ParamField>

<ParamField body="scan_state_path" type="string" default="~/.codegate/scan-state.json">
  Path to the file that stores MCP baseline state for rug-pull detection (`NEW_SERVER` and `CONFIG_CHANGE` findings). Paths beginning with `~` resolve to the current user's home directory.
</ParamField>

<ParamField body="scan_user_scope" type="boolean" default="true">
  When `true`, user-scope AI tool config paths (home directory tool configs) are included in Layer 1 discovery and Layer 3 resource discovery. Set to `false` to limit scans to the project directory only. Can be force-enabled per run with `--include-user-scope`.
</ParamField>

## TUI

<ParamField body="tui" type="object">
  Controls the interactive terminal UI rendered during `codegate scan` and `codegate run`.

  <Expandable title="tui properties">
    <ParamField body="tui.enabled" type="boolean" default="true">
      Enable or disable the interactive TUI. When `false`, output is written as plain text. Can be overridden with `--no-tui`.
    </ParamField>

    <ParamField body="tui.colour_scheme" type="string" default="default">
      Colour scheme for the TUI. Currently only `default` is supported.
    </ParamField>

    <ParamField body="tui.compact_mode" type="boolean" default="false">
      When `true`, the TUI renders in a more compact layout with reduced spacing.
    </ParamField>
  </Expandable>
</ParamField>

## Tool discovery

<ParamField body="tool_discovery" type="object">
  Controls which AI tools CodeGate discovers and uses for Layer 3 deep scan.

  <Expandable title="tool_discovery properties">
    <ParamField body="tool_discovery.preferred_agent" type="string" default="claude">
      The AI tool to prefer for deep scan meta-agent analysis. Practical values: `claude`, `claude-code`, `codex`, `codex-cli`, `opencode`.
    </ParamField>

    <ParamField body="tool_discovery.agent_paths" type="object" default="{}">
      Map of agent key to binary path. Use this to point CodeGate to a non-standard install location for a tool.

      ```json theme={null}
      {
        "tool_discovery": {
          "agent_paths": {
            "claude": "/usr/local/bin/claude"
          }
        }
      }
      ```
    </ParamField>

    <ParamField body="tool_discovery.skip_tools" type="string[]" default="[]">
      Tool keys to exclude from discovery and selection during deep scan.
    </ParamField>
  </Expandable>
</ParamField>

## Trust and blocking

<ParamField body="trusted_directories" type="string[]" default="[]">
  List of directory paths that are treated as trusted for `codegate run` confirmation purposes. When the current working directory is inside a configured trusted directory, warning-level launch confirmations are skipped.

  Paths are evaluated against resolved absolute paths.

  <Warning>
    This key is **global-only**. Values in a project `.codegate.json` are ignored. This prevents a repository from promoting itself to a trusted path.
  </Warning>
</ParamField>

<ParamField body="blocked_commands" type="string[]" default="[&#x22;bash&#x22;,&#x22;sh&#x22;,&#x22;curl&#x22;,&#x22;wget&#x22;,&#x22;nc&#x22;,&#x22;python&#x22;,&#x22;node&#x22;]">
  Command names that are flagged when found in MCP server `command` arrays or hooks. This list is merged with the built-in defaults; the defaults are always retained regardless of what you configure.
</ParamField>

<ParamField body="trusted_api_domains" type="string[]" default="[]">
  Domain names that are considered trusted for outbound API call checks. Findings involving these domains are not raised.
</ParamField>

## Known-safe allowlists

<ParamField body="known_safe_mcp_servers" type="string[]">
  Package or server identifiers that are considered safe and will not produce `NEW_SERVER` findings. Prefilled with a set of well-known servers:

  * `@anthropic/mcp-server-filesystem`
  * `@modelcontextprotocol/server-github`

  Entries from global and project configs are merged and de-duplicated with the defaults.
</ParamField>

<ParamField body="known_safe_formatters" type="string[]">
  Formatter names that are considered safe. Prefilled with common formatters:

  * `prettier`, `black`, `gofmt`, `rustfmt`, `clang-format`
</ParamField>

<ParamField body="known_safe_lsp_servers" type="string[]">
  LSP server names that are considered safe. Prefilled with common servers:

  * `typescript-language-server`, `pyright`, `rust-analyzer`, `gopls`
</ParamField>

<ParamField body="known_safe_hooks" type="string[]" default="[]">
  Relative hook file paths (relative to the repository root) that are considered safe and will not produce hook-related findings. Example: `.git/hooks/pre-commit`.
</ParamField>

## Analysis toggles

<ParamField body="unicode_analysis" type="boolean" default="true">
  When `true`, CodeGate checks for hidden or misleading Unicode characters in Layer 2 rule-file scanning and Layer 3 tool-description scanning.

  Setting this to `false` disables hidden-unicode findings only. All other rule-file heuristics remain enabled.
</ParamField>

<ParamField body="check_ide_settings" type="boolean" default="true">
  When `false`, `IDE_SETTINGS` findings are suppressed entirely.
</ParamField>

<ParamField body="owasp_mapping" type="boolean" default="true">
  When `false`, detection behavior is unchanged but `owasp` arrays in reports are emitted as empty arrays. Use this to reduce report noise if OWASP categorization is not relevant to your workflow.
</ParamField>

## Suppression and rule policy

<ParamField body="suppress_findings" type="string[]" default="[]">
  List of finding IDs or fingerprints to suppress. Matching findings are marked as suppressed and excluded from exit code calculation. Merged across global and project config.
</ParamField>

<ParamField body="suppression_rules" type="object[]" default="[]">
  Structured suppression rules. Each rule suppresses findings that match all specified criteria (AND semantics). Omitted criteria are ignored. Merged across global and project config.

  See [Suppression and rule policy](/configuration/suppression) for full field reference and examples.
</ParamField>

<ParamField body="rules" type="object">
  Per-rule policy configuration. Keys are rule IDs; values are policy objects with `disable`, `ignore`, and `config` fields.

  See [Suppression and rule policy](/configuration/suppression) for details.
</ParamField>

## Rule pack loading

<ParamField body="rule_pack_paths" type="string[]" default="[]">
  Paths to extra JSON rule pack files or directories of JSON rule packs to load in addition to the built-in rules. Merged across global and project config.
</ParamField>

<ParamField body="allowed_rules" type="string[]" default="[]">
  After all rule packs are loaded, only rule IDs in this list remain active. An empty list means all loaded rules are active. Merged across global and project config.
</ParamField>

<ParamField body="skip_rules" type="string[]" default="[]">
  Rule IDs to drop after all rule packs are loaded. Applied after `allowed_rules`. Merged across global and project config.
</ParamField>

## Collection and persona (advanced)

<ParamField body="scan_collection_modes" type="string[]" default="[&#x22;default&#x22;]">
  Default collection scope modes for scans. Allowed values: `default`, `project`, `user`, `explicit`, `all`. Can be overridden per run with `--collect`.
</ParamField>

<ParamField body="scan_collection_kinds" type="string[]">
  Restrict collection to specific artifact kinds. Allowed values: `workflows`, `actions`, `dependabot`. When unset, all kinds are collected. Can be overridden per run with `--collect-kind`.
</ParamField>

<ParamField body="strict_collection" type="boolean" default="false">
  When `true`, parse failures in collected inputs are treated as high-severity findings instead of being silently skipped.
</ParamField>

<ParamField body="persona" type="string" default="regular">
  Audit sensitivity persona applied during scans. Allowed values: `regular`, `pedantic`, `auditor`. Can be overridden per run with `--persona`.
</ParamField>

<ParamField body="runtime_mode" type="string" default="offline">
  Runtime mode for optional online audits. Allowed values: `offline`, `online`, `online-no-audits`. Can be overridden per run with `--runtime-mode`.
</ParamField>

<ParamField body="workflow_audits" type="object">
  Controls the GitHub Actions workflow audit pack.

  <Expandable title="workflow_audits properties">
    <ParamField body="workflow_audits.enabled" type="boolean" default="false">
      When `true`, workflow audit checks are enabled by default for all scans. Can also be enabled per run with `--workflow-audits`.
    </ParamField>
  </Expandable>
</ParamField>