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

# Analysis layers

> How CodeGate's four-layer pipeline discovers, analyses, and remediates AI tool configuration risks — from offline file walking to opt-in deep scan and guided remediation.

CodeGate uses a four-layer pipeline to inspect AI tool configuration surfaces. Layers 1 and 2 are offline-first and deterministic; they run on every scan without network access or external tool invocation. Layer 3 is opt-in and requires explicit per-resource consent. Layer 4 provides guided remediation with full undo support.

## Offline-first design

Layers 1 and 2 run entirely offline. They make no network requests, spawn no external processes, and produce the same output for the same input on every run. This design means:

* A scan never leaks project content to external services by default.
* Results are reproducible and suitable for CI gating.
* The scan completes even in air-gapped environments.

Layer 3 departs from this by contacting external resources and invoking a local meta-agent. It is always opt-in and consent-gated.

## Pipeline flow

<Steps>
  <Step title="Layer 1 — Discovery">
    The file walker traverses the project tree up to five directory levels deep, skipping `node_modules`, `dist`, `build`, `.venv`, `vendor`, and `.git` internals while still descending into `.git/hooks`. It records symlink escapes (symlinks that resolve outside the project root) and circular symlinks for later static analysis.

    The config parser identifies AI tool configuration files by path pattern and format (JSON, YAML, TOML, Markdown, plain text). The tool detector checks whether AI coding tools are installed by probing `PATH`, known application bundle locations, and VS Code extension directories. Detected tools include: `claude-code`, `codex-cli`, `opencode`, `cursor`, `windsurf`, `kiro`, `vscode`, `jetbrains`, and `github-copilot`.

    The knowledge base provides the static lists that drive safe-server allow-listing, blocked command defaults, and known-safe formatter and LSP server references used in Layer 2 detections.
  </Step>

  <Step title="Layer 2 — Static analysis">
    The static engine receives the parsed files, symlink escape list, and git hook list from Layer 1. It runs a set of registered file-level and global audits against each file without any network access.

    Built-in detectors cover: environment variable overrides, command execution patterns, consent bypass configurations, rule/instruction file injection, IDE settings issues, symlink escapes, git hook anomalies, plugin manifest issues, and advisory intelligence matching.

    The rule engine loads built-in rule packs (per-tool JSON rule packs for Claude Code, Codex, Cursor, Copilot, OpenCode, and common patterns) plus any additional `rule_pack_paths` from config. Rules support field-path queries and text pattern matching.

    All Layer 2 findings carry a `layer: "L2"` label and a `confidence` of `HIGH`, `MEDIUM`, or `LOW`.
  </Step>

  <Step title="Layer 3 — Deep scan (opt-in)">
    Enabled with `--deep`. CodeGate discovers eligible external resources from known config paths and eligible local instruction files (`AGENTS.md`, `CODEX.md`, discovered skill/rule markdown) from the already-selected scan surface.

    In interactive mode, CodeGate enumerates installed meta-agents (`claude`, `codex`, `opencode`) and prompts for selection. For each candidate resource, it presents a per-resource consent prompt and a command preview before executing anything. No network request or meta-agent invocation occurs without user approval.

    MCP tool-description acquisition does not execute untrusted stdio command arrays. Local instruction-file analysis is text-only: file content and extracted URL strings are passed as inert text; referenced content is never executed.

    In non-interactive mode (CI), deep actions are skipped unless `--force` is provided.

    Layer 3 outcomes — including consent-skipped, timeout, auth failure, and schema-mismatch results — are normalized into findings so operators can audit why deep scan did not fully complete.
  </Step>

  <Step title="Layer 4 — Remediation">
    Remediation is opt-in and guided. Use `--remediate` for interactive guided fixes, `--fix-safe` to apply unambiguous critical fixes automatically, `--dry-run` to preview proposed changes without writing, or `--patch` to generate a patch file for review workflows.

    Every remediation session writes a backup under `.codegate-backup/` before modifying any file. Run `codegate undo [dir]` to restore the latest backup session. Remediation is best-effort: always review changes before committing them.
  </Step>
</Steps>

<Note>
  Layer 3 deep scan increases your exposure compared to a static-only scan because it may fetch remote metadata and invoke a selected local AI tool. Keep `--deep` off in automated pipelines unless you have reviewed its consent model and trust the installed meta-agent.
</Note>

## Summary table

| Layer | Name            | Network | Deterministic | Opt-in                             |
| ----- | --------------- | ------- | ------------- | ---------------------------------- |
| L1    | Discovery       | No      | Yes           | No                                 |
| L2    | Static analysis | No      | Yes           | No                                 |
| L3    | Deep scan       | Yes     | No            | Yes (`--deep`)                     |
| L4    | Remediation     | No      | Yes           | Yes (`--remediate` / `--fix-safe`) |