> ## 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 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.

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

## Initial setup

<Steps>
  <Step title="Install CodeGate">
    ```bash theme={null}
    npm install -g codegate-ai
    ```
  </Step>

  <Step title="Create a global config with defaults">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Edit your config">
    Open `~/.codegate/config.json` and adjust values to suit your workflow. See [Configuration reference](/configuration/reference) for every available key.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

```json theme={null}
{
  "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": []
}
```

<Note>
  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.
</Note>