humanitas-check

AI ethics, by papal decree.

Audit any system prompt or agent config through the 10 principles of Magnifica Humanitas — the first papal encyclical on artificial intelligence (Leo XIV, 15 May 2026).

Why

Magnifica Humanitas is the first papal encyclical on artificial intelligence. It establishes ten principles of Catholic Social Doctrine — from human dignity to transparency — as a framework for evaluating AI systems. humanitas-check uses the Claude API to semantically audit any system prompt against all ten principles, returning a score, per-principle verdicts, and actionable findings.

Useful for:

• Compliance gates in CI/CD pipelines
• Auditing third-party agent configurations before deployment
• Ethical review workflows for AI products

Installation

# global (CLI use)
npm install -g humanitas-check
pnpm add -g humanitas-check
yarn global add humanitas-check

# local dev dependency
npm install --save-dev humanitas-check
pnpm add -D humanitas-check

Requires Node.js ≥18 and an Anthropic API key.

Quickstart

# in your project root
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env.local
humanitas-check system-prompt.txt

Usage

From a file:

humanitas-check <file>

From stdin:

cat system-prompt.txt | humanitas-check --stdin

Options:

| Flag | Values | Default | |------|--------|---------| | --format | text, json | text | | --model | claude-opus-4-7, claude-sonnet-4-6 | claude-opus-4-7 | | --stdin | — | — |

Exit codes:

| Code | Meaning | |------|---------| | 0 | All principles pass | | 1 | At least one warn or fail | | 2 | Execution error |

Output interpretation

| Verdict | Meaning | Recommended CI action | |---------|---------|-----------------------| | PASS (score ≥80) | Low risk — no clear violations | Allow | | WARN (score 50–79) | Potential concern — ambiguous or borderline | Review gate (human sign-off) | | FAIL (score <50) | Clear violation of one or more principles | Block deployment |

A single FAIL on any principle sets the overall verdict to fail (exit code 1). Use --format json to get per-principle details for automated triage.

Model comparison

| Model | Quality | Cost | Best for | |-------|---------|------|----------| | claude-opus-4-7 (default) | Highest | Higher | Final CI gates, compliance audits | | claude-sonnet-4-6 | Good | ~5× lower | Fast iteration, draft reviews |

Doctrine context is cached after the first call (~4 000 tokens reused), so subsequent calls on the same machine are cheaper regardless of model.

Troubleshooting

ANTHROPIC_API_KEY not set
Run humanitas-check from the directory that contains .env or .env.local, or export the key in your shell: export ANTHROPIC_API_KEY=sk-ant-...

Error: principles-reference.md not found
The package was installed incompletely. Run npm install -g humanitas-check again, or run from the repo root with npx tsx src/cli.ts.

CLI hangs with no output
The API call has a 120-second timeout. If it fires, you will see an AbortError. Check your network connection or VPN.

Error: --model must be one of: ...
The tool accepts claude-opus-4-7 and claude-sonnet-4-6 (case-insensitive).

Node.js version error
Requires Node.js ≥18. Check with node --version.

Example output

HUMANITAS CHECK — Magnifica Humanitas Audit
Score: 75/100  |  Overall: ⚠ WARN

  ✓ PASS  Human Dignity
  ✓ PASS  Common Good
  ✓ PASS  Universal Destination of Goods
  ✓ PASS  Subsidiarity
  ✓ PASS  Solidarity
  ✓ PASS  Social Justice
  ⚠ WARN  Human Oversight & Accountability
         No human override mechanism described (§105, §164)
         Rules: oversight/no-human-review
  ✗ FAIL  Freedom from Dependencies
         Engagement maximization without user welfare (§170)
         Rules: freedom/exploit-vulnerability
  ✓ PASS  Transparency & Non-Deception
  ✓ PASS  Human Primacy Over Technology

Summary: The prompt instructs the AI to maximize engagement without regard
for user welfare, violating the freedom principle. An oversight mechanism
should be specified.
Model: claude-opus-4-7 | Tokens: 850 in / 1200 out / 3980 from cache

JSON output (--format json):

{
  "verdict": "fail",
  "score": 75,
  "principles": [
    {
      "principle": "freedom",
      "verdict": "fail",
      "ruleIds": ["freedom/exploit-vulnerability"],
      "citations": ["§170"],
      "finding": "Engagement maximization without user welfare violates freedom from dependency."
    }
  ],
  "summary": "...",
  "modelUsed": "claude-opus-4-7",
  "inputTokens": 850,
  "outputTokens": 1200,
  "cacheReadTokens": 3980
}

Programmatic API

import { analyzeContent } from 'humanitas-check/analyze';

const report = await analyzeContent(systemPrompt, {
  model: 'claude-opus-4-7',
});

console.log(report.score, report.verdict);

CI/CD

Fail the pipeline when an agent's system prompt violates any principle:

- name: Humanitas Check
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: npx humanitas-check agent-system-prompt.txt --format json > humanitas-report.json

The 10 Principles

| Principle | Rule prefix | Key paragraph | |-----------|-------------|---------------| | Human Dignity | dignity/ | §50 | | Common Good | common-good/ | §60 | | Universal Destination of Goods | universal-destination/ | §67 | | Subsidiarity | subsidiarity/ | §71 | | Solidarity | solidarity/ | §76 | | Social Justice | social-justice/ | §80 | | Human Oversight & Accountability | oversight/ | §105, §198 | | Freedom from Dependencies | freedom/ | §170 | | Transparency & Non-Deception | transparency/ | §102 | | Human Primacy Over Technology | human-primacy/ | §129, §233 |

Claude Code skill

The /humanitas-check skill lets you audit prompts directly inside Claude Code — no extra API key, no subprocess.

Global install (recommended)

Installs the skill for all your projects:

# npm
npm install -g humanitas-check

# pnpm
pnpm add -g humanitas-check

# yarn
yarn global add humanitas-check

Then copy the skill to your global Claude skills directory:

mkdir -p ~/.claude/skills/humanitas-check
cp $(npm root -g)/humanitas-check/.claude/skills/humanitas-check/SKILL.md ~/.claude/skills/humanitas-check/

Per-project install

# npm
npm install --save-dev humanitas-check

# pnpm
pnpm add -D humanitas-check

# yarn
yarn add -D humanitas-check

Then copy to your project:

mkdir -p .claude/skills/humanitas-check
cp node_modules/humanitas-check/.claude/skills/humanitas-check/SKILL.md .claude/skills/humanitas-check/

Usage

In Claude Code, run:

/humanitas-check path/to/system-prompt.txt

Or invoke /humanitas-check and paste your prompt directly.

Claude audits the content inline against all 10 principles and outputs score, per-principle verdicts, findings, and remediation guidance.

CLI mode (for CI/CD)

The CLI tool is still available for pipelines and scripted use — see CI/CD below.

Contributing

1. Fork and clone
2. echo "ANTHROPIC_API_KEY=sk-ant-..." > .env.local
3. npx tsx src/cli.ts <file> to run locally without building
4. Open a PR — all changes go through the same 10-principle audit

License

MIT — see LICENSE.

Based on Magnifica Humanitas, Encyclical Letter of His Holiness Leo XIV, 15 May 2026.