humancov

A lightweight CLI that tracks AI-generated vs human-written code in your repo.

Add provenance headers to your files, scan, and know exactly what's been human-reviewed.

Install

Install as a dev dependency in your project:

npm install --save-dev humancov
npx humancov scan

Requires Node >= 18.

AI Tool Setup

Run humancov init first - it teaches your AI coding tool to tag every file it generates with provenance headers automatically.

humancov init

It detects existing config files (or rule directories) and appends the instructions block. If a modern rules directory exists, a dedicated rule file is created instead.

| Tool | Config file | |---|---| | Claude Code | CLAUDE.md | | AGENTS.md (cross-tool) | AGENTS.md | | Cursor (legacy) | .cursorrules | | Cursor (rules dir) | .cursor/rules/humancov.mdc | | Windsurf (legacy) | .windsurfrules | | Windsurf (rules dir) | .windsurf/rules/humancov.md | | GitHub Copilot | .github/copilot-instructions.md |

If the file already contains AI-Provenance instructions, it skips it. If no config files are found, it lists the supported files.

Quick Start

1. Add headers to your files (first 20 lines):

# AI-Provenance-Origin: ai
# AI-Provenance-Generator: claude-code
# AI-Provenance-Reviewed: false
# AI-Provenance-Tested: false

2. Scan your repo:

humancov scan

AI-Provenance Scan
==================
Total files scanned:  22
AI-generated:         18
Human-written:        0
Mixed:                0
Unknown (no header):  4

Of AI files:
  Reviewed:  3 / 18  (17%)
  Tested:    5 / 18  (28%)

3. When you review a file, update the header:

# AI-Provenance-Origin: ai
# AI-Provenance-Reviewed: true
# AI-Provenance-Confidence: high

Commands

| Command | Description | |---|---| | humancov scan | Scan repo and print report | | humancov scan --json | Output results as JSON | | humancov scan --badge | Output shields.io badge URL | | humancov scan --check <N> | Exit 1 if reviewed% < N (for CI) | | humancov manifest | Generate .humancov manifest file | | humancov init | Add AI-Provenance instructions to AI tool configs | | humancov --version | Print version |

Examples

--json - per-file provenance data:

{
  "files": [
    { "file": "src/scanner.js", "origin": "ai", "generator": "claude-code", "reviewed": "false", ... },
    { "file": "lib/utils.py", "origin": "human", "reviewed": "true", ... }
  ],
  "summary": { "total": 22, "ai": 18, "human": 0, "mixed": 0, "unknown": 4, "reviewed": 3, "tested": 5 }
}

--badge - shields.io URL + markdown snippet:

https://img.shields.io/badge/human--reviewed-17%25%20of%20AI%20files-red
![Human Reviewed](https://img.shields.io/badge/human--reviewed-17%25%20of%20AI%20files-red)

--check 80 - CI gate (exits 1 on failure):

Reviewed: 17% (threshold: 80%)
FAIL: 17% < 80%

Header Keys

Add AI-Provenance- headers in a comment block at the top of any file (first 20 lines). Use your language's comment syntax (//, #, <!--, /*, --).

| Key | Required | Values | |---|---|---| | Origin | yes | ai, human, mixed | | Generator | no | tool name (claude-code, copilot, codex...) | | Reviewed | yes | true, false, partial | | Tested | no | true, false, partial | | Confidence | no | high, medium, low | | Notes | no | free-text |

Ignore Files

humancov automatically respects your .gitignore - no extra setup needed. Anything ignored by git is ignored by humancov.

For humancov-specific ignores on top of .gitignore, create .humancov-ignore at repo root (same gitignore syntax):

*.md
LICENSE
*.lock
dist/
coverage/

Resolution order: built-in defaults → .gitignore → .humancov-ignore.

Built-in defaults: node_modules/, .git/, .humancov, .humancov-ignore, *.md, *.lock, LICENSE, .gitignore, .github/.

Badge

Shows the percentage of AI files that have been human-reviewed:

![Human Reviewed](https://img.shields.io/badge/human--reviewed-42%25%20of%20AI%20files-yellow)

| Reviewed % | Color | |---|---| | < 25% | red | | 25-74% | yellow | | 75-99% | green | | 100% | brightgreen |

CI Integration

Add to your pipeline to enforce a review threshold:

# GitHub Actions example
- name: Check AI review coverage
  run: npx humancov scan --check 80

Exits with code 1 if the reviewed percentage is below the threshold.

Pre-commit Hook

A pre-commit hook keeps the badge and .humancov manifest up to date automatically on every commit.

Run humancov init and your AI tool will propose installing the hook for you.

Create .git/hooks/pre-commit with this content:

#!/bin/sh

# humancov - auto-update badge and manifest before each commit
npx humancov manifest 2>/dev/null
if [ -f ".humancov" ]; then
  git add .humancov
fi

BADGE_URL=$(npx humancov scan --badge 2>/dev/null | head -1)
if [ -n "$BADGE_URL" ] && [ -f "README.md" ]; then
  node -e "
    const fs = require('fs');
    const url = process.argv[1];
    const readme = fs.readFileSync('README.md', 'utf8');
    const updated = readme.replace(
      /!\[Human Reviewed\]\(https:\/\/img\.shields\.io\/badge\/human--reviewed-[^)]*\)/,
      '![Human Reviewed](' + url + ')'
    );
    if (updated !== readme) { fs.writeFileSync('README.md', updated); }
  " "\$BADGE_URL"
  git add README.md
fi

Then make it executable:

chmod +x .git/hooks/pre-commit

Note: .git/hooks/ is local and not shared via git. Each contributor needs to set up the hook on their machine. If your team uses husky or a similar tool, add the hook content to your shared hooks directory instead.

Manifest

humancov manifest generates a .humancov file at repo root - a TSV summary of all files with provenance headers:

# .humancov
# file              origin   reviewed   tested   generator     confidence
src/scanner.js      ai       true       false    claude-code   high
src/parser.js       ai       false      false    claude-code   -
lib/utils.py        human    true       true     -             -

File headers are the source of truth. If both exist and conflict, headers win.

How It Works

humancov scan
     |
     v
Load ignore patterns (.humancov-ignore)
     |
     v
List files (git ls-files, or recursive walk)
     |
     v
For each file:
  - Skip if ignored or binary
  - Read first 20 lines
  - Extract AI-Provenance-* headers
  - Classify: ai / human / mixed / unknown
     |
     v
Aggregate stats and output report

Spec

See the AI-Provenance Spec v0.1 for the full specification.

License

CC0 1.0 (public domain)