Configuration overview

Understand how CodeGate loads, merges, and applies configuration across global and project-level files.

CodeGate resolves configuration from up to three sources: built-in defaults, a global user config file, and an optional per-project override file. CLI flags can override scalar values at runtime.

Config file locations

Scope	Path
Global	~/.codegate/config.json
Project override	<scan-target>/.codegate.json

The global config applies to all scans. The project config applies only when that directory is the scan target.

trusted_directories can only be set in the global config. A project config cannot elevate its own directory to a trusted path.

Initial setup

1. Install CodeGate

   npm install -g codegate-ai
   
2. Create a global config with defaults

   codegate init
   

   This writes ~/.codegate/config.json populated with all default values, making it easy to review and tune your preferences.

   Available flags:

   Flag	Purpose
   --path <path>	Write the config file to a custom location instead of ~/.codegate/config.json
   --force	Overwrite an existing config file

   If you skip init, CodeGate still works using built-in defaults.

3. Edit your config

   Open ~/.codegate/config.json and adjust values to suit your workflow. See Configuration reference for every available key.

4. Optionally add a project override

   Place a .codegate.json file in the root of a project directory. Settings there apply only when that directory is the scan target and are merged with the global config according to the precedence rules below.

Precedence and merge rules

When resolving the effective configuration, CodeGate applies the following rules:

Scalar values (strings, booleans, numbers) follow a first-wins priority:

CLI override → project config → global config → built-in defaults

List values are merged and de-duplicated across all levels. Entries from the global config and project config are combined, with duplicates removed.

Special cases:

• trusted_directories — global-only. Project config values for this key are ignored.
• blocked_commands — merged with defaults. The default set (bash, sh, curl, wget, nc, python, node) is always retained even if the project or global config specifies additional commands.
• rule_pack_paths, allowed_rules, skip_rules, suppress_findings, and suppression_rules — merged across global and project config.

Default config

Running codegate init produces a file with the following content:

{
  "severity_threshold": "high",
  "auto_proceed_below_threshold": true,
  "output_format": "terminal",
  "scan_state_path": "~/.codegate/scan-state.json",
  "scan_user_scope": true,
  "tui": {
    "enabled": true,
    "colour_scheme": "default",
    "compact_mode": false
  },
  "tool_discovery": {
    "preferred_agent": "claude",
    "agent_paths": {},
    "skip_tools": []
  },
  "trusted_directories": [],
  "blocked_commands": ["bash", "sh", "curl", "wget", "nc", "python", "node"],
  "known_safe_mcp_servers": [
    "@anthropic/mcp-server-filesystem",
    "@modelcontextprotocol/server-github"
  ],
  "known_safe_formatters": ["prettier", "black", "gofmt", "rustfmt", "clang-format"],
  "known_safe_lsp_servers": ["typescript-language-server", "pyright", "rust-analyzer", "gopls"],
  "known_safe_hooks": [],
  "unicode_analysis": true,
  "check_ide_settings": true,
  "owasp_mapping": true,
  "trusted_api_domains": [],
  "suppress_findings": [],
  "suppression_rules": [],
  "rule_pack_paths": [],
  "allowed_rules": [],
  "skip_rules": []
}

The project config (.codegate.json) supports the same keys as the global config, except trusted_directories. You do not need to repeat all keys — only include the values you want to override or extend.