Iris - Code Health for VS Code

Static code insights for JavaScript, TypeScript, Go, and Python. No AI, no backend analysis. Your code never leaves your machine.

Iris includes a guided first-run sidebar tour, a 15-step spotlight walkthrough across the live tabs, an in-flow docs surface inside the sidebar, gate previews before hook install, and configurable enforcement gates for Pro users.

Install from Marketplace | Documentation | iriscode.co

Product truths that should not drift

• Iris is a VS Code extension first. The main product surfaces are the sidebar, detached panel, Code Lens, status bar, welcome page, commands, and the Dependents Table. Problems diagnostics are available as an opt-in setting.
• Analysis is local-first. Iris does use network requests for sign-in, license validation, and dependency/advisory lookups, so "no backend" is inaccurate; "no analysis backend" is correct.
• The git hook is a pre-push hook, not a pre-commit hook. It runs the bundled CLI against the workspace root and blocks the push when the configured threshold fails.
• Iris ships a user-facing CLI (iris) in addition to the hooks. Users can run iris secrets, iris deps, iris auth login, and other commands directly. The CLI is the same binary used by the hooks - it is not a separate install.
• Preset configs (presetId in .irisconfig.json) are free for all users. Custom config (editing threshold values directly) is Pro only. The CLI always reads .irisconfig.json regardless of licence status.
• Trend tracking stores 2 rolling snapshots on Free and unlimited snapshots on Pro.
• The Dependents Table reads root manifests: package.json, go.mod, requirements.txt, and [project] dependencies in pyproject.toml.

What Iris does

Iris analyses your code as you work - every file open and save triggers a full analysis. The sidebar shows:

• Health score - 0-100 composite score per file and workspace
• Complexity score - 1-10 based on function density, nesting, and control flow
• Function list - every function with line number
• Code smells - console.log, magic numbers, TODOs, long parameter lists, unused variables, hardcoded secrets
• TypeScript metrics - any usages, @ts-ignore count, non-null assertions, missing return types
• Workspace analysis - aggregate stats, file type breakdown, largest/most complex files, unused packages (Pro)
• Issues tab - blocking issues and warning-level findings across the current scan scope (Pro)
• TODOs tab - all TODO/FIXME/HACK comments aggregated (Pro)
• Dependents Table - audit all third-party dependencies for outdated versions and CVEs (Pro)

Supported languages

Free vs Pro

Pro is $6/month globally. Nigerian developers: NGN 3,500/month.

Get Pro at iriscode.co

Quick start

1. Install Iris from the marketplace
2. Open any JS, TS, Go, or Python file - the sidebar populates instantly
3. First-run: a guided onboarding tour starts automatically in the sidebar (4 steps: file scoring, workspace scan, Free vs Pro, gate enforcement). Skip any time or restart later with Iris: Restart Guided Tour.
4. Run Iris: Sign In from the command palette to activate your account
5. Run Iris: Analyse Workspace to scan your entire project (Pro)

The book icon in the sidebar header opens the docs surface inside Iris. It leads with the guided-tour section, includes previous/next section navigation, and switches between a left rail on wider sidebars and a horizontal rail on narrower ones. From there you can launch the Start Spotlight Tour walkthrough, and the readiness summary cards at the top of File, Folder, and WS still work as shortcuts so blockers, warnings, TODO load, or unused-package drift take you straight to the right fix surface.

Configuration

VS Code settings (free)

Configure Iris via VS Code settings (iris.*) - open Settings UI or settings.json. All thresholds and toggles are available.

Config presets (Free + Pro)

Iris ships five built-in presets that snap your whole project to a known baseline with one line. Add presetId to .irisconfig.json to use one:

{
  "presetId": "legacy"
}

Available presets: strict, balanced, legacy, security, typescript.

Free users - Iris applies the shipped preset values as the source of truth. Local edits to threshold fields are ignored and receive a yellow warning squiggle in the editor explaining they require Pro. This means the preset registry in the extension, not the file on disk, controls the actual thresholds.

Pro users - the preset acts as a base layer. Any threshold you override locally is merged on top, giving you a customised baseline that your team can still reason about.

Use Iris: Sync Config from Dashboard on the webapp to push a preset or customised config directly to VS Code.

.irisconfig.json (Pro for custom config)

Drop a .irisconfig.json at your project root or inside a subfolder and commit it - your whole team runs Iris with the same thresholds. The extension resolves the nearest file from the current source file back up to the workspace root. Custom threshold values require a Pro licence in the extension. Takes priority over personal defaults and VS Code settings. JSONC comments and trailing commas are supported:

{
  "functionLengthThreshold": 60,
  "fileLengthThreshold": 400,
  "gateMaxComplexity": 14,
  "gateMaxSecrets": 0,
  "enableConsoleLogWarnings": false,
  "enableSecretsDetection": true,
  "enableInlineDiagnostics": false,
  "inlineDiagnostics": {
    "consoleLogs": true,
    "todos": true
  },
  "minHealthScore": 80,
  "healthScoreWeights": {
    "hardcodedSecret": 16,
    "unusedFunction": 3
  },
  "ignoreFiles": ["**/*.test.ts", "**/generated/**"],
  "ignoreFunctions": ["main", "handler"],
  "severityOverrides": {
    "no-exports": "warning",
    "file-too-long": "warning"
  }
}

Pro-only enforcement fields in .irisconfig.json

These fields are read by the bundled CLI, git hook, and build hook. Free users can keep preset-backed configs, but custom gate fields are ignored in the extension with a warning until Pro is active.

Pro custom scoring weights

healthScoreWeights lets Pro teams retune how much each finding affects the final 0-100 score. Any omitted key falls back to Iris defaults.

{
  "healthScoreWeights": {
    "errorWarning": 6,
    "warningWarning": 4,
    "hardcodedSecret": 16,
    "unusedFunction": 3
  }
}

Supported keys: errorWarning, warningWarning, anyUsage, tsIgnore, consoleLog, deepNesting, longParamList, unusedVar, unusedFunction, hardcodedSecret.

Global config

Iris also supports a personal global config file for cross-project defaults. This is not a shared team config - it is your own fallback layer when a workspace does not override something. Global config is still part of the Pro config system in the extension.

Precedence in the extension:

1. nearest folder .irisconfig.json (Pro)
2. workspace-root .irisconfig.json (Pro)
3. global config file
4. VS Code iris.* settings
5. built-in defaults

Global config paths:

• Windows: %APPDATA%\\Iris\\.irisconfig.json
• macOS: ~/Library/Application Support/Iris/.irisconfig.json
• Linux: ${XDG_CONFIG_HOME:-~/.config}/iris/.irisconfig.json

The sidebar now shows which config source is active and surfaces config problems directly in the panel.

Threshold settings

Feature toggles

Other settings

Hardcoded secrets detection

When iris.enableSecretsDetection is enabled, Iris flags string literals that look like secrets:

• Suspicious variable names assigned to string literals - key, token, secret, password, api, and similar
• Known secret formats - GitHub personal access tokens, Stripe API keys, AWS access key IDs, and others
• Placeholder values such as your_key_here, changeme, or todo are ignored and not flagged

Each finding reduces the file health score by 10 points - the highest penalty in the system. Variables flagged as hardcoded secrets are excluded from the unused variables list to avoid double-counting.

Inline diagnostics

When iris.enableInlineDiagnostics is enabled, Iris findings appear as squiggles in the editor and entries in VS Code's Problems panel. It is off by default so routine code-health findings stay in Iris instead of reading like editor/compiler errors.

Default enabled categories

Severity follows severityOverrides

The severityOverrides setting affects both sidebar display and inline diagnostics:

{
  "severityOverrides": {
    "hardcoded-secret": "warning",
    "unused-function": "error"
  }
}

Supported diagnostic codes: hardcoded-secret, file-too-long, function-too-long, too-many-functions, too-many-imports, no-exports, any-usage, ts-ignore, unused-function, unused-var, console-log, magic-number, long-param-list, todo.

CLI

Iris ships a full user-facing CLI alongside the VS Code extension. It is the same binary used by the git hook and build hook - no separate install needed. Once Iris is installed in VS Code, the CLI is available at ~/.vscode/extensions/davidjaja.iris-code-*/dist/cli.js, or you can point to it directly from the extension folder.

Authentication

iris auth login     Sign in with your Iris account (opens browser or prompts for token)
iris auth logout    Clear stored credentials
iris auth status    Show current auth state and GitHub token status

Credentials are stored in ~/.iris/credentials (Unix permissions 600). The CLI checks the following in order:

• IRIS_LICENCE_TOKEN env var - licence token
• GITHUB_TOKEN env var - GitHub PAT for CVE rate limits
• ~/.iris/credentials - stored from iris auth login

Commands

Common options

Most commands accept:

--format pretty|json|github   Output format (default: pretty)
--output <path>               Write JSON result to a file (requires --format json)
--config <path>               Use a specific .irisconfig.json
--min-score <n>               Health score threshold 0-100 (check, gate, report)

--format github (on check and gate) emits GitHub Actions workflow commands so failing rules render as inline annotations on the pull request diff, and writes a pass/fail summary table to $GITHUB_STEP_SUMMARY.

--format json output carries a schemaVersion field (currently 1) so scripts can depend on the payload shape; it is bumped only on a breaking change.

iris secrets

Scans JS, TS, Go, and Python for hardcoded secrets. The same two-layer detection used by the extension sidebar:

• Layer 1: suspicious variable names assigned to string literals (key, token, secret, password, etc.)
• Layer 2: known token formats (GitHub PAT, Stripe key, AWS key ID, Slack token, Google API key, inline Bearer tokens)

Exits 1 if any secrets are found, 0 otherwise. Free - no licence required.

iris deps

Reads package.json, go.mod, requirements.txt, or pyproject.toml and checks each dependency against the current registry version and the GitHub Advisory Database for CVEs.

iris deps               Scan the current directory
iris deps --no-cache    Skip the 24-hour local cache and re-fetch

Without a GitHub token, the advisory API rate limit is 60 req/hr. Run iris auth login to store a GitHub PAT and raise it to 5,000 req/hr. Exits 1 if any vulnerable dependencies are found.

iris gate

Runs the full enforcement gate and shows each configured rule's threshold alongside the actual value:

  ✓ Min health score   threshold: 70    actual: 85    PASS
  ✓ Max secrets        threshold: 0     actual: 0     PASS
  ✗ Max complexity     threshold: 15    actual: 22    FAIL
  - Max file length    threshold: —     actual: 312   not configured

Gate rules are read from .irisconfig.json (minHealthScore, gateMaxSecrets, gateMaxComplexity, gateMaxFileLength, gateMaxSmellsPerFile). Exits 1 if the gate fails.

iris report

Generates a dark-themed standalone HTML file summarising the scan. Defaults to iris-report.html in the current directory. Pass --output path/to/report.html to change the location.

iris hook

Manages the same pre-push and pre-build hooks as the VS Code commands, directly from the terminal - useful for team onboarding scripts and CI setup:

iris hook git install       Install pre-push hook in the nearest git repo
iris hook build install     Install pre-build hook (prebuild script or Makefile target)
iris hook git status        Check whether the hook is installed (no Pro required)

After installing a hook, Iris needs your licence token at push/build time. Set IRIS_LICENCE_TOKEN in your shell profile or run iris auth login once to store it in ~/.iris/credentials.

Enforcement in CI (GitHub Actions)

Run iris gate . --format github in your CI to block merges and render inline annotations on the pull request diff at the exact failing lines. Everything runs on your own runners - your code never leaves your infrastructure.

• Copy-paste workflow: .github/workflows/iris-example.yml
• Full guide: docs/github-actions.md and iriscode.co/docs/enforcement/github-actions
• Generate it from the editor: run Iris: Add GitHub Actions Workflow (Pro) to write .github/workflows/iris.yml into the open workspace

Other CI systems: run Iris: Add CI Pipeline Snippet (Pro) to generate an Iris step for GitLab CI, Bitbucket Pipelines, an npm/pnpm/yarn script, or a generic shell script. Inline annotations are GitHub-specific; other systems gate on the exit code and can keep the JSON report as an artifact. On Alpine/musl runners the npm install -g @iris-code/cli route works unchanged; a dedicated iris-alpine-amd64 binary is also published on each release.

When a Pro step runs without a valid licence (no token, or the licence server is unreachable), it skips and exits 0 with a notice rather than failing the build; inside a GitHub runner it also posts a non-blocking warning annotation.

Exit codes used across all commands: 0 pass / no findings, 1 fail / findings found, 2 invalid arguments or config error.

Dependents Table (Pro)

Open Iris: Open Dependents Table from the Command Palette to audit your third-party dependencies. Requires Pro.

• Table view - lists every dependency with its installed version, latest version, status (up-to-date / outdated / vulnerable / unknown), and any CVEs. Click N CVEs to expand inline advisory details per package.
• Ecosystems supported - npm (package.json), Go (go.mod), Python (requirements.txt / pyproject.toml).
• Cache - results are cached locally for 24 hours in .iris-cache/ (gitignored automatically). Click Scan to force a fresh check.
• GitHub token - click Token in the toolbar to store a GitHub PAT in VS Code's SecretStorage, raising the advisory API rate limit from 60 to 5,000 requests/hour.

See docs/dependents-table.md for full documentation.

Git hook (Pro)

Iris can install a pre-push hook that blocks pushes when any file's health score is below your configured threshold. Requires Pro. On first activation in a git repo, Pro users are offered the hook automatically. You can also manage it manually:

VS Code commands:

CLI commands (same behaviour, useful for team scripts):

iris hook git install [path]    Install the pre-push hook
iris hook git uninstall [path]  Remove the hook
iris hook git status [path]     Check if the hook is installed (Free)

Set "minHealthScore": 80 in .irisconfig.json to control the threshold. See docs/git-hook.md for full details.

Build hook (Pro)

Iris can wire a health check into your build step so failing code cannot be built. Requires Pro.

• Node projects - adds a prebuild script to package.json. If a prebuild script already exists, Iris chains before it.
• Go / Python projects - injects an iris-check phony target into your Makefile (creating it if absent) and wires it as a prerequisite on the first build: or all: target found.

VS Code commands:

CLI commands:

iris hook build install [path]    Install the pre-build hook
iris hook build uninstall [path]  Remove the hook
iris hook build status [path]     Check if the hook is installed (Free)

The sidebar shows a "Build Hook" section next to the Git Hook section so you can see install status at a glance. See docs/build-hook.md for full details.

Commands

Privacy

Your code never leaves your machine. All analysis runs entirely locally. Iris makes network requests for account management (sign-in, license validation), the dependents table (npm/PyPI/Go Proxy and GitHub Advisory API), and product-use events covering feature usage, enforcement activity (pushes blocked, hook runs), and account operations. No source code, file contents, or project structure is ever transmitted. Product events can be disabled from your account settings.

Documentation | Pricing | Support