Installation.

Three install paths. Pick the one that matches how you want to run CodeTitan: on every pull request (Action), from any terminal (global CLI), or pinned to a single project (per-repo dev dependency).

§ 01 · GitHub Action (recommended)

Zero install. The Action bootstraps the engine, pulls the rule bundle, and runs on every PR. Best for almost every team.

Create .github/workflows/codetitan.yml:

name: CodeTitan
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      security-events: write
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: Noa-Lia/codetitan-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          fail-on-severity: HIGH
          format: both

Required permissions. pull-requests: write posts the review comment; security-events: write uploads SARIF to Code Scanning; contents: read clones the repo. Drop any you don't need.

§ 02 · Global CLI

For running analyses locally or in non-GitHub CI.

# npm
npm install -g @noalia/codetitan

# pnpm
pnpm add -g @noalia/codetitan

# yarn
yarn global add @noalia/codetitan

# verify
codetitan --version

The binary is codetitan (not codetitan-cli). Run it from any directory that contains JavaScript or TypeScript code.

§ 03 · Per-project (dev dependency)

Pin CodeTitan to your repo so every contributor has the same version and it runs in pre-commit or CI without a global install.

npm install --save-dev @noalia/codetitan

# in package.json
{
  "scripts": {
    "review": "codetitan analyze . --changed-only",
    "review:full": "codetitan analyze ."
  }
}

§ 04 · CI (non-GitHub)

Works in any Node-18+ runner. Install the CLI, run it, collect exit code and (optionally) the SARIF output.

# GitLab CI example
code_review:
  image: node:20-alpine
  script:
    - npm install -g @noalia/codetitan
    - codetitan analyze . --no-ai --format json --output findings.json
    - codetitan analyze . --no-ai --format sarif --output codetitan.sarif
  artifacts:
    paths: [findings.json, codetitan.sarif]

Gate the job with --fail-on high — the CLI exits 1 and the pipeline fails.

§ 05 · Pre-commit hook

Catch regressions before they hit CI. Install the hook once; it runs automatically on every git commit.

codetitan hook install
# — to uninstall:
codetitan hook uninstall

The hook analyzes staged files at level 2 by default and blocks the commit on serious findings. Tune it at install time: --level <1-8> changes the depth, --no-block shows findings without ever blocking.

§ 06 · System requirements

• Node.js 18+ (CLI + Action)
• macOS, Linux, or Windows (all supported)
• ~50 MB of disk for the installed CLI + engine
• Network for the install itself; analysis runs fully offline (only --deps and the cloud flags make network calls)

§ 07 · Verify

codetitan --version
# → 2.1.8

codetitan analyze --help
# → prints flag reference

If codetitan isn't found after install, your global bin directory isn't on PATH. Run npm config get prefix and add <prefix>/bin to PATH.