Advanced.

Power-user territory. Everything here assumes you've read the Getting started and CLI reference guides. Custom rules, CI gating trade-offs, fixer safety, performance tuning, self-hosting.

§ 01 · Custom rules

Custom rules are YAML, in a Semgrep-compatible format. Put them in .codetitan/rules/*.yml (or inline in .codetitan.yml), register with rules add, test with rules test.

# .codetitan/rules/no-hardcoded-password.yml
rules:
  - id: custom/hardcoded-password
    severity: ERROR
    message: Hardcoded password detected
    languages: [javascript, typescript]
    pattern: password = "$PASSWORD"
    metadata:
      category: security
      cwe: CWE-798
      confidence: HIGH
    fix: "Use environment variables instead"

codetitan rules add no-hardcoded-password.yml   # validate + register
codetitan rules test no-hardcoded-password.yml  # try it against a sample
codetitan rules test my.yml --target src/auth.ts # or your own file
codetitan rules list                             # see what's registered

Pattern variables ($PASSWORD) bind like Semgrep metavariables. Start narrow: a rule that fires everywhere teaches the team to ignore it.

§ 02 · Gating strategy

The severity gate is the single most impactful CI knob. In the GitHub Action it's the fail-on-severity input (HIGH); on the CLI it's the --fail-on flag (lowercase, e.g. --fail-on high). Three common strategies:

• Strict — fail-on-severity: HIGH. Any HIGH or CRITICAL blocks merge. Use for production-critical repos.
• Graduated — gate only on CRITICAL for first 4 weeks, tighten to HIGH after the team adapts.
• Diff-only — --changed-only + gate. Only new findings in the PR block merge; legacy findings don't. Use when inheriting a codebase with historical debt.

Per-repo defaults live in .codetitan.yml (output.fail_on and rules.severity_threshold); CLI flags override the file. Exempt whole paths with .codetitanignore, and suppress individual lines with a // codetitan-suppress: <RULE_ID> comment on the line above — see the rules page.

§ 03 · Fixer safety

The fixer's safety model is isolation, not undo: fixes are applied and validated in an isolated git worktree by default, and nothing touches your repo until you promote the result.

# 1 — preview what would change
codetitan fix . --dry-run --patch-output fixes.patch

# 2 — run the fixes in an isolated worktree, with your tests as the judge
codetitan fix . --validate-command "npm test"

# 3 — read the diff, then promote into the repo
codetitan fix . --promote --diff-reviewed

--direct bypasses the worktree and writes straight into the repo — it is labeled unsafe in the CLI for a reason. If you use it, commit your in-flight work first. Fixes are automatic edits to source; treat them with the skepticism you'd apply to any refactor PR.

§ 04 · Performance tuning

• --changed-only — drop full-scan time from minutes to seconds. Best for pre-commit hooks and PR CI (the Action defaults to it on pull requests).
• --min-confidence 85 — surface only high-confidence findings (0–100 scale).
• --level — lower levels scan less. The pre-commit hook defaults to 2; full runs default to 4.
• Exclude generated code via .codetitanignore — dist/, build/, vendor directories (the generated default already covers the common ones).
• Action runtime caching — set the runtime-root input to a persistent directory to cache the engine runtime between workflow runs.

§ 05 · Self-hosting (Enterprise roadmap)

For regulated environments where source code cannot transit third-party infrastructure, a self-hosted / air-gapped deployment is on the Enterprise roadmap — not generally available yet. Today the deterministic CLI and the GitHub Action already run entirely on your own machine and your own runner (your code never leaves CI), which covers most no-egress requirements. If a fully self-hosted control plane is on your critical path, contact enterprise@codetitan.dev and we'll scope it with you.