Getting started.

Zero to first review in five minutes. This walks through a full cycle: install, run your first analysis, read the report, and understand the PR Risk Score.

§ 01 · Install

Skip this if you already added the GitHub Action. For a local walkthrough:

npm install -g @noalia/codetitan

§ 02 · Your first analysis

Run CodeTitan on any repo:

codetitan analyze . --no-ai --format json --output report.json

The flags: . means the current directory, --no-ai skips the LLM ensemble (faster, and the safe default while you're trying it out), --format json writes a machine-readable report, --output specifies the destination.

§ 03 · Reading the report

A real report, trimmed (this finding came from an actual run against a one-file Express app):

{
  "status": "completed",
  "files_analyzed": 1,
  "findings_count": 3,
  "findings": [
    {
      "file_path": "server.js",
      "line_number": 6,
      "severity": "HIGH",
      "category": "TAINT_SQL_INJECTION",
      "message": "Tainted user input may reach a SQL query. User input reaches sink directly on this line.",
      "code_snippet": "db.query(\"SELECT * FROM users WHERE name = '\" + req.query.name + \"'\");",
      "confidence": 64
    }
  ],
  "duration_ms": 60,
  "learnedProfile": { ... },
  "prRiskScore": { ... }
}

• category · the rule identifier. See the rules catalog.
• severity · one of CRITICAL, HIGH, MEDIUM, LOW.
• file_path / line_number · exact location, with the offending line in code_snippet.
• confidence · 0–100. Filter with --min-confidence.
• learnedProfile / prRiskScore · the per-repo memory state and the composite risk for this run.

§ 04 · The PR Risk Score

A 0–100 composite with a letter grade, printed on every run — for example Risk: 60 (high / C). It weighs the severity mix of the findings against your repo's learned profile, so the same diff scores differently in a repo with history than in a fresh one. It appears in the console output, in report.json as prRiskScore, and in the PR comment the Action posts.

Gate on it in CI with --risk-threshold <number> (exit 1 at or above the threshold; default 80), or gate on severities directly with --fail-on high.

§ 05 · Next steps

• Read the CLI reference for every flag and command.
• Browse the rules catalog to see what's enforced.
• See how the engine features work — learned profile, AI drift, 3-pass taint.
• When you're ready for power-user settings, the advanced guide.