Grain CLI

AI code provenance CLI — trace how much of your code was AI-generated and where it came from.

Grain connects Prompt → Conversation → AI Generation → File Changes → Commit, giving developers and teams visibility into AI-assisted code production.

Requires Cursor on macOS. Grain reads the AI tracking database and agent transcripts that Cursor maintains locally. It does not work with other editors or AI coding tools, and currently only supports macOS.

Prerequisites

• macOS — Linux and Windows support is not yet available.
• Cursor — Grain reads Cursor's local AI telemetry. You need to have been using Cursor for development so that its tracking data exists on your machine.
• Node.js 18+
• Git — The repository you run Grain against must be a git repo.

Install

Install globally from npm:

npm install -g @beachio/grain-cli

Then run anywhere:

grain <command>

From source

Clone the repo and install dependencies:

git clone https://github.com/beachio/grain-cli.git
cd grain-cli
npm install
npm link

Quick Start

# See AI% across recent commits
grain commit-trend --last 10

# Deep-dive into a specific commit
grain explain HEAD

# View a specific AI conversation
grain convo <conversationId>

Commands

grain commit-trend

Show recent commits with AI contribution breakdown.

grain commit-trend --last 20
grain commit-trend --json

Output includes AI%, composer/tab/human line counts, and commit messages.

grain explain <commit>

Full AI provenance report for a commit.

grain explain HEAD
grain explain 47174ead
grain explain HEAD --json
grain explain HEAD --override-level 0

Shows:

• Commit metadata and AI attribution percentage
• Composer vs tab vs human line breakdown
• Files changed (sanitized to relative paths)
• Linked AI conversations ranked by relevance
• Transcript excerpts (when provenance level allows)

The --override-level flag lets you preview output at a different provenance level (0-3).

grain convo <conversationId>

Details for a specific AI conversation.

grain convo 30c7410d-dde1-4ca3-...
grain convo 30c7410d --json

Shows model(s) used, time window, top files touched, conversation summary, and transcript timeline.

grain init

Initialize environment and policy configuration for the current repository.

grain init
grain init -e production

Creates .grain/config.yaml in the repo root. Without this file, Grain runs in an unconfigured state — full provenance output, no policy enforcement.

grain env

Display the current environment and provenance level.

grain env
grain env --json

Example output:

  Environment:      production
  Provenance Level: enhanced (level 2)
  Config:           .grain/config.yaml

grain policy-check <commit>

Evaluate a commit against configured policy rules.

grain policy-check HEAD
grain policy-check HEAD --json

Example output:

  Policy Check
  Commit:      47174ead
  Environment: production

  Rules Evaluated: 4

  PASS         allowed_models        All models allowed
  PASS         ai_volume             12 AI code events within limit
  WARNING      ai_contribution       AI% 94% exceeds warn threshold (60%)
  VIOLATION    restricted_paths      AI modified auth/token_service.ts

  Result: 1 warning(s), 1 violation(s)

Exits with code 1 when violations are found, making it suitable for CI integration.

grain policy-list

List all configured policy rules and their current thresholds.

grain policy-list
grain policy-list --json

Configuration

Run grain init to create .grain/config.yaml in your repository. The file controls two things: the environment (which sets the provenance disclosure level) and policy rules.

Environment

environment: production

| Environment | Provenance Level | What's Disclosed | |---------------|------------------|---------------------------------------------------------------| | playground | minimal (0) | AI%, model attribution, commit metadata | | development | standard (1) | + conversation summaries, file list, agent mode | | production | enhanced (2) | + transcript excerpts, tool execution metadata | | regulated | full (3) | + full transcripts, tool call details, reasoning traces |

When no config file exists, Grain operates in an unconfigured state — full provenance output with no filtering, identical to pre-configuration behavior.

Policies

Policies evaluate commits against configurable rules. Add them under the policies key:

policies:
  ai_contribution:
    warn_threshold: 60
    max_threshold: 90

  restricted_paths:
    - auth/
    - billing/
    - security/

  agent_mode:
    require_review: true

  allowed_models:
    - claude-4.6-opus-high-thinking
    - gpt-5.3-codex

  ai_volume:
    max_ai_hashes_per_commit: 2000

ai_contribution — Warn or flag when AI-generated code exceeds a percentage threshold.

restricted_paths — Flag when AI has modified files in sensitive directories.

agent_mode — Flag commits produced by autonomous agent/composer mode conversations.

allowed_models — Restrict which AI models may generate code. Commits using unlisted models are flagged as violations.

ai_volume — Warn when the number of AI code generation events in a single commit is unusually high.

Privacy

Privacy guards are always active (path sanitization, secret redaction, home directory scrubbing, internal URL redaction). Two additional opt-in settings are available:

privacy:
  strip_author: true
  hash_conversation_ids: true

strip_author — Omit git author name and email from all output.

hash_conversation_ids — Display short hashes (e.g. conv:a3f8b2c1) instead of raw conversation UUIDs, preventing direct access to transcript files.

Privacy

Grain applies privacy sanitization to all output, regardless of configuration:

• Path sanitization — Absolute file paths are stripped to repo-relative paths
• Home directory scrubbing — /Users/<name>/, /home/<name>/, ~/.cursor/ patterns are replaced
• Secret redaction — API keys (sk-, ghp_, AKIA...), tokens, passwords, and connection strings are replaced with [REDACTED]
• Internal URL redaction — localhost, private IPs (10.*, 192.168.*), and .local/.internal hostnames are replaced with [INTERNAL_URL]
• Transcript length caps — Controlled by provenance level: Level 0 shows nothing, Level 1 caps at 100 chars, Level 2 at 200 chars

Data Sources

Grain reads from two local data sources — it does not phone home or send data anywhere.

Cursor AI Tracking Database (~/.cursor/ai-tracking/ai-code-tracking.db)

• scored_commits — AI percentage per commit with composer/tab/human breakdown
• ai_code_hashes — AI code fingerprints with file names, timestamps, conversation IDs, models
• conversation_summaries — Titles, summaries, models, and modes

Agent Transcripts (~/.cursor/projects/<id>/agent-transcripts/)

• JSONL files containing full conversation turns (user queries, assistant responses, tool calls)

Git — Standard git operations for commit metadata and changed file lists.

JSON Output

All commands support --json for machine-readable output:

grain explain HEAD --json
grain policy-check HEAD --json
grain env --json
grain commit-trend --json
grain policy-list --json

License

MIT