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

# run

> Scan the current directory first, then launch the selected AI coding tool if policy allows. Dangerous findings block launch.

`codegate run <tool>` is a scan-first wrapper that inspects the current directory before handing off to the AI tool. If findings at or above the configured severity threshold are detected, launch is blocked.

<Warning>
  If the scan returns exit code `2` (dangerous findings), `codegate run` will not launch the tool. You must resolve or suppress the findings and re-run. If config files change between the scan and the launch check, launch is also blocked and a rescan is required.
</Warning>

## Valid run targets

| Target     | Tool launched |
| ---------- | ------------- |
| `claude`   | Claude Code   |
| `opencode` | OpenCode      |
| `codex`    | Codex CLI     |
| `cursor`   | Cursor        |
| `windsurf` | Windsurf      |
| `kiro`     | Kiro          |

## Flags

<ParamField path="--no-tui" type="boolean" default="false">
  Disable the TUI dashboard and interactive prompts during the preflight scan.
</ParamField>

<ParamField path="--config" type="string">
  Path to a specific global config file. Overrides the default `~/.codegate/config.json` location.
</ParamField>

<ParamField path="--force" type="boolean" default="false">
  Skip the warning-level launch confirmation prompt. Has no effect on blocking-level findings — those always prevent launch regardless of `--force`.
</ParamField>

## Blocking behavior

`codegate run` evaluates scan results through two guards before handing off to the tool:

**Post-scan guard** — evaluated immediately after the scan completes:

* Exit code `2` (dangerous findings): launch is **blocked** unconditionally.
* Config files changed between scan and guard check: launch is **blocked**; a rescan is required.
* Exit code `1` (warning-level findings): launch **requires confirmation** unless one of the following is true:
  * `--force` is provided
  * `auto_proceed_below_threshold` is `true` in config
  * The current working directory is inside a configured `trusted_directories` path

**Pre-launch guard** — evaluated at the moment the tool would be invoked:

* If local config files changed between the post-scan guard and the moment of launch: launch is **blocked**; a rescan is required.

<Note>
  `codegate run` always renders terminal/TUI output. Machine-readable output formats (`json`, `sarif`, etc.) are only available from `codegate scan`.
</Note>

## Post-scan change detection

Change detection covers the same local config surface that was scanned, including selected user-scope config files when user-scope scanning is enabled. Any modification to that surface after the scan completes — before the tool actually launches — causes the pre-launch guard to block execution.

## `auto_proceed_below_threshold` and `trusted_directories`

These two config keys control whether warning-level findings require an interactive confirmation:

* `auto_proceed_below_threshold: true` — warning-level findings never prompt; launch proceeds automatically.
* `trusted_directories` — a list of absolute directory paths. If the current working directory resolves to one of these paths, the confirmation prompt is skipped.

Both settings apply only to warning-level findings (exit code `1`). Blocking-level findings (exit code `2`) are never bypassed by either setting.

## Examples

```bash theme={null}
# Scan and launch Claude Code
codegate run claude

# Scan and launch Claude Code, skipping the warning-level confirmation
codegate run claude --force

# Scan and launch Codex CLI
codegate run codex

# Scan and launch Cursor
codegate run cursor
```