annotations

Generate annotations for GitHub Checks API integration.

Usage

whogitit annotations [OPTIONS]

Description

The annotations command generates annotation data suitable for the GitHub Checks API. This is primarily used in CI/CD pipelines to display AI attribution information directly in the GitHub PR diff view.

Annotations appear as colored markers in the “Files changed” tab, showing which lines were AI-generated and the prompts used.

Options

Core Options

Consolidation Options

Filtering Options

Grouping and Sorting Options

Consolidation Modes

Auto (default)

Smart consolidation that chooses between file-level and line-level annotations based on AI coverage:

• File-level annotation when:

  • File is new (no original lines), OR
  • AI coverage >= threshold (default 70%) AND prompts <= prompt limit (default 3)

• Line-level annotations otherwise

File

Creates one annotation per file, summarizing all AI attribution.

whogitit annotations --consolidate file

Lines

Creates granular line-level annotations, grouping consecutive AI lines from the same prompt.

whogitit annotations --consolidate lines

Annotation Prioritization

When more annotations are generated than --max-annotations allows, annotations are scored and prioritized by:

1. AI coverage (up to 40 points) - Higher AI percentage scores higher
2. AI line count (up to 30 points) - More AI lines score higher (capped at 100)
3. New file bonus (15 points) - Files created entirely by AI
4. In-diff bonus (15 points) - Lines within the PR diff

The highest-scoring annotations are kept.

Examples

Basic usage (for GitHub Actions)

whogitit annotations --base ${{ github.event.pull_request.base.sha }} --head ${{ github.sha }}

JSON output for debugging

whogitit annotations --format json

File-level consolidation for cleaner diffs

whogitit annotations --consolidate file --base main

Custom threshold and prompt limit

# Consolidate at 50%+ AI coverage with up to 5 prompts
whogitit annotations --consolidate-threshold 0.5 --consolidate-prompt-limit 5

Filter to significant files only

# Only annotate files with at least 10 AI lines and 20% AI coverage
whogitit annotations --min-ai-lines 10 --min-ai-percent 20.0

Annotate only lines in the PR diff

whogitit annotations --base main --diff-only

Group AI and AI-modified lines together

# Creates fewer, larger annotations
whogitit annotations --group-ai-types

Sort by AI line count instead of coverage

whogitit annotations --sort-by lines

Output Format

GitHub Checks Format

{
  "annotations": [
    {
      "path": "src/main.rs",
      "start_line": 42,
      "end_line": 48,
      "annotation_level": "notice",
      "title": "AI Generated (7 lines)",
      "message": "Model: claude-opus-4-5-20251101 | Session: 2024-01-15\n\n**Breakdown:** 5 AI, 2 AI-modified, 0 human, 0 original\n\n**Prompt:** Add error handling with retry logic...",
      "raw_details": "Add error handling with retry logic..."
    }
  ],
  "summary": {
    "files_analyzed": 5,
    "models": ["claude-opus-4-5-20251101", "claude-sonnet-4-20250514"],
    "session_range": "2024-01-15 to 2024-01-20"
  }
}

JSON Format

Same structure but without GitHub-specific formatting constraints.

Shallow Clone Handling

When running in a shallow clone (common in CI), the command automatically:

• Detects the shallow clone
• Switches to file-level consolidation mode
• Displays a warning message

This ensures annotations work even with limited git history.

GitHub Actions Integration

See the CI/CD Integration guide for complete GitHub Actions workflow examples.

- name: Generate annotations
  run: |
    ANNOTATIONS=$(whogitit annotations \
      --base ${{ github.event.pull_request.base.sha }} \
      --min-ai-lines 5 \
      --sort-by coverage)
    echo "$ANNOTATIONS" > annotations.json

- name: Create Check Run
  uses: actions/github-script@v7
  with:
    script: |
      const fs = require('fs');
      const output = JSON.parse(fs.readFileSync('annotations.json'));
      // ... create check run with output.annotations

See Also

• summary - PR summary in Markdown format
• CI/CD Integration - Full workflow examples