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.

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.

Valid run targets

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

Flags

--no-tui · boolean · default: "false"

Disable the TUI dashboard and interactive prompts during the preflight scan.

--config · string

Path to a specific global config file. Overrides the default ~/.codegate/config.json location.

--force · boolean · default: "false"

Skip the warning-level launch confirmation prompt. Has no effect on blocking-level findings — those always prevent launch regardless of --force.

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.

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

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

# 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