Skip to main content

cai-miner

CI PyPI Python License: MIT

cai-miner (Coding-Agent Invocations miner) mines the git history of GitHub Actions workflow files and finds the coding-agent invocations inside them: the steps that run Claude Code, Codex, Copilot, Gemini, Cursor, Aider and similar agents as part of a repository's continuous integration.

For every workflow file that invokes an agent at some point, it emits the file's whole history (before the agent arrived, while it was there, and after it was removed), one row per agent invocation, and repository-level denominators. It is the tool behind the GHAgentCI dataset.

Why content-based detection

Agent context files such as CLAUDE.md or AGENTS.md can be classified by path, since the filename names the agent. An agentic CI workflow cannot: it is an ordinary .github/workflows/whatever.yml, indistinguishable by name from a build or lint workflow. cai-miner therefore parses every revision of every workflow file, walks its jobs and steps, and matches each step against a catalogue of agents.

Not every mention of an agent is an invocation; a workflow that sets ANTHROPIC_API_KEY may just be feeding a test suite. Evidence is therefore tiered:

evidence meaning strength
uses a step invokes a dedicated agent GitHub Action strong
run a step shell-invokes an agent CLI strong
path the workflow file has a reserved, agent-specific name strong
ghaw the file was compiled by GitHub Agentic Workflows strong
job a job carries a reserved, agent-specific id weak
url a step talks to an LLM inference endpoint weak
env an agent or LLM credential is bound at that scope weak

A revision counts as agentic only with strong evidence, unless you pass --include-weak.

Installation

cai-miner needs Python 3.11 or newer and git 2.30 or newer on the PATH. Its only Python dependency is PyYAML.

uv tool install cai-miner     # recommended: an isolated, global command
pipx install cai-miner        # equivalent with pipx
pip install cai-miner         # into the current environment

Or run it once without installing: uvx cai-miner --help.

Quickstart

cai-miner works on local clones. A size-capped partial clone without a working tree is the fastest way to get one (see cloning):

git clone --filter=blob:limit=64k --no-checkout --single-branch \
    https://github.com/vitejs/vite.git clones/vite

# Agent invocations across the whole history, as CSV on stdout
cai-miner clones/vite

# Full outputs for many clones, plus every distinct workflow revision
cai-miner --from-file clones.txt -o out/ --content-dir out/content

With -o out/ you get:

file one row per
repositories.csv repository, agentic or not, including failures
revisions.csv change to a workflow file whose history is agentic at some point
steps.csv agent invocation
ghaw_manifests.csv revision of a GitHub Agentic Workflows source or compiled file

Every column is documented in the output reference.

Command-line reference

cai-miner [options] [REPOSITORY ...]
option effect
-c, --config FILE detector catalogue (TOML); defaults to the bundled frozen catalogue
--from-file FILE read clone paths from a file, one per line
-o, --out-dir DIR write the four CSV files to DIR
--content-dir DIR store each distinct workflow revision as DIR/<sha256>.yml
--rev REV commit to start the history walk from (default HEAD)
--since DATE ignore commits older than DATE, e.g. 2024-01-01
--include-weak let job, url and env evidence make a revision agentic
--keep-all emit every workflow revision, not only agentic histories
--no-prefetch disable the bulk blob prefetch on partial clones
--repository OWNER/NAME name of the single repository given, instead of reading it from the clone's remote
--fail-fast stop at the first repository that fails
-q, --quiet suppress progress output
--version print the version and exit

python -m cai_miner is equivalent to cai-miner.

Detector catalogue

Agents and their patterns live in a TOML catalogue; adding an agent needs no code changes:

[agents.myagent]
display_name = "My Agent"
uses = ["myorg/my-agent-action"]
run  = ["myagent --run"]
env  = ["MYAGENT_API_KEY"]

The bundled default is the catalogue GHAgentCI was mined with: a hand-written catalogue drawn from vendor documentation, merged with one generated from the GitHub Marketplace ai-assisted category. See the catalogue reference for the format, includes, aliases and overrides.

Files generated by GitHub Agentic Workflows are detected from the compiler's own header, with no catalogue involved, and their manifests are parsed in full; see gh-aw.

Using it from Python

from cai_miner.config import load_config
from cai_miner.detect import analyse
from cai_miner.extract import extract_repository

catalogue = load_config()  # the bundled catalogue; or load_config("my.toml")

# Classify one workflow revision
facts = analyse(catalogue, open("ci.yml").read(), ".github/workflows/ci.yml")
print(facts.strong_agents)

# Mine one local clone
result = extract_repository("clones/vite", catalogue)
print(result.summary.n_agentic_files, len(result.steps))

The command line is the stable interface; the Python modules may change between minor versions before 1.0.

Reproducing GHAgentCI

The GHAgentCI dataset and its replication package are archived on Zenodo at doi:10.5281/zenodo.24088832. This repository also holds the scripts and validation material behind it; they are not part of the installed package:

Citing

If you use cai-miner or GHAgentCI in research, please cite it; GitHub's "Cite this repository" button reads CITATION.cff.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for the development setup.

License

MIT

Metadata

Release files for cai-miner 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cai-miner 0.1.0
File Size Uploaded Provenance Actions
cai_miner-0.1.0.tar.gz 61.0 kB With provenance Details for cai_miner-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cai-miner 0.1.0
File Interpreter ABI Platform Actions
cai_miner-0.1.0-py3-none-any.whl Python 3 none any Details for cai_miner-0.1.0-py3-none-any.whl

Total release size: 110.4 kB

Release files / cai_miner-0.1.0.tar.gz

Download URL cai_miner-0.1.0.tar.gz
Size 61.0 kB
Tags Source
SHA-256 checksum
How to use checksums
bc5107e1e2133bb82c7c70df0e16e5c9d3f8176ea0a953804c138ebd225b839e
BLAKE2b-256 checksum
How to use checksums
0835212c88affbe732ffaa6736bc703eaa7c857fceb9db02d0d2776c3b2258d9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / cai_miner-0.1.0-py3-none-any.whl

Download URL cai_miner-0.1.0-py3-none-any.whl
Size 49.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e62115a7582e69f7a73fc8e6532202a159c4cbdea3115c070d88db9136e1f663
BLAKE2b-256 checksum
How to use checksums
f5f802104653ee63f961ddc6878d40edbe7e98d99d8385bf761e5d1e45114ed3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for cai-miner 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cai_miner-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page