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 for precedence and merge rules.

Scan behavior

severity_threshold · 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

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

output_format · string · default: "terminal"

Default output format for codegate scan. Can be overridden at runtime with --format.

Allowed values: terminal, json, sarif, markdown, html

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

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

TUI

tui · object

Controls the interactive terminal UI rendered during codegate scan and codegate run.

Show tui properties

tui.enabled · boolean · default: "true"

Enable or disable the interactive TUI. When false, output is written as plain text. Can be overridden with --no-tui.

tui.colour_scheme · string · default: "default"

Colour scheme for the TUI. Currently only default is supported.

tui.compact_mode · boolean · default: "false"

When true, the TUI renders in a more compact layout with reduced spacing.

Tool discovery

tool_discovery · object

Controls which AI tools CodeGate discovers and uses for Layer 3 deep scan.

Show tool_discovery properties

tool_discovery.preferred_agent · string · default: "claude"

The AI tool to prefer for deep scan meta-agent analysis. Practical values: claude, claude-code, codex, codex-cli, opencode.

tool_discovery.agent_paths · object · default: "{}"

Map of agent key to binary path. Use this to point CodeGate to a non-standard install location for a tool.

{
  "tool_discovery": {
    "agent_paths": {
      "claude": "/usr/local/bin/claude"
    }
  }
}

tool_discovery.skip_tools · string[] · default: "[]"

Tool keys to exclude from discovery and selection during deep scan.

Trust and blocking

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

This key is global-only. Values in a project .codegate.json are ignored. This prevents a repository from promoting itself to a trusted path.

blocked_commands · string[]

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.

trusted_api_domains · string[] · default: "[]"

Domain names that are considered trusted for outbound API call checks. Findings involving these domains are not raised.

Known-safe allowlists

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

known_safe_formatters · string[]

Formatter names that are considered safe. Prefilled with common formatters:

• prettier, black, gofmt, rustfmt, clang-format

known_safe_lsp_servers · string[]

LSP server names that are considered safe. Prefilled with common servers:

• typescript-language-server, pyright, rust-analyzer, gopls

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

Analysis toggles

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

check_ide_settings · boolean · default: "true"

When false, IDE_SETTINGS findings are suppressed entirely.

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

Suppression and rule policy

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

suppression_rules · 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 for full field reference and examples.

rules · object

Per-rule policy configuration. Keys are rule IDs; values are policy objects with disable, ignore, and config fields.

See Suppression and rule policy for details.

Rule pack loading

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

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

skip_rules · string[] · default: "[]"

Rule IDs to drop after all rule packs are loaded. Applied after allowed_rules. Merged across global and project config.

Collection and persona (advanced)

scan_collection_modes · string[] · default: "[\"default\"]"

Default collection scope modes for scans. Allowed values: default, project, user, explicit, all. Can be overridden per run with --collect.

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

strict_collection · boolean · default: "false"

When true, parse failures in collected inputs are treated as high-severity findings instead of being silently skipped.

persona · string · default: "regular"

Audit sensitivity persona applied during scans. Allowed values: regular, pedantic, auditor. Can be overridden per run with --persona.

runtime_mode · string · default: "offline"

Runtime mode for optional online audits. Allowed values: offline, online, online-no-audits. Can be overridden per run with --runtime-mode.

workflow_audits · object

Controls the GitHub Actions workflow audit pack.

Show workflow_audits properties

workflow_audits.enabled · boolean · default: "false"

When true, workflow audit checks are enabled by default for all scans. Can also be enabled per run with --workflow-audits.