diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4f9019d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,603 @@
+# @bahmutov/cy-grep
+
+> Filter tests using substring or tag
+
+```shell
+# run only tests with "hello" in their names
+npx cypress run --env grep=hello
+
+  ✓ hello world
+  - works
+  - works 2 @tag1
+  - works 2 @tag1 @tag2
+
+  1 passing (38ms)
+  3 pending
+```
+
+All other tests will be marked pending, see why in the [Cypress test statuses](https://on.cypress.io/writing-and-organizing-tests#Test-statuses) blog post.
+
+If you have multiple spec files, all specs will be loaded, and every test will be filtered the same way, since the grep is run-time operation and cannot eliminate the spec files without loading them. If you want to run only specific tests, use the built-in [--spec](https://on.cypress.io/command-line#cypress-run-spec-lt-spec-gt) CLI argument.
+
+Watch the video [intro to cypress-grep plugin](https://www.youtube.com/watch?v=HS-Px-Sghd8)
+
+Table of Contents
+
+<!-- MarkdownTOC autolink="true" -->
+
+- [@bahmutov/cy-grep](#bahmutovcy-grep)
+  - [Install](#install)
+    - [Support file](#support-file)
+    - [Config file](#config-file)
+  - [Usage Overview](#usage-overview)
+  - [Filter by test title](#filter-by-test-title)
+    - [OR substring matching](#or-substring-matching)
+    - [Test suites](#test-suites)
+    - [Invert filter](#invert-filter)
+  - [Filter with tags](#filter-with-tags)
+    - [Tags in the test config object](#tags-in-the-test-config-object)
+    - [AND tags](#and-tags)
+    - [OR tags](#or-tags)
+    - [Inverted tags](#inverted-tags)
+    - [NOT tags](#not-tags)
+    - [Tags in test suites](#tags-in-test-suites)
+    - [Grep untagged tests](#grep-untagged-tests)
+  - [Pre-filter specs (grepFilterSpecs)](#pre-filter-specs-grepfilterspecs)
+  - [Omit filtered tests (grepOmitFiltered)](#omit-filtered-tests-grepomitfiltered)
+  - [Disable grep](#disable-grep)
+  - [Burn (repeat) tests](#burn-repeat-tests)
+  - [TypeScript support](#typescript-support)
+  - [General advice](#general-advice)
+  - [DevTools console](#devtools-console)
+  - [Debugging](#debugging)
+    - [Log messages](#log-messages)
+    - [Debugging in the plugin](#debugging-in-the-plugin)
+    - [Debugging in the browser](#debugging-in-the-browser)
+  - [Examples](#examples)
+  - [See also](#see-also)
+  - [Migration guide](#migration-guide)
+    - [from v1 to v2](#from-v1-to-v2)
+    - [from v2 to v3](#from-v2-to-v3)
+  - [Small Print](#small-print)
+
+<!-- /MarkdownTOC -->
+
+## Install
+
+Assuming you have Cypress installed, add this module as a dev dependency.
+
+```shell
+# using NPM
+npm i -D @cypress/grep
+# using Yarn
+yarn add -D @cypress/grep
+```
+
+**Note**: @cypress/grep only works with Cypress version >= 10.
+
+### Support file
+
+**required:** load this module from the [support file](https://on.cypress.io/writing-and-organizing-tests#Support-file) or at the top of the spec file if not using the support file. You import the registration function and then call it:
+
+```js
+// cypress/support/index.js
+// load and register the grep feature using "require" function
+// https://github.com/cypress-io/cypress/tree/develop/npm/grep
+const registerCypressGrep = require('@cypress/grep')
+registerCypressGrep()
+
+// if you want to use the "import" keyword
+// note: `./index.d.ts` currently extends the global Cypress types and
+// does not define `registerCypressGrep` so the import path is directly
+// pointed to the `support.js` file
+import registerCypressGrep from '@cypress/grep/src/support'
+registerCypressGrep()
+
+
+// "import" with `@ts-ignore`
+// @see error 2306 https://github.com/microsoft/TypeScript/blob/3fcd1b51a1e6b16d007b368229af03455c7d5794/src/compiler/diagnosticMessages.json#L1635
+// @ts-ignore
+import registerCypressGrep from '@cypress/grep'
+registerCypressGrep()
+```
+
+### Config file
+
+**optional:** load and register this module from the [config file](https://docs.cypress.io/guides/references/configuration#setupNodeEvents):
+
+```js
+// cypress.config.js
+{
+  e2e: {
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+  },
+  }
+}
+```
+
+Installing the plugin via `setupNodeEvents()` is required to enable the [grepFilterSpecs](#grepfilterspecs) feature.
+
+## Usage Overview
+
+You can filter tests to run using part of their title via `grep`, and via explicit tags via `grepTags` Cypress environment variables.
+
+Most likely you will pass these environment variables from the command line. For example, to only run tests with "login" in their title and tagged "smoke", you would run:
+
+Here are a few examples:
+
+```shell
+# run only the tests with "auth user" in the title
+$ npx cypress run --env grep="auth user"
+# run tests with "hello" or "auth user" in their titles
+# by separating them with ";" character
+$ npx cypress run --env grep="hello; auth user"
+# run tests tagged @fast
+$ npx cypress run --env grepTags=@fast
+# run only the tests tagged "smoke"
+# that have "login" in their titles
+$ npx cypress run --env grep=login,grepTags=smoke
+# only run the specs that have any tests with "user" in their titles
+$ npx cypress run --env grep=user,grepFilterSpecs=true
+# only run the specs that have any tests tagged "@smoke"
+$ npx cypress run --env grepTags=@smoke,grepFilterSpecs=true
+# run only tests that do not have any tags
+# and are not inside suites that have any tags
+$ npx cypress run --env grepUntagged=true
+```
+
+You can use any way to modify the environment values `grep` and `grepTags`, except the run-time `Cypress.env('grep')` (because it is too late at run-time). You can set the `grep` value in the `cypress.json` file to run only tests with the substring `viewport` in their names
+
+```json
+{
+  "env": {
+    "grep": "viewport"
+  }
+}
+```
+
+You can also set the `env.grep` object in the plugin file, but remember to return the changed config object:
+
+```js
+// cypress/plugin/index.js
+module.exports = (on, config) => {
+  config.env.grep = 'viewport'
+  return config
+}
+```
+
+You can also set the grep and grepTags from the DevTools console while running Cypress in the interactive mode `cypress open`, see [DevTools Console section](#devtools-console).
+
+## Filter by test title
+
+```shell
+# run all tests with "hello" in their title
+$ npx cypress run --env grep=hello
+# run all tests with "hello world" in their title
+$ npx cypress run --env grep="hello world"
+```
+
+### OR substring matching
+
+You can pass multiple title substrings to match separating them with `;` character. Each substring is trimmed.
+
+```shell
+# run all tests with "hello world" or "auth user" in their title
+$ npx cypress run --env grep="hello world; auth user"
+```
+
+### Test suites
+
+The filter is also applied to the "describe" blocks. In that case, the tests look up if any of their outer suites are enabled.
+
+```js
+describe('block for config', () => {
+  it('should run', () => {})
+
+  it('should also work', () => {})
+})
+```
+
+```
+# run any tests in the blocks including "config"
+--env grep=config
+```
+
+**Note:** global function `describe` and `context` are aliases and both supported by this plugin.
+
+### Invert filter
+
+```shell
+# run all tests WITHOUT "hello world" in their title
+$ npx cypress run --env grep="-hello world"
+# run tests with "hello", but without "world" in the titles
+$ npx cypress run --env grep="hello; -world"
+```
+
+**Note:** Inverted title filter is not compatible with the `grepFilterSpecs` option
+
+## Filter with tags
+
+You can select tests to run or skip using tags by passing `--env grepTags=...` value.
+
+```
+# enable the tests with tag "one" or "two"
+--env grepTags="one two"
+# enable the tests with both tags "one" and "two"
+--env grepTags="one+two"
+# enable the tests with "hello" in the title and tag "smoke"
+--env grep=hello,grepTags=smoke
+```
+
+If you can pass commas in the environment variable `grepTags`, you can use `,` to separate the tags
+
+```
+# enable the tests with tag "one" or "two"
+CYPRESS_grepTags=one,two npx cypress run
+```
+
+### Tags in the test config object
+
+Cypress tests can have their own [test config object](https://on.cypress.io/configuration#Test-Configuration), and when using this plugin you can put the test tags there, either as a single tag string or as an array of tags.
+
+```js
+it('works as an array', { tags: ['config', 'some-other-tag'] }, () => {
+  expect(true).to.be.true
+})
+
+it('works as a string', { tags: 'config' }, () => {
+  expect(true).to.be.true
+})
+```
+
+You can run both of these tests using `--env grepTags=config` string.
+
+### AND tags
+
+Use `+` to require both tags to be present
+
+```
+--env grepTags=@smoke+@fast
+```
+
+### OR tags
+
+You can run tests that match one tag or another using spaces. Make sure to quote the grep string!
+
+```
+# run tests with tags "@slow" or "@critical" in their names
+--env grepTags='@slow @critical'
+```
+
+### Inverted tags
+
+You can skip running the tests with specific tag using the invert option: prefix the tag with the character `-`.
+
+```
+# do not run any tests with tag "@slow"
+--env grepTags=-@slow
+```
+
+If you want to run all tests with tag `@slow` but without tag `@smoke`:
+
+```
+--env grepTags=@slow+-@smoke
+```
+
+**Note:** Inverted tag filter is not compatible with the `grepFilterSpecs` option
+
+### NOT tags
+
+You can skip running the tests with specific tag, even if they have a tag that should run, using the not option: prefix the tag with `--`.
+
+Note this is the same as appending `+-<tag to never run>` to each tag. May be useful with large number of tags.
+
+If you want to run tests with tags `@slow` or `@regression` but without tag `@smoke`
+
+```
+--env grepTags='@slow @regression --@smoke'
+```
+
+which is equivalent to
+
+```
+--env grepTags='@slow+-@smoke @regression+-@smoke'
+```
+
+### Tags in test suites
+
+The tags are also applied to the "describe" blocks. In that case, the tests look up if any of their outer suites are enabled.
+
+```js
+describe('block with config tag', { tags: '@smoke' }, () => {})
+```
+
+```
+# run any tests in the blocks having "@smoke" tag
+--env grepTags=@smoke
+# skip any blocks with "@smoke" tag
+--env grepTags=-@smoke
+```
+
+See the [cypress/integration/describe-tags-spec.js](./cypress/integration/describe-tags-spec.js) file.
+
+**Note:** global function `describe` and `context` are aliases and both supported by this plugin.
+
+### Grep untagged tests
+
+Sometimes you want to run only the tests without any tags, and these tests are inside the describe blocks without any tags.
+
+```
+$ npx cypress run --env grepUntagged=true
+```
+
+## Pre-filter specs (grepFilterSpecs)
+
+By default, when using `grep` and `grepTags` all specs are executed, and inside each the filters are applied. This can be very wasteful, if only a few specs contain the `grep` in the test titles. Thus when doing the positive `grep`, you can pre-filter specs using the `grepFilterSpecs=true` parameter.
+
+```
+# filter all specs first, and only run the ones with
+# suite or test titles containing the string "it loads"
+$ npx cypress run --env grep="it loads",grepFilterSpecs=true
+# filter all specs files, only run the specs with a tag "@smoke"
+$ npx cypress run --env grepTags=@smoke,grepFilterSpecs=true
+```
+
+**Note 1:** this requires installing this plugin in your project's plugin file, see the [Install](#install).
+
+**Note 2:** the `grepFilterSpecs` option is only compatible with the positive `grep` and `grepTags` options, not with the negative (inverted) "-..." filter.
+
+**Note 3:** if there are no files remaining after filtering, the plugin prints a warning and leaves all files unchanged to avoid the test runner erroring with "No specs found".
+
+**Tip:** you can set this environment variable in the [config file](https://docs.cypress.io/guides/references/configuration) file to enable it by default and skip using the environment variable:
+
+```js
+{
+  "env": {
+    "grepFilterSpecs": true
+  }
+}
+```
+
+## Omit filtered tests (grepOmitFiltered)
+
+By default, all filtered tests are made _pending_ using `it.skip` method. If you want to completely omit them, pass the environment variable `grepOmitFiltered=true`.
+
+Pending filtered tests
+
+```
+cypress run --env grep="works 2"
+```
+
+![Pending tests](./images/includes-pending.png)
+
+Omit filtered tests
+
+```
+cypress run --env grep="works 2",grepOmitFiltered=true
+```
+
+![Only running tests remaining](./images/omit-pending.png)
+
+**Tip:** you can set this environment variable in the config file (usually `cypress.config.js`) file to enable it by default and skip using the environment variable:
+
+```json
+{
+  "env": {
+    "grepOmitFiltered": true
+  }
+}
+```
+
+## Disable grep
+
+If you specify the `grep` parameters the [config file](https://docs.cypress.io/guides/references/configuration), you can disable it from the command line
+
+```
+$ npx cypress run --env grep=,grepTags=,burn=
+```
+
+## Burn (repeat) tests
+
+You can burn the filtered tests to make sure they are flake-free
+
+```
+npx cypress run --env grep="hello world",burn=5
+```
+
+You can pass the number of times to run the tests via environment name `burn` or `grepBurn` or `grep-burn`. Note, if a lot of tests match the grep and grep tags, a lot of tests will be burnt!
+
+If you do not specify the "grep" or "grep tags" option, the "burn" will repeat _every_ test.
+
+## TypeScript support
+
+Because the Cypress test config object type definition does not have the `tags` property we are using above, the TypeScript linter will show an error. Just add an ignore comment above the test:
+
+```js
+// @ts-ignore
+it('runs on deploy', { tags: 'smoke' }, () => {
+  ...
+})
+```
+
+This package comes with [src/index.d.ts](./src/index.d.ts) definition file that adds the property `tags` to the Cypress test overrides interface. Include this file in your specs or TS config settings. For example, you can load it using a reference comment
+
+```js
+// cypress/integration/my-spec.js
+/// <reference types="@cypress/grep" />
+```
+
+If you have `tsconfig.json` file, add this library to the types list
+
+```json
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["es5", "dom"],
+    "types": ["cypress", "@cypress/grep"]
+  },
+  "include": ["**/*.ts"]
+}
+```
+
+## General advice
+
+- keep it simple.
+- I like using `@` as tag prefix to make the tags searchable
+
+```js
+// ✅ good practice
+describe('auth', { tags: '@critical' }, () => ...)
+it('works', { tags: '@smoke' }, () => ...)
+it('works quickly', { tags: ['@smoke', '@fast'] }, () => ...)
+
+// 🚨 NOT GOING TO WORK
+// ERROR: treated as a single tag,
+// probably want an array instead
+it('works', { tags: '@smoke @fast' }, () => ...)
+```
+
+Grepping the tests
+
+```shell
+# run the tests by title
+$ npx cypress run --env grep="works quickly"
+# run all tests tagged @smoke
+$ npx cypress run --env grepTags=@smoke
+# run all tests except tagged @smoke
+$ npx cypress run --env grepTags=-@smoke
+# run all tests that have tag @fast but do not have tag @smoke
+$ npx cypress run --env grepTags=@fast+-@smoke
+```
+
+I would run all tests by default, and grep tests from the command line. For example, I could run the smoke tests first using grep plugin, and if the smoke tests pass, then run all the tests. See the video [How I organize pull request workflows by running smoke tests first](https://www.youtube.com/watch?v=SFW7Ecj5TNE) and its [pull request workflow file](https://github.com/bahmutov/cypress-grep-example/blob/main/.github/workflows/pr.yml).
+
+## DevTools console
+
+You can set the grep string from the DevTools Console. This plugin adds method `Cypress.grep` and `Cypress.grepTags` to set the grep strings and restart the tests
+
+```js
+// filter tests by title substring
+Cypress.grep('hello world')
+// run filtered tests 100 times
+Cypress.grep('hello world', null, 100)
+// filter tests by tag string
+// in this case will run tests with tag @smoke OR @fast
+Cypress.grep(null, '@smoke @fast')
+// run tests tagged @smoke AND @fast
+Cypress.grep(null, '@smoke+@fast')
+// run tests with title containing "hello" and tag @smoke
+Cypress.grep('hello', '@smoke')
+// run tests with title containing "hello" and tag @smoke 10 times
+Cypress.grep('hello', '@smoke', 10)
+```
+
+- to remove the grep strings enter `Cypress.grep()`
+
+## Debugging
+
+When debugging a problem, first make sure you are using the expected version of this plugin, as some features might be only available in the [later releases](https://github.com/cypress-io/cypress-grep/releases).
+
+```
+# get the cypress-grep version using NPM
+$ npm ls cypress-grep
+...
+└── cypress-grep@2.10.1
+# get the cypress-grep version using Yarn
+$ yarn why cypress-grep
+...
+=> Found "cypress-grep@2.10.1"
+info Has been hoisted to "cypress-grep"
+info This module exists because it's specified in "devDependencies".
+...
+```
+
+Second, make sure you are passing the values to the plugin correctly by inspecting the "Settings" tab in the Cypress Desktop GUI screen. You should see the values you have passed in the "Config" object under the `env` property. For example, if I start the Test Runner with
+
+```text
+$ npx cypress open --env grep=works,grepFilterTests=true
+```
+
+Then I expect to see the grep string and the "filter tests" flag in the `env` object.
+
+![Values in the env object](./images/config.png)
+
+### Log messages
+
+This module uses [debug](https://github.com/visionmedia/debug#readme) to log verbose messages. You can enable the debug messages in the plugin file (runs when discovering specs to filter), and inside the browser to see how it determines which tests to run and to skip. When opening a new issue, please provide the debug logs from the plugin (if any) and from the browser.
+
+### Debugging in the plugin
+
+Start Cypress with the environment variable `DEBUG=cypress-grep`. You will see a few messages from this plugin in the terminal output:
+
+```
+$ DEBUG=cypress-grep npx cypress run --env grep=works,grepFilterSpecs=true
+cypress-grep: tests with "works" in their names
+cypress-grep: filtering specs using "works" in the title
+  cypress-grep Cypress config env object: { grep: 'works', grepFilterSpecs: true }
+  ...
+  cypress-grep found 1 spec files +5ms
+  cypress-grep [ 'spec.js' ] +0ms
+  cypress-grep spec file spec.js +5ms
+  cypress-grep suite and test names: [ 'hello world', 'works', 'works 2 @tag1',
+    'works 2 @tag1 @tag2', 'works @tag2' ] +0ms
+  cypress-grep found "works" in 1 specs +0ms
+  cypress-grep [ 'spec.js' ] +0ms
+```
+
+### Debugging in the browser
+
+To enable debug console messages in the browser, from the DevTools console set `localStorage.debug='cypress-grep'` and run the tests again.
+
+![Debug messages](./images/debug.png)
+
+To see how to debug this plugin, watch the video [Debug cypress-grep Plugin](https://youtu.be/4YMAERddHYA).
+
+## Examples
+
+- [cypress-grep-example](https://github.com/bahmutov/cypress-grep-example)
+- [todo-graphql-example](https://github.com/bahmutov/todo-graphql-example)
+
+## See also
+
+- [cypress-select-tests](https://github.com/bahmutov/cypress-select-tests)
+- [cypress-skip-test](https://github.com/cypress-io/cypress-skip-test)
+
+## Migration guide
+
+### from v1 to v2
+
+In v2 we have separated grepping by part of the title string from tags.
+
+**v1**
+
+```
+--env grep="one two"
+```
+
+The above scenario was confusing - did you want to find all tests with title containing "one two" or did you want to run tests tagged `one` or `two`?
+
+**v2**
+
+```
+# enable the tests with string "one two" in their titles
+--env grep="one two"
+# enable the tests with tag "one" or "two"
+--env grepTags="one two"
+# enable the tests with both tags "one" and "two"
+--env grepTags="one+two"
+# enable the tests with "hello" in the title and tag "smoke"
+--env grep=hello,grepTags=smoke
+```
+
+### from v2 to v3
+
+Version >= 3 of cypress-grep _only_ supports Cypress >= 10.
+
+## Small Print
+
+License: MIT - do anything with the code, but don't blame me if it does not work.
+
+Support: if you find any problems with this module, email / tweet /
+[open issue](https://github.com/bahmutov/cy-grep/issues) on Github
diff --git a/cypress.config.js b/cypress.config.js
new file mode 100644
index 0000000..eca9ad3
--- /dev/null
+++ b/cypress.config.js
@@ -0,0 +1,15 @@
+const { defineConfig } = require('cypress')
+
+module.exports = defineConfig({
+  e2e: {
+    defaultCommandTimeout: 1000,
+    setupNodeEvents (on, config) {
+      require('./src/plugin')(config)
+
+      return config
+    },
+    specPattern: '**/spec.js',
+  },
+  fixturesFolder: false,
+  video: false,
+})
diff --git a/cypress/e2e/before-spec.js b/cypress/e2e/before-spec.js
new file mode 100644
index 0000000..facc7b4
--- /dev/null
+++ b/cypress/e2e/before-spec.js
@@ -0,0 +1,17 @@
+describe('Runs before and beforeEach when first test is skipped', () => {
+  let count = 0
+
+  before(() => {
+    count++
+  })
+
+  beforeEach(() => {
+    count++
+  })
+
+  it('A', { tags: ['@core'] }, () => {})
+
+  it('B', { tags: ['@core', '@staging'] }, () => {
+    expect(count).to.equal(2)
+  })
+})
diff --git a/cypress/e2e/burn-spec.js b/cypress/e2e/burn-spec.js
new file mode 100644
index 0000000..22229d4
--- /dev/null
+++ b/cypress/e2e/burn-spec.js
@@ -0,0 +1,9 @@
+/// <reference types="cypress" />
+
+// if we specify just the burn parameter
+// then this test will be repeated N times
+describe('burning a test N times', () => {
+  it('repeats', () => {})
+
+  it('second test', () => {})
+})
diff --git a/cypress/e2e/config-spec.js b/cypress/e2e/config-spec.js
new file mode 100644
index 0000000..d3b9e9c
--- /dev/null
+++ b/cypress/e2e/config-spec.js
@@ -0,0 +1,7 @@
+// @ts-check
+/// <reference types="cypress" />
+describe('tests that use config object', () => {
+  it('still works @config', { baseUrl: 'http://localhost:8000' }, () => {
+    expect(Cypress.config('baseUrl')).to.equal('http://localhost:8000')
+  })
+})
diff --git a/cypress/e2e/config-tags-spec.js b/cypress/e2e/config-tags-spec.js
new file mode 100644
index 0000000..b0c6b82
--- /dev/null
+++ b/cypress/e2e/config-tags-spec.js
@@ -0,0 +1,16 @@
+// @ts-check
+/// <reference path="../../src/index.d.ts" />
+describe('tags in the config object', () => {
+  it('works as an array', { tags: ['config', 'some-other-tag'] }, () => {
+    expect(true).to.be.true
+  })
+
+  it('works as a string', { tags: 'config' }, () => {
+    expect(true).to.be.true
+  })
+
+  it('does not use tags', () => {
+    // so it fails
+    expect(true).to.be.false
+  })
+})
diff --git a/cypress/e2e/describe-tags-spec.js b/cypress/e2e/describe-tags-spec.js
new file mode 100644
index 0000000..b3ee573
--- /dev/null
+++ b/cypress/e2e/describe-tags-spec.js
@@ -0,0 +1,23 @@
+/// <reference path="../../src/index.d.ts" />
+
+// @ts-check
+
+describe('block with no tags', () => {
+  it('inside describe 1', () => {})
+
+  it('inside describe 2', () => {})
+})
+
+describe('block with tag smoke', { tags: '@smoke' }, () => {
+  it('inside describe 3', () => {})
+
+  it('inside describe 4', () => {})
+})
+
+describe('block without any tags', () => {
+  // note the parent suite has no tags
+  // so this test should run when using --env grepTags=@smoke
+  it('test with tag smoke', { tags: '@smoke' }, () => {})
+})
+
+it('is a test outside any suites', () => {})
diff --git a/cypress/e2e/each-spec.js b/cypress/e2e/each-spec.js
new file mode 100644
index 0000000..5dfc712
--- /dev/null
+++ b/cypress/e2e/each-spec.js
@@ -0,0 +1,11 @@
+/// <reference types="cypress" />
+
+// https://github.com/bahmutov/cypress-each
+import 'cypress-each'
+
+describe('tests that use .each work', () => {
+  // creating tests dynamically works with "cypress-grep"
+  it.each([1, 2, 3])('test for %d', (x) => {
+    expect(x).to.be.oneOf([1, 2, 3])
+  })
+})
diff --git a/cypress/e2e/inherits-tag-spec.js b/cypress/e2e/inherits-tag-spec.js
new file mode 100644
index 0000000..ee805e2
--- /dev/null
+++ b/cypress/e2e/inherits-tag-spec.js
@@ -0,0 +1,7 @@
+/// <reference types="cypress" />
+
+describe('Screen A', { tags: ['@sanity', '@screen-a'] }, () => {
+  it('loads', { tags: ['@screen-b'] }, () => {
+    // do something that eventually sends the page to screen b.
+  })
+})
diff --git a/cypress/e2e/multiple-registrations.js b/cypress/e2e/multiple-registrations.js
new file mode 100644
index 0000000..1a73d67
--- /dev/null
+++ b/cypress/e2e/multiple-registrations.js
@@ -0,0 +1,10 @@
+/// <reference types="cypress" />
+
+// register the plugin multiple times
+// to simulate including from support and spec files
+// https://github.com/cypress-io/cypress-grep/issues/59
+require('../../src/support')()
+require('../../src/support')()
+require('../../src/support')()
+
+it('hello world', () => {})
diff --git a/cypress/e2e/nested-describe-spec.js b/cypress/e2e/nested-describe-spec.js
new file mode 100644
index 0000000..a06a781
--- /dev/null
+++ b/cypress/e2e/nested-describe-spec.js
@@ -0,0 +1,18 @@
+/// <reference path="../../src/index.d.ts" />
+
+// @ts-check
+describe('grand', () => {
+  context('outer', { tags: '@smoke' }, () => {
+    describe('inner', () => {
+      it('runs', () => {})
+    })
+  })
+})
+
+describe('top', { tags: '@smoke' }, () => {
+  describe('middle', () => {
+    context('bottom', { tags: ['@integration', '@fast'] }, () => {
+      it('runs too', () => {});
+    })
+  })
+})
diff --git a/cypress/e2e/omit-and-skip-spec.js b/cypress/e2e/omit-and-skip-spec.js
new file mode 100644
index 0000000..4c3a029
--- /dev/null
+++ b/cypress/e2e/omit-and-skip-spec.js
@@ -0,0 +1,10 @@
+/// <reference path="../../src/index.d.ts" />
+
+// @ts-check
+describe('Page', () => {
+  describe('List', { tags: ['@us1'] }, () => {
+    it.skip('first test', () => {})
+    it('second test', () => {})
+    it('third test', () => {})
+  })
+})
diff --git a/cypress/e2e/skip-spec.js b/cypress/e2e/skip-spec.js
new file mode 100644
index 0000000..0aa964e
--- /dev/null
+++ b/cypress/e2e/skip-spec.js
@@ -0,0 +1,9 @@
+/// <reference types="cypress" />
+describe('tests that use .skip', () => {
+  // use a template literal
+  it(`works`, () => {})
+
+  it.skip('is pending', () => {})
+
+  it.skip('is pending again', () => {})
+})
diff --git a/cypress/e2e/spec.js b/cypress/e2e/spec.js
new file mode 100644
index 0000000..fd4df2f
--- /dev/null
+++ b/cypress/e2e/spec.js
@@ -0,0 +1,11 @@
+/// <reference types="cypress" />
+
+it('hello world', () => {})
+
+it('works', () => {})
+
+it('works 2 @tag1', { tags: '@tag1' }, () => {})
+
+it('works 2 @tag1 @tag2', { tags: ['@tag1', '@tag2'] }, () => {})
+
+it('works @tag2', { tags: '@tag2' }, () => {})
diff --git a/cypress/e2e/specify-spec.js b/cypress/e2e/specify-spec.js
new file mode 100644
index 0000000..9651d32
--- /dev/null
+++ b/cypress/e2e/specify-spec.js
@@ -0,0 +1,13 @@
+/// <reference types="cypress" />
+
+// specify is the same as it()
+
+specify('hello world', () => {})
+
+specify('works', () => {})
+
+specify('works 2 @tag1', { tags: '@tag1' }, () => {})
+
+specify('works 2 @tag1 @tag2', { tags: ['@tag1', '@tag2'] }, () => {})
+
+specify('works @tag2', { tags: '@tag2' }, () => {})
diff --git a/cypress/e2e/tags/test1.spec.js b/cypress/e2e/tags/test1.spec.js
new file mode 100644
index 0000000..5296790
--- /dev/null
+++ b/cypress/e2e/tags/test1.spec.js
@@ -0,0 +1,5 @@
+/// <reference types="cypress" />
+
+it('Test 1', { tags: ['smoke', 'regression'] }, () => {
+  expect(true).to.be.true
+})
diff --git a/cypress/e2e/tags/test2.spec.js b/cypress/e2e/tags/test2.spec.js
new file mode 100644
index 0000000..3044c0e
--- /dev/null
+++ b/cypress/e2e/tags/test2.spec.js
@@ -0,0 +1,5 @@
+/// <reference types="cypress" />
+
+it('Test 2', { tags: ['high', 'smoke'] }, () => {
+  expect(true).to.be.true
+})
diff --git a/cypress/e2e/tags/test3.spec.js b/cypress/e2e/tags/test3.spec.js
new file mode 100644
index 0000000..7579c45
--- /dev/null
+++ b/cypress/e2e/tags/test3.spec.js
@@ -0,0 +1,5 @@
+/// <reference types="cypress" />
+
+it('Test 3', { tags: ['smoke'] }, () => {
+  expect(true).to.be.true
+})
diff --git a/cypress/e2e/this-spec.js b/cypress/e2e/this-spec.js
new file mode 100644
index 0000000..2b788e2
--- /dev/null
+++ b/cypress/e2e/this-spec.js
@@ -0,0 +1,11 @@
+/// <reference types="cypress" />
+describe('this context', () => {
+  beforeEach(() => {
+    cy.wrap(42).as('life')
+  })
+
+  it('preserves the test context', function () {
+    expect(this).to.be.an('object')
+    expect(this.life).to.equal(42)
+  })
+})
diff --git a/cypress/e2e/ts-spec.ts b/cypress/e2e/ts-spec.ts
new file mode 100644
index 0000000..3b9fb62
--- /dev/null
+++ b/cypress/e2e/ts-spec.ts
@@ -0,0 +1,29 @@
+describe('TypeScript spec', () => {
+  it('works', () => {
+    type Person = {
+      name: string
+    }
+
+    const person: Person = {
+      name: 'Joe',
+    }
+
+    cy.wrap(person).should('have.property', 'name', 'Joe')
+  })
+
+  it('loads', () => {
+    const n: number = 1
+    cy.wrap(n).should('eq', 1)
+  })
+
+  it('loads interfaces', () => {
+    interface Person {
+      name: string
+    }
+
+    const p: Person = {
+      name: 'Joe',
+    }
+    cy.wrap(p).should('have.property', 'name', 'Joe')
+  })
+})
diff --git a/cypress/e2e/unit.js b/cypress/e2e/unit.js
new file mode 100644
index 0000000..0ade87a
--- /dev/null
+++ b/cypress/e2e/unit.js
@@ -0,0 +1,439 @@
+/// <reference types="cypress" />
+
+import {
+  parseGrep,
+  parseTitleGrep,
+  parseFullTitleGrep,
+  parseTagsGrep,
+  shouldTestRun,
+  shouldTestRunTags,
+  shouldTestRunTitle,
+} from '../../src/utils'
+
+describe('utils', () => {
+  context('parseTitleGrep', () => {
+    it('grabs the positive title', () => {
+      const parsed = parseTitleGrep('hello w')
+
+      expect(parsed).to.deep.equal({
+        title: 'hello w',
+        invert: false,
+      })
+    })
+
+    it('trims the string', () => {
+      const parsed = parseTitleGrep('   hello w  ')
+
+      expect(parsed).to.deep.equal({
+        title: 'hello w',
+        invert: false,
+      })
+    })
+
+    it('inverts the string', () => {
+      const parsed = parseTitleGrep('-hello w')
+
+      expect(parsed).to.deep.equal({
+        title: 'hello w',
+        invert: true,
+      })
+    })
+
+    it('trims the inverted the string', () => {
+      const parsed = parseTitleGrep('  -hello w  ')
+
+      expect(parsed).to.deep.equal({
+        title: 'hello w',
+        invert: true,
+      })
+    })
+
+    it('returns null for undefined input', () => {
+      const parsed = parseTitleGrep()
+
+      expect(parsed).to.equal(null)
+    })
+  })
+
+  context('parseFullTitleGrep', () => {
+    it('returns list of title greps', () => {
+      const parsed = parseFullTitleGrep('hello; one; -two')
+
+      expect(parsed).to.deep.equal([
+        { title: 'hello', invert: false },
+        { title: 'one', invert: false },
+        { title: 'two', invert: true },
+      ])
+    })
+  })
+
+  context('parseTagsGrep', () => {
+    it('parses AND tags', () => {
+      // run only the tests with all 3 tags
+      const parsed = parseTagsGrep('@tag1+@tag2+@tag3')
+
+      expect(parsed).to.deep.equal([
+        // single OR part
+        [
+          // with 3 AND parts
+          { tag: '@tag1', invert: false },
+          { tag: '@tag2', invert: false },
+          { tag: '@tag3', invert: false },
+        ],
+      ])
+    })
+
+    it('handles dashes in the tag', () => {
+      const parsed = parseTagsGrep('@smoke+@screen-b')
+
+      expect(parsed).to.deep.equal([
+        [
+          { tag: '@smoke', invert: false },
+          { tag: '@screen-b', invert: false },
+        ],
+      ])
+    })
+
+    it('parses OR tags spaces', () => {
+      // run tests with tag1 OR tag2 or tag3
+      const parsed = parseTagsGrep('@tag1 @tag2 @tag3')
+
+      expect(parsed).to.deep.equal([
+        [{ tag: '@tag1', invert: false }],
+        [{ tag: '@tag2', invert: false }],
+        [{ tag: '@tag3', invert: false }],
+      ])
+    })
+
+    it('parses OR tags commas', () => {
+      // run tests with tag1 OR tag2 or tag3
+      const parsed = parseTagsGrep('@tag1,@tag2,@tag3')
+
+      expect(parsed).to.deep.equal([
+        [{ tag: '@tag1', invert: false }],
+        [{ tag: '@tag2', invert: false }],
+        [{ tag: '@tag3', invert: false }],
+      ])
+    })
+
+    it('parses inverted tag', () => {
+      const parsed = parseTagsGrep('-@tag1')
+
+      expect(parsed).to.deep.equal([[{ tag: '@tag1', invert: true }]])
+    })
+
+    it('parses tag1 but not tag2 with space', () => {
+      const parsed = parseTagsGrep('@tag1 -@tag2')
+
+      expect(parsed).to.deep.equal([
+        [{ tag: '@tag1', invert: false }],
+        [{ tag: '@tag2', invert: true }],
+      ])
+    })
+
+    it('forgives extra spaces', () => {
+      const parsed = parseTagsGrep('  @tag1   -@tag2 ')
+
+      expect(parsed).to.deep.equal([
+        [{ tag: '@tag1', invert: false }],
+        [{ tag: '@tag2', invert: true }],
+      ])
+    })
+
+    it('parses tag1 but not tag2 with comma', () => {
+      const parsed = parseTagsGrep('@tag1,-@tag2')
+
+      expect(parsed).to.deep.equal([
+        [{ tag: '@tag1', invert: false }],
+        [{ tag: '@tag2', invert: true }],
+      ])
+    })
+
+    it('filters out empty tags', () => {
+      const parsed = parseTagsGrep(',, @tag1,-@tag2,, ,, ,')
+
+      expect(parsed).to.deep.equal([
+        [{ tag: '@tag1', invert: false }],
+        [{ tag: '@tag2', invert: true }],
+      ])
+    })
+
+    // TODO: would need to change the tokenizer
+    it.skip('parses tag1 but not tag2', () => {
+      const parsed = parseTagsGrep('@tag1-@tag2')
+
+      expect(parsed).to.deep.equal([
+        [
+          { tag: '@tag1', invert: false },
+          { tag: '@tag2', invert: true },
+        ],
+      ])
+    })
+
+    it('allows all tags to be inverted', () => {
+      const parsed = parseTagsGrep('--@tag1,--@tag2')
+
+      expect(parsed).to.deep.equal([
+        [{ tag: '@tag1', invert: true }, { tag: '@tag2', invert: true }],
+      ])
+    })
+  })
+
+  context('parseGrep', () => {
+    // no need to exhaustively test the parsing
+    // since we want to confirm it works via test names
+    // and not through the implementation details of
+    // the parsed object
+
+    it('creates just the title grep', () => {
+      const parsed = parseGrep('hello w')
+
+      expect(parsed).to.deep.equal({
+        title: [
+          {
+            title: 'hello w',
+            invert: false,
+          },
+        ],
+        tags: [],
+      })
+    })
+
+    it('creates object from the grep string only', () => {
+      const parsed = parseGrep('hello w')
+
+      expect(parsed).to.deep.equal({
+        title: [
+          {
+            title: 'hello w',
+            invert: false,
+          },
+        ],
+        tags: [],
+      })
+
+      // check how the parsed grep works against specific tests
+      expect(shouldTestRun(parsed, 'hello w')).to.equal(true)
+      expect(shouldTestRun(parsed, 'hello no')).to.equal(false)
+    })
+
+    it('matches one of the titles', () => {
+      // also should trim each title
+      const parsed = parseGrep('  hello w; work 2  ')
+
+      expect(parsed).to.deep.equal({
+        title: [
+          {
+            title: 'hello w',
+            invert: false,
+          },
+          {
+            title: 'work 2',
+            invert: false,
+          },
+        ],
+        tags: [],
+      })
+
+      // check how the parsed grep works against specific tests
+      expect(shouldTestRun(parsed, 'hello w')).to.equal(true)
+      expect(shouldTestRun(parsed, 'this work 2 works')).to.equal(true)
+      expect(shouldTestRun(parsed, 'hello no')).to.equal(false)
+    })
+
+    it('creates object from the grep string and tags', () => {
+      const parsed = parseGrep('hello w', '@tag1+@tag2+@tag3')
+
+      expect(parsed).to.deep.equal({
+        title: [
+          {
+            title: 'hello w',
+            invert: false,
+          },
+        ],
+        tags: [
+          // single OR part
+          [
+            // with 3 AND parts
+            { tag: '@tag1', invert: false },
+            { tag: '@tag2', invert: false },
+            { tag: '@tag3', invert: false },
+          ],
+        ],
+      })
+
+      // check how the parsed grep works against specific tests
+      expect(shouldTestRun(parsed, 'hello w'), 'needs tags').to.equal(false)
+      expect(shouldTestRun(parsed, 'hello no')).to.equal(false)
+      // not every tag is present
+      expect(shouldTestRun(parsed, ['@tag1', '@tag2'])).to.equal(false)
+      expect(shouldTestRun(parsed, ['@tag1', '@tag2', '@tag3'])).to.equal(true)
+      expect(
+        shouldTestRun(parsed, ['@tag1', '@tag2', '@tag3', '@tag4']),
+      ).to.equal(true)
+
+      // title matches, but tags do not
+      expect(shouldTestRun(parsed, 'hello w', ['@tag1', '@tag2'])).to.equal(
+        false,
+      )
+
+      // tags and title match
+      expect(
+        shouldTestRun(parsed, 'hello w', ['@tag1', '@tag2', '@tag3']),
+      ).to.equal(true)
+    })
+  })
+
+  context('shouldTestRunTags', () => {
+    // when the user types "used" string
+    // and the test has the given tags, make sure
+    // our parsing and decision logic computes the expected result
+    const shouldIt = (used, tags, expected) => {
+      const parsedTags = parseTagsGrep(used)
+
+      expect(
+        shouldTestRunTags(parsedTags, tags),
+        `"${used}" against "${tags}"`,
+      ).to.equal(expected)
+    }
+
+    it('handles AND tags', () => {
+      shouldIt('smoke+slow', ['fast', 'smoke'], false)
+      shouldIt('smoke+slow', ['mobile', 'smoke', 'slow'], true)
+      shouldIt('smoke+slow', ['slow', 'extra', 'smoke'], true)
+      shouldIt('smoke+slow', ['smoke'], false)
+    })
+
+    it('handles OR tags', () => {
+      // smoke OR slow
+      shouldIt('smoke slow', ['fast', 'smoke'], true)
+      shouldIt('smoke', ['mobile', 'smoke', 'slow'], true)
+      shouldIt('slow', ['slow', 'extra', 'smoke'], true)
+      shouldIt('smoke', ['smoke'], true)
+      shouldIt('smoke', ['slow'], false)
+    })
+
+    it('handles invert tag', () => {
+      // should not run - we are excluding the "slow"
+      shouldIt('smoke+-slow', ['smoke', 'slow'], false)
+      shouldIt('mobile+-slow', ['smoke', 'slow'], false)
+      shouldIt('smoke -slow', ['smoke', 'fast'], true)
+      shouldIt('-slow', ['smoke', 'slow'], false)
+      shouldIt('-slow', ['smoke'], true)
+      // no tags in the test
+      shouldIt('-slow', [], true)
+    })
+  })
+
+  context('shouldTestRun', () => {
+    // a little utility function to parse the given grep string
+    // and apply the first argument in shouldTestRun
+    const checkName = (grep, grepTags) => {
+      const parsed = parseGrep(grep, grepTags)
+
+      expect(parsed).to.be.an('object')
+
+      return (testName, testTags = []) => {
+        expect(testName, 'test title').to.be.a('string')
+        expect(testTags, 'test tags').to.be.an('array')
+
+        return shouldTestRun(parsed, testName, testTags)
+      }
+    }
+
+    it('simple tag', () => {
+      const parsed = parseGrep('@tag1')
+
+      expect(shouldTestRun(parsed, 'no tag1 here')).to.be.false
+      expect(shouldTestRun(parsed, 'has @tag1 in the name')).to.be.true
+    })
+
+    it('with invert title', () => {
+      const t = checkName('-hello')
+
+      expect(t('no greetings')).to.be.true
+      expect(t('has hello world')).to.be.false
+    })
+
+    it('with invert option', () => {
+      const t = checkName(null, '-@tag1')
+
+      expect(t('no tags here')).to.be.true
+      expect(t('has tag1', ['@tag1'])).to.be.false
+      expect(t('has other tags', ['@tag2'])).to.be.true
+    })
+
+    it('with AND option', () => {
+      const t = checkName('', '@tag1+@tag2')
+
+      expect(t('no tag1 here')).to.be.false
+      expect(t('has only @tag1', ['@tag1'])).to.be.false
+      expect(t('has only @tag2', ['@tag2'])).to.be.false
+      expect(t('has both tags', ['@tag1', '@tag2'])).to.be.true
+    })
+
+    it('with OR option', () => {
+      const t = checkName(null, '@tag1 @tag2')
+
+      expect(t('no tag1 here')).to.be.false
+      expect(t('has only @tag1 in the name', ['@tag1'])).to.be.true
+      expect(t('has only @tag2 in the name', ['@tag2'])).to.be.true
+      expect(t('has @tag1 and @tag2 in the name', ['@tag1', '@tag2'])).to.be
+      .true
+    })
+
+    it('OR with AND option', () => {
+      const t = checkName(null, '@tag1 @tag2+@tag3')
+
+      expect(t('no tag1 here')).to.be.false
+      expect(t('has only @tag1 in the name', ['@tag1'])).to.be.true
+      expect(t('has only @tag2 in the name', ['@tag2'])).to.be.false
+      expect(t('has only @tag2 in the name and also @tag3', ['@tag2', '@tag3']))
+      .to.be.true
+
+      expect(
+        t('has @tag1 and @tag2 and @tag3 in the name', [
+          '@tag1',
+          '@tag2',
+          '@tag3',
+        ]),
+      ).to.be.true
+    })
+
+    it('Multiple invert strings and a simple one', () => {
+      const t = checkName('-name;-hey;number')
+
+      expect(t('number should only be matches without a n-a-m-e')).to.be.true
+      expect(t('number can\'t be name')).to.be.false
+      expect(t('The man needs a name')).to.be.false
+      expect(t('number hey name')).to.be.false
+      expect(t('numbers hey name')).to.be.false
+      expect(t('number hsey nsame')).to.be.true
+      expect(t('This wont match')).to.be.false
+    })
+
+    it('Only inverted strings', () => {
+      const t = checkName('-name;-hey')
+
+      expect(t('I\'m matched')).to.be.true
+      expect(t('hey! I\'m not')).to.be.false
+      expect(t('My name is weird')).to.be.false
+    })
+  })
+
+  context('parseFullTitleGrep', () => {
+    const shouldIt = (search, testName, expected) => {
+      const parsed = parseFullTitleGrep(search)
+
+      expect(
+        shouldTestRunTitle(parsed, testName),
+        `"${search}" against title "${testName}"`,
+      ).to.equal(expected)
+    }
+
+    it('passes for substring', () => {
+      shouldIt('hello w', 'hello world', true)
+      shouldIt('-hello w', 'hello world', false)
+    })
+  })
+})
diff --git a/cypress/support/e2e.js b/cypress/support/e2e.js
new file mode 100644
index 0000000..739f20c
--- /dev/null
+++ b/cypress/support/e2e.js
@@ -0,0 +1,7 @@
+// @ts-check
+/// <reference types="cypress" />
+
+import cypressGrep from '../../src/support'
+// register the grep feature
+// https://github.com/cypress-io/cypress-grep
+cypressGrep()
\ No newline at end of file
diff --git a/cypress/tsconfig.json b/cypress/tsconfig.json
new file mode 100644
index 0000000..d6ad993
--- /dev/null
+++ b/cypress/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "compilerOptions": {
+    "types": ["cypress"]
+  },
+  "include": ["e2e/**/*.ts"]
+}
diff --git a/expects/README.md b/expects/README.md
new file mode 100644
index 0000000..61a360f
--- /dev/null
+++ b/expects/README.md
@@ -0,0 +1,3 @@
+Different JSON files with expected test statuses when running Cypress tests with different grep argument.
+
+Used via [cypress-expect](https://github.com/bahmutov/cypress-expect) with `--expect` option to run on CI to verify the correct tests were pending or passing.
diff --git a/expects/all-pending.json b/expects/all-pending.json
new file mode 100644
index 0000000..87005e8
--- /dev/null
+++ b/expects/all-pending.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "pending",
+  "works 2 @tag1": "pending",
+  "works 2 @tag1 @tag2": "pending",
+  "works @tag2": "pending"
+}
diff --git a/expects/before.json b/expects/before.json
new file mode 100644
index 0000000..cf306f5
--- /dev/null
+++ b/expects/before.json
@@ -0,0 +1,6 @@
+{
+  "Runs before and beforeEach when first test is skipped": {
+    "A": "pending",
+    "B": "passed"
+  }
+}
diff --git a/expects/burn-spec.json b/expects/burn-spec.json
new file mode 100644
index 0000000..c0b4021
--- /dev/null
+++ b/expects/burn-spec.json
@@ -0,0 +1,14 @@
+{
+  "burning a test N times": {
+    "repeats: burning 1 of 5": "pass",
+    "repeats: burning 2 of 5": "pass",
+    "repeats: burning 3 of 5": "pass",
+    "repeats: burning 4 of 5": "pass",
+    "repeats: burning 5 of 5": "pass",
+    "second test: burning 1 of 5": "pass",
+    "second test: burning 2 of 5": "pass",
+    "second test: burning 3 of 5": "pass",
+    "second test: burning 4 of 5": "pass",
+    "second test: burning 5 of 5": "pass"
+  }
+}
diff --git a/expects/config-spec.json b/expects/config-spec.json
new file mode 100644
index 0000000..12de586
--- /dev/null
+++ b/expects/config-spec.json
@@ -0,0 +1,5 @@
+{
+  "tests that use config object": {
+    "still works @config": "passed"
+  }
+}
diff --git a/expects/config-tags-spec.json b/expects/config-tags-spec.json
new file mode 100644
index 0000000..5c742cb
--- /dev/null
+++ b/expects/config-tags-spec.json
@@ -0,0 +1,7 @@
+{
+  "tags in the config object": {
+    "works as an array": "passed",
+    "works as a string": "passed",
+    "does not use tags": "pending"
+  }
+}
diff --git a/expects/describe-tags-invert-spec.json b/expects/describe-tags-invert-spec.json
new file mode 100644
index 0000000..e21542e
--- /dev/null
+++ b/expects/describe-tags-invert-spec.json
@@ -0,0 +1,14 @@
+{
+  "block with no tags": {
+    "inside describe 1": "passing",
+    "inside describe 2": "passing"
+  },
+  "block with tag smoke": {
+    "inside describe 3": "pending",
+    "inside describe 4": "pending"
+  },
+  "block without any tags": {
+    "test with tag smoke": "pending"
+  },
+  "is a test outside any suites": "passing"
+}
diff --git a/expects/describe-tags-spec-untagged.json b/expects/describe-tags-spec-untagged.json
new file mode 100644
index 0000000..e21542e
--- /dev/null
+++ b/expects/describe-tags-spec-untagged.json
@@ -0,0 +1,14 @@
+{
+  "block with no tags": {
+    "inside describe 1": "passing",
+    "inside describe 2": "passing"
+  },
+  "block with tag smoke": {
+    "inside describe 3": "pending",
+    "inside describe 4": "pending"
+  },
+  "block without any tags": {
+    "test with tag smoke": "pending"
+  },
+  "is a test outside any suites": "passing"
+}
diff --git a/expects/describe-tags-spec.json b/expects/describe-tags-spec.json
new file mode 100644
index 0000000..2e15bf7
--- /dev/null
+++ b/expects/describe-tags-spec.json
@@ -0,0 +1,14 @@
+{
+  "block with no tags": {
+    "inside describe 1": "pending",
+    "inside describe 2": "pending"
+  },
+  "block with tag smoke": {
+    "inside describe 3": "passed",
+    "inside describe 4": "passed"
+  },
+  "block without any tags": {
+    "test with tag smoke": "passed"
+  },
+  "is a test outside any suites": "pending"
+}
diff --git a/expects/each-spec.json b/expects/each-spec.json
new file mode 100644
index 0000000..6dd5736
--- /dev/null
+++ b/expects/each-spec.json
@@ -0,0 +1,7 @@
+{
+  "tests that use .each work": {
+    "test for 1": "pending",
+    "test for 2": "passing",
+    "test for 3": "pending"
+  }
+}
diff --git a/expects/grep-filter-specs-tag.json b/expects/grep-filter-specs-tag.json
new file mode 100644
index 0000000..63a106f
--- /dev/null
+++ b/expects/grep-filter-specs-tag.json
@@ -0,0 +1,28 @@
+{
+  "block with no tags": {
+    "inside describe 1": "pending",
+    "inside describe 2": "pending"
+  },
+  "block with tag smoke": {
+    "inside describe 3": "passing",
+    "inside describe 4": "passing"
+  },
+  "block without any tags": {
+    "test with tag smoke": "passing"
+  },
+  "is a test outside any suites": "pending",
+  "grand": {
+    "outer": {
+      "inner": {
+        "runs": "passing"
+      }
+    }
+  },
+  "top": {
+    "middle": {
+      "bottom": {
+        "runs too": "passing"
+      }
+    }
+  }
+}
diff --git a/expects/grep-filter-specs.json b/expects/grep-filter-specs.json
new file mode 100644
index 0000000..5fd27bf
--- /dev/null
+++ b/expects/grep-filter-specs.json
@@ -0,0 +1,14 @@
+{
+  "is a test outside any suites": "passing",
+  "block with no tags": {
+    "inside describe 1": "pending",
+    "inside describe 2": "pending"
+  },
+  "block with tag smoke": {
+    "inside describe 3": "pending",
+    "inside describe 4": "pending"
+  },
+  "block without any tags": {
+    "test with tag smoke": "pending"
+  }
+}
diff --git a/expects/grep-untagged.json b/expects/grep-untagged.json
new file mode 100644
index 0000000..f8b91c5
--- /dev/null
+++ b/expects/grep-untagged.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "passing",
+  "works": "passing",
+  "works 2 @tag1": "pending",
+  "works 2 @tag1 @tag2": "pending",
+  "works @tag2": "pending"
+}
diff --git a/expects/hello-burn.json b/expects/hello-burn.json
new file mode 100644
index 0000000..58bf7c6
--- /dev/null
+++ b/expects/hello-burn.json
@@ -0,0 +1,9 @@
+{
+  "hello world: burning 1 of 3": "passed",
+  "hello world: burning 2 of 3": "passed",
+  "hello world: burning 3 of 3": "passed",
+  "works": "pending",
+  "works 2 @tag1": "pending",
+  "works 2 @tag1 @tag2": "pending",
+  "works @tag2": "pending"
+}
diff --git a/expects/hello-or-works-2.json b/expects/hello-or-works-2.json
new file mode 100644
index 0000000..f1d0722
--- /dev/null
+++ b/expects/hello-or-works-2.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "passed",
+  "works": "pending",
+  "works 2 @tag1": "passed",
+  "works 2 @tag1 @tag2": "passed",
+  "works @tag2": "pending"
+}
diff --git a/expects/hello.json b/expects/hello.json
new file mode 100644
index 0000000..c25d99c
--- /dev/null
+++ b/expects/hello.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "passed",
+  "works": "pending",
+  "works 2 @tag1": "pending",
+  "works 2 @tag1 @tag2": "pending",
+  "works @tag2": "pending"
+}
diff --git a/expects/inherits-tag-spec.json b/expects/inherits-tag-spec.json
new file mode 100644
index 0000000..1280057
--- /dev/null
+++ b/expects/inherits-tag-spec.json
@@ -0,0 +1,5 @@
+{
+  "Screen A": {
+    "loads": "passed"
+  }
+}
diff --git a/expects/invert-tag1.json b/expects/invert-tag1.json
new file mode 100644
index 0000000..dbef7dc
--- /dev/null
+++ b/expects/invert-tag1.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "passing",
+  "works": "passing",
+  "works 2 @tag1": "pending",
+  "works 2 @tag1 @tag2": "pending",
+  "works @tag2": "passing"
+}
diff --git a/expects/multiple-registrations.json b/expects/multiple-registrations.json
new file mode 100644
index 0000000..7a56ff7
--- /dev/null
+++ b/expects/multiple-registrations.json
@@ -0,0 +1,5 @@
+{
+  "hello world: burning 1 of 3": "passed",
+  "hello world: burning 2 of 3": "passed",
+  "hello world: burning 3 of 3": "passed"
+}
diff --git a/expects/nested-describe-inheriting-names-spec.json b/expects/nested-describe-inheriting-names-spec.json
new file mode 100644
index 0000000..3b406af
--- /dev/null
+++ b/expects/nested-describe-inheriting-names-spec.json
@@ -0,0 +1,16 @@
+{
+  "grand": {
+    "outer": {
+      "inner": {
+        "runs": "pending"
+      }
+    }
+  },
+  "top": {
+    "middle": {
+      "bottom": {
+        "runs too": "passing"
+      }
+    }
+  }
+}
diff --git a/expects/nested-describe-inheriting-tags-spec.json b/expects/nested-describe-inheriting-tags-spec.json
new file mode 100644
index 0000000..3b406af
--- /dev/null
+++ b/expects/nested-describe-inheriting-tags-spec.json
@@ -0,0 +1,16 @@
+{
+  "grand": {
+    "outer": {
+      "inner": {
+        "runs": "pending"
+      }
+    }
+  },
+  "top": {
+    "middle": {
+      "bottom": {
+        "runs too": "passing"
+      }
+    }
+  }
+}
diff --git a/expects/nested-describe-spec.json b/expects/nested-describe-spec.json
new file mode 100644
index 0000000..990270c
--- /dev/null
+++ b/expects/nested-describe-spec.json
@@ -0,0 +1,16 @@
+{
+  "grand": {
+    "outer": {
+      "inner": {
+        "runs": "passing"
+      }
+    }
+  },
+  "top": {
+    "middle": {
+      "bottom": {
+        "runs too": "passing"
+      }
+    }
+  }
+}
diff --git a/expects/no-hello-no-works2.json b/expects/no-hello-no-works2.json
new file mode 100644
index 0000000..65a2cf8
--- /dev/null
+++ b/expects/no-hello-no-works2.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "passed",
+  "works 2 @tag1": "pending",
+  "works 2 @tag1 @tag2": "pending",
+  "works @tag2": "passed"
+}
diff --git a/expects/no-hello.json b/expects/no-hello.json
new file mode 100644
index 0000000..c70c9c6
--- /dev/null
+++ b/expects/no-hello.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "passed",
+  "works 2 @tag1": "passed",
+  "works 2 @tag1 @tag2": "passed",
+  "works @tag2": "passed"
+}
diff --git a/expects/number1.json b/expects/number1.json
new file mode 100644
index 0000000..9032d53
--- /dev/null
+++ b/expects/number1.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "pending",
+  "works 2 @tag1": "passed",
+  "works 2 @tag1 @tag2": "passed",
+  "works @tag2": "pending"
+}
diff --git a/expects/omit-and-skip.json b/expects/omit-and-skip.json
new file mode 100644
index 0000000..1021529
--- /dev/null
+++ b/expects/omit-and-skip.json
@@ -0,0 +1,9 @@
+{
+  "Page": {
+    "List": {
+      "first test": "pending",
+      "second test": "passed",
+      "third test": "passed"
+    }
+  }
+}
diff --git a/expects/omit-filtered.json b/expects/omit-filtered.json
new file mode 100644
index 0000000..c123168
--- /dev/null
+++ b/expects/omit-filtered.json
@@ -0,0 +1,4 @@
+{
+  "works 2 @tag1": "passed",
+  "works 2 @tag1 @tag2": "passed"
+}
diff --git a/expects/pending.json b/expects/pending.json
new file mode 100644
index 0000000..72bbd91
--- /dev/null
+++ b/expects/pending.json
@@ -0,0 +1,7 @@
+{
+  "tests that use .skip": {
+    "works": "pending",
+    "is pending": "pending",
+    "is pending again": "pending"
+  }
+}
diff --git a/expects/specify.json b/expects/specify.json
new file mode 100644
index 0000000..9032d53
--- /dev/null
+++ b/expects/specify.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "pending",
+  "works 2 @tag1": "passed",
+  "works 2 @tag1 @tag2": "passed",
+  "works @tag2": "pending"
+}
diff --git a/expects/tag1-and-tag2.json b/expects/tag1-and-tag2.json
new file mode 100644
index 0000000..ba8712a
--- /dev/null
+++ b/expects/tag1-and-tag2.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "pending",
+  "works 2 @tag1": "pending",
+  "works 2 @tag1 @tag2": "passed",
+  "works @tag2": "pending"
+}
diff --git a/expects/tag1-without-tag2.json b/expects/tag1-without-tag2.json
new file mode 100644
index 0000000..9b6c08b
--- /dev/null
+++ b/expects/tag1-without-tag2.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "pending",
+  "works 2 @tag1": "passed",
+  "works 2 @tag1 @tag2": "pending",
+  "works @tag2": "pending"
+}
diff --git a/expects/tag1.json b/expects/tag1.json
new file mode 100644
index 0000000..9032d53
--- /dev/null
+++ b/expects/tag1.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "pending",
+  "works 2 @tag1": "passed",
+  "works 2 @tag1 @tag2": "passed",
+  "works @tag2": "pending"
+}
diff --git a/expects/tag2.json b/expects/tag2.json
new file mode 100644
index 0000000..471c7ad
--- /dev/null
+++ b/expects/tag2.json
@@ -0,0 +1,6 @@
+{
+  "hello world": "pending",
+  "works": "pending",
+  "works 2 @tag1": "pending",
+  "works 2 @tag1 @tag2": "passed"
+}
diff --git a/expects/tags-and.json b/expects/tags-and.json
new file mode 100644
index 0000000..84c4a52
--- /dev/null
+++ b/expects/tags-and.json
@@ -0,0 +1,5 @@
+{
+  "Test 1": "pending",
+  "Test 2": "passing",
+  "Test 3": "pending"
+}
diff --git a/expects/tags-or-filter.json b/expects/tags-or-filter.json
new file mode 100644
index 0000000..260fd0c
--- /dev/null
+++ b/expects/tags-or-filter.json
@@ -0,0 +1,4 @@
+{
+  "Test 1": "passing",
+  "Test 2": "passing"
+}
diff --git a/expects/tags-or.json b/expects/tags-or.json
new file mode 100644
index 0000000..d9a758d
--- /dev/null
+++ b/expects/tags-or.json
@@ -0,0 +1,5 @@
+{
+  "Test 1": "passing",
+  "Test 2": "passing",
+  "Test 3": "passing"
+}
diff --git a/expects/test-npm-module.js b/expects/test-npm-module.js
new file mode 100644
index 0000000..0abade8
--- /dev/null
+++ b/expects/test-npm-module.js
@@ -0,0 +1,31 @@
+// https://github.com/cypress-io/cypress-grep/issues/41
+// shows how to pass grep parameters using Cypress NPM Module API
+// https://on.cypress.io/module-api
+const cypress = require('cypress')
+
+cypress
+.run({
+  env: {
+    grep: 'works',
+    grepTags: '@tag2',
+  },
+})
+.then((results) => {
+  // TODO use cypress-expects to compare the test results
+  if (results.totalTests !== 5) {
+    console.error('expected 5 tests total, got %d', results.totalTests)
+    process.exit(1)
+  }
+
+  if (results.totalPassed !== 2) {
+    console.error('expected 2 tests passed, got %d', results.totalPassed)
+    process.exit(1)
+  }
+
+  if (results.totalPending !== 3) {
+    console.error('expected 3 tests pending, got %d', results.totalPending)
+    process.exit(1)
+  }
+
+  console.log(results.runs[0])
+})
diff --git a/expects/this-spec.json b/expects/this-spec.json
new file mode 100644
index 0000000..c07f53b
--- /dev/null
+++ b/expects/this-spec.json
@@ -0,0 +1,7 @@
+{
+  "this context": {
+    "preserves the test context: burning 1 of 3": "passed",
+    "preserves the test context: burning 2 of 3": "passed",
+    "preserves the test context: burning 3 of 3": "passed"
+  }
+}
diff --git a/expects/ts-spec.json b/expects/ts-spec.json
new file mode 100644
index 0000000..60c2597
--- /dev/null
+++ b/expects/ts-spec.json
@@ -0,0 +1,6 @@
+{
+  "TypeScript spec": {
+    "loads": "passing",
+    "loads interfaces": "passing"
+  }
+}
diff --git a/expects/works-2.json b/expects/works-2.json
new file mode 100644
index 0000000..aee1ddd
--- /dev/null
+++ b/expects/works-2.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "pending",
+  "works 2 @tag1": "passing",
+  "works 2 @tag1 @tag2": "passing",
+  "works @tag2": "pending"
+}
diff --git a/expects/works-and-tag1.json b/expects/works-and-tag1.json
new file mode 100644
index 0000000..aee1ddd
--- /dev/null
+++ b/expects/works-and-tag1.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "pending",
+  "works": "pending",
+  "works 2 @tag1": "passing",
+  "works 2 @tag1 @tag2": "passing",
+  "works @tag2": "pending"
+}
diff --git a/expects/works-hello-no-2.json b/expects/works-hello-no-2.json
new file mode 100644
index 0000000..8572a0d
--- /dev/null
+++ b/expects/works-hello-no-2.json
@@ -0,0 +1,7 @@
+{
+  "hello world": "passed",
+  "works": "passed",
+  "works 2 @tag1": "pending",
+  "works 2 @tag1 @tag2": "pending",
+  "works @tag2": "pending"
+}
diff --git a/images/config.png b/images/config.png
new file mode 100644
index 0000000..3370c6f
Binary files /dev/null and b/images/config.png differ
diff --git a/images/debug.png b/images/debug.png
new file mode 100644
index 0000000..9e4b179
Binary files /dev/null and b/images/debug.png differ
diff --git a/images/includes-pending.png b/images/includes-pending.png
new file mode 100644
index 0000000..335681c
Binary files /dev/null and b/images/includes-pending.png differ
diff --git a/images/omit-pending.png b/images/omit-pending.png
new file mode 100644
index 0000000..ffa07bc
Binary files /dev/null and b/images/omit-pending.png differ
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..c2828ec
--- /dev/null
+++ b/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "@bahmutov/cy-grep",
+  "version": "0.0.0-development",
+  "description": "Filter Cypress tests using title or tags",
+  "main": "src/support.js",
+  "scripts": {
+    "cy:run": "cypress run --config specPattern='**/unit.js'",
+    "cy:open": "cypress open --e2e -b electron --config specPattern='**/unit.js'"
+  },
+  "dependencies": {
+    "debug": "^4.3.2",
+    "find-test-names": "^1.19.0",
+    "globby": "^11.0.4"
+  },
+  "devDependencies": {
+    "cypress": "12.1.0",
+    "cypress-each": "^1.11.0",
+    "cypress-expect": "^2.5.3",
+    "typescript": "^4.7.4"
+  },
+  "peerDependencies": {
+    "cypress": ">=10"
+  },
+  "files": [
+    "src"
+  ],
+  "types": "src/index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bahmutov/cy-grep.git"
+  },
+  "homepage": "https://github.com/bahmutov/cy-grep",
+  "author": "Gleb Bahmutov <gleb.bahmutov@gmail.com>",
+  "bugs": {
+    "url": "https://github.com/bahmutov/cy-grep/issues"
+  },
+  "keywords": [
+    "cypress",
+    "grep"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}
diff --git a/src/index.d.ts b/src/index.d.ts
new file mode 100644
index 0000000..8410b98
--- /dev/null
+++ b/src/index.d.ts
@@ -0,0 +1,31 @@
+/// <reference types="cypress" />
+
+declare namespace Cypress {
+  interface SuiteConfigOverrides {
+    /**
+     * List of tags for this suite
+     * @example a single tag
+     *  describe('block with config tag', { tags: '@smoke' }, () => {})
+     * @example multiple tags
+     *  describe('block with config tag', { tags: ['@smoke', '@slow'] }, () => {})
+     */
+    tags?: string | string[]
+  }
+
+  // specify additional properties in the TestConfig object
+  // in our case we will add "tags" property
+  interface TestConfigOverrides {
+    /**
+     * List of tags for this test
+     * @example a single tag
+     *  it('logs in', { tags: '@smoke' }, () => { ... })
+     * @example multiple tags
+     *  it('works', { tags: ['@smoke', '@slow'] }, () => { ... })
+     */
+    tags?: string | string[]
+  }
+
+  interface Cypress {
+    grep?: (grep?: string, tags?: string, burn?: string) => void
+  }
+}
diff --git a/src/plugin.js b/src/plugin.js
new file mode 100644
index 0000000..ddd3572
--- /dev/null
+++ b/src/plugin.js
@@ -0,0 +1,156 @@
+const debug = require('debug')('cypress-grep')
+const globby = require('globby')
+const { getTestNames } = require('find-test-names')
+const fs = require('fs')
+const { version } = require('../package.json')
+const { parseGrep, shouldTestRun } = require('./utils')
+
+/**
+ * Prints the cypress-grep environment values if any.
+ * @param {Cypress.ConfigOptions} config
+ */
+function cypressGrepPlugin (config) {
+  if (!config || !config.env) {
+    return config
+  }
+
+  const { env } = config
+
+  if (!config.specPattern) {
+    throw new Error(
+      'Incompatible versions detected, cypress-grep 3.0.0+ requires Cypress 10.0.0+',
+    )
+  }
+
+  debug('cypress-grep plugin version %s', version)
+  debug('Cypress config env object: %o', env)
+
+  const grep = env.grep ? String(env.grep) : undefined
+
+  if (grep) {
+    console.log('cypress-grep: tests with "%s" in their names', grep.trim())
+  }
+
+  const grepTags = env.grepTags || env['grep-tags']
+
+  if (grepTags) {
+    console.log('cypress-grep: filtering using tag(s) "%s"', grepTags)
+    const parsedGrep = parseGrep(null, grepTags)
+
+    debug('parsed grep tags %o', parsedGrep.tags)
+  }
+
+  const grepBurn = env.grepBurn || env['grep-burn'] || env.burn
+
+  if (grepBurn) {
+    console.log('cypress-grep: running filtered tests %d times', grepBurn)
+  }
+
+  const grepUntagged = env.grepUntagged || env['grep-untagged']
+
+  if (grepUntagged) {
+    console.log('cypress-grep: running untagged tests')
+  }
+
+  const omitFiltered = env.grepOmitFiltered || env['grep-omit-filtered']
+
+  if (omitFiltered) {
+    console.log('cypress-grep: will omit filtered tests')
+  }
+
+  const { specPattern, excludeSpecPattern } = config
+  const integrationFolder = env.grepIntegrationFolder || process.cwd()
+
+  const grepFilterSpecs = env.grepFilterSpecs === true
+
+  if (grepFilterSpecs) {
+    debug('specPattern', specPattern)
+    debug('excludeSpecPattern', excludeSpecPattern)
+    debug('integrationFolder', integrationFolder)
+    const specFiles = globby.sync(specPattern, {
+      cwd: integrationFolder,
+      ignore: excludeSpecPattern,
+      absolute: true,
+    })
+
+    debug('found %d spec files', specFiles.length)
+    debug('%o', specFiles)
+    let greppedSpecs = []
+
+    if (grep) {
+      console.log('cypress-grep: filtering specs using "%s" in the title', grep)
+      const parsedGrep = parseGrep(grep)
+
+      debug('parsed grep %o', parsedGrep)
+      greppedSpecs = specFiles.filter((specFile) => {
+        const text = fs.readFileSync(specFile, { encoding: 'utf8' })
+
+        try {
+          const names = getTestNames(text)
+          const testAndSuiteNames = names.suiteNames.concat(names.testNames)
+
+          debug('spec file %s', specFile)
+          debug('suite and test names: %o', testAndSuiteNames)
+
+          return testAndSuiteNames.some((name) => {
+            const shouldRun = shouldTestRun(parsedGrep, name)
+
+            return shouldRun
+          })
+        } catch (err) {
+          debug(err.message)
+          debug(err.stack)
+          console.error('Could not determine test names in file: %s', specFile)
+          console.error('Will run it to let the grep filter the tests')
+
+          return true
+        }
+      })
+
+      debug('found grep "%s" in %d specs', grep, greppedSpecs.length)
+      debug('%o', greppedSpecs)
+    } else if (grepTags) {
+      const parsedGrep = parseGrep(null, grepTags)
+
+      debug('parsed grep tags %o', parsedGrep)
+      greppedSpecs = specFiles.filter((specFile) => {
+        const text = fs.readFileSync(specFile, { encoding: 'utf8' })
+
+        try {
+          const testInfo = getTestNames(text)
+
+          debug('spec file %s', specFile)
+          debug('test info: %o', testInfo.tests)
+
+          return testInfo.tests.some((info) => {
+            const shouldRun = shouldTestRun(parsedGrep, null, info.tags)
+
+            return shouldRun
+          })
+        } catch (err) {
+          console.error('Could not determine test names in file: %s', specFile)
+          console.error('Will run it to let the grep filter the tests')
+
+          return true
+        }
+      })
+
+      debug('found grep tags "%s" in %d specs', grepTags, greppedSpecs.length)
+      debug('%o', greppedSpecs)
+    }
+
+    if (greppedSpecs.length) {
+      config.specPattern = greppedSpecs
+    } else {
+      // hmm, we filtered out all specs, probably something is wrong
+      console.warn('grep and/or grepTags has eliminated all specs')
+      grep ? console.warn('grep: %s', grep) : null
+      grepTags ? console.warn('grepTags: %s', grepTags) : null
+      console.warn('Will leave all specs to run to filter at run-time')
+    }
+  }
+
+  return config
+}
+
+module.exports = cypressGrepPlugin
diff --git a/src/support.js b/src/support.js
new file mode 100644
index 0000000..5fd42b5
--- /dev/null
+++ b/src/support.js
@@ -0,0 +1,247 @@
+// @ts-check
+/// <reference path="./index.d.ts" />
+
+const { parseGrep, shouldTestRun } = require('./utils')
+// @ts-ignore
+const { version } = require('../package.json')
+const debug = require('debug')('@cypress/grep')
+
+debug.log = console.info.bind(console)
+
+// preserve the real "it" function
+const _it = it
+const _describe = describe
+
+/**
+ * Wraps the "it" and "describe" functions that support tags.
+ * @see https://github.com/cypress-io/cypress-grep
+ */
+function cypressGrep () {
+  /** @type {string} Part of the test title go grep */
+  let grep = Cypress.env('grep')
+
+  if (grep) {
+    grep = String(grep).trim()
+  }
+
+  /** @type {string} Raw tags to grep string */
+  const grepTags = Cypress.env('grepTags') || Cypress.env('grep-tags')
+
+  const burnSpecified =
+    Cypress.env('grepBurn') || Cypress.env('grep-burn') || Cypress.env('burn')
+
+  const grepUntagged =
+    Cypress.env('grepUntagged') || Cypress.env('grep-untagged')
+
+  if (!grep && !grepTags && !burnSpecified && !grepUntagged) {
+    // nothing to do, the user has no specified the "grep" string
+    debug('Nothing to grep, version %s', version)
+
+    return
+  }
+
+  /** @type {number} Number of times to repeat each running test */
+  const grepBurn =
+    Cypress.env('grepBurn') ||
+    Cypress.env('grep-burn') ||
+    Cypress.env('burn') ||
+    1
+
+  /** @type {boolean} Omit filtered tests completely */
+  const omitFiltered =
+    Cypress.env('grepOmitFiltered') || Cypress.env('grep-omit-filtered')
+
+  debug('grep %o', { grep, grepTags, grepBurn, omitFiltered, version })
+  if (!Cypress._.isInteger(grepBurn) || grepBurn < 1) {
+    throw new Error(`Invalid grep burn value: ${grepBurn}`)
+  }
+
+  const parsedGrep = parseGrep(grep, grepTags)
+
+  debug('parsed grep %o', parsedGrep)
+
+  // prevent multiple registrations
+  // https://github.com/cypress-io/cypress-grep/issues/59
+  if (it.name === 'itGrep') {
+    debug('already registered cypress-grep')
+
+    return
+  }
+
+  it = function itGrep (name, options, callback) {
+    if (typeof options === 'function') {
+      // the test has format it('...', cb)
+      callback = options
+      options = {}
+    }
+
+    if (!callback) {
+      // the pending test by itself
+      return _it(name, options)
+    }
+
+    let configTags = options && options.tags
+
+    if (typeof configTags === 'string') {
+      configTags = [configTags]
+    }
+
+    const nameToGrep = suiteStack
+    .map((item) => item.name)
+    .concat(name)
+    .join(' ')
+    const tagsToGrep = suiteStack
+    .flatMap((item) => item.tags)
+    .concat(configTags)
+    .filter(Boolean)
+
+    const shouldRun = shouldTestRun(
+      parsedGrep,
+      nameToGrep,
+      tagsToGrep,
+      grepUntagged,
+    )
+
+    if (tagsToGrep && tagsToGrep.length) {
+      debug(
+        'should test "%s" with tags %s run? %s',
+        name,
+        tagsToGrep.join(','),
+        shouldRun,
+      )
+    } else {
+      debug('should test "%s" run? %s', nameToGrep, shouldRun)
+    }
+
+    if (shouldRun) {
+      if (grepBurn > 1) {
+        // repeat the same test to make sure it is solid
+        return Cypress._.times(grepBurn, (k) => {
+          const fullName = `${name}: burning ${k + 1} of ${grepBurn}`
+
+          _it(fullName, options, callback)
+        })
+      }
+
+      return _it(name, options, callback)
+    }
+
+    if (omitFiltered) {
+      // omit the filtered tests completely
+      return
+    }
+
+    // skip tests without grep string in their names
+    return _it.skip(name, options, callback)
+  }
+
+  // list of "describe" suites for the current test
+  // when we encounter a new suite, we push it to the stack
+  // when the "describe" function exits, we pop it
+  // Thus a test can look up the tags from its parent suites
+  const suiteStack = []
+
+  describe = function describeGrep (name, options, callback) {
+    if (typeof options === 'function') {
+      // the block has format describe('...', cb)
+      callback = options
+      options = {}
+    }
+
+    const stackItem = { name }
+
+    suiteStack.push(stackItem)
+
+    if (!callback) {
+      // the pending suite by itself
+      const result = _describe(name, options)
+
+      suiteStack.pop()
+
+      return result
+    }
+
+    let configTags = options && options.tags
+
+    if (typeof configTags === 'string') {
+      configTags = [configTags]
+    }
+
+    if (!configTags || !configTags.length) {
+      // if the describe suite does not have explicit tags
+      // move on, since the tests inside can have their own tags
+      _describe(name, options, callback)
+      suiteStack.pop()
+
+      return
+    }
+
+    // when looking at the suite of the tests, I found
+    // that using the name is quickly becoming very confusing
+    // and thus we need to use the explicit tags
+    stackItem.tags = configTags
+    _describe(name, options, callback)
+    suiteStack.pop()
+
+    return
+  }
+
+  // overwrite "context" which is an alias to "describe"
+  context = describe
+
+  // overwrite "specify" which is an alias to "it"
+  specify = it
+
+  // keep the ".skip", ".only" methods the same as before
+  it.skip = _it.skip
+  it.only = _it.only
+  // preserve "it.each" method if found
+  // https://github.com/cypress-io/cypress-grep/issues/72
+  if (typeof _it.each === 'function') {
+    it.each = _it.each
+  }
+
+  describe.skip = _describe.skip
+  describe.only = _describe.only
+  if (typeof _describe.each === 'function') {
+    describe.each = _describe.each
+  }
+}
+
+function restartTests () {
+  setTimeout(() => {
+    window.top.document.querySelector('.reporter .restart').click()
+  }, 0)
+}
+
+if (!Cypress.grep) {
+  /**
+   * A utility method to set the grep and run the tests from
+   * the DevTools console. Restarts the test runner
+   * @example
+   *  // run only the tests with "hello w" in the title
+   *  Cypress.grep('hello w')
+   *  // runs only tests tagged both "@smoke" and "@fast"
+   *  Cypress.grep(null, '@smoke+@fast')
+   *  // runs the grepped tests 100 times
+   *  Cypress.grep('add items', null, 100)
+   *  // remove all current grep settings
+   *  // and run all tests
+   *  Cypress.grep()
+   * @see "Grep from DevTools console" https://github.com/cypress-io/cypress-grep#devtools-console
+   */
+  Cypress.grep = function grep (grep, tags, burn) {
+    Cypress.env('grep', grep)
+    Cypress.env('grepTags', tags)
+    Cypress.env('grepBurn', burn)
+    // remove any aliased values
+    Cypress.env('grep-tags', null)
+    Cypress.env('grep-burn', null)
+    Cypress.env('burn', null)
+
+    debug('set new grep to "%o" restarting tests', { grep, tags, burn })
+    restartTests()
+  }
+}
+
+module.exports = cypressGrep
diff --git a/src/utils.js b/src/utils.js
new file mode 100644
index 0000000..9ba2dc5
--- /dev/null
+++ b/src/utils.js
@@ -0,0 +1,187 @@
+// @ts-check
+
+// Universal code - should run in Node or in the browser
+
+/**
+ * Parses test title grep string.
+ * The string can have "-" in front of it to invert the match.
+ * @param {string} s Input substring of the test title
+ */
+function parseTitleGrep (s) {
+  if (!s || typeof s !== 'string') {
+    return null
+  }
+
+  s = s.trim()
+  if (s.startsWith('-')) {
+    return {
+      title: s.substring(1),
+      invert: true,
+    }
+  }
+
+  return {
+    title: s,
+    invert: false,
+  }
+}
+
+function parseFullTitleGrep (s) {
+  if (!s || typeof s !== 'string') {
+    return []
+  }
+
+  // separate each title
+  return s.split(';').map(parseTitleGrep)
+}
+
+/**
+ * Parses tags to grep for.
+ * @param {string} s Tags string like "@tag1+@tag2"
+ */
+function parseTagsGrep (s) {
+  if (!s) {
+    return []
+  }
+
+  const explicitNotTags = []
+
+  // top level split - using space or comma, each part is OR
+  const ORS = s
+  .split(/[ ,]/)
+  // remove any empty tags
+  .filter(Boolean)
+  .map((part) => {
+    // now every part is an AND
+    if (part.startsWith('--')) {
+      explicitNotTags.push({
+        tag: part.slice(2),
+        invert: true,
+      })
+
+      return
+    }
+
+    const parsed = part.split('+').map((tag) => {
+      if (tag.startsWith('-')) {
+        return {
+          tag: tag.slice(1),
+          invert: true,
+        }
+      }
+
+      return {
+        tag,
+        invert: false,
+      }
+    })
+
+    return parsed
+  })
+
+  // filter out undefined from explicit not tags
+  const ORS_filtered = ORS.filter((x) => x !== undefined)
+
+  if (explicitNotTags.length > 0) {
+    ORS_filtered.forEach((OR, index) => {
+      ORS_filtered[index] = OR.concat(explicitNotTags)
+    })
+
+    if (ORS_filtered.length === 0) {
+      ORS_filtered[ 0 ] = explicitNotTags
+    }
+  }
+
+  return ORS_filtered
+}
+
+function shouldTestRunTags (parsedGrepTags, tags = []) {
+  if (!parsedGrepTags.length) {
+    // there are no parsed tags to search for, the test should run
+    return true
+  }
+
+  // now the test has tags and the parsed tags are present
+
+  // top levels are OR
+  const onePartMatched = parsedGrepTags.some((orPart) => {
+    const everyAndPartMatched = orPart.every((p) => {
+      if (p.invert) {
+        return !tags.includes(p.tag)
+      }
+
+      return tags.includes(p.tag)
+    })
+    // console.log('every part matched %o?', orPart, everyAndPartMatched)
+
+    return everyAndPartMatched
+  })
+
+  // console.log('onePartMatched', onePartMatched)
+  return onePartMatched
+}
+
+function shouldTestRunTitle (parsedGrep, testName) {
+  if (!testName) {
+    // if there is no title, let it run
+    return true
+  }
+
+  if (!parsedGrep) {
+    return true
+  }
+
+  if (!Array.isArray(parsedGrep)) {
+    console.error('Invalid parsed title grep')
+    console.error(parsedGrep)
+    throw new Error('Expected title grep to be an array')
+  }
+
+  if (!parsedGrep.length) {
+    return true
+  }
+
+  const inverted = parsedGrep.filter((g) => g.invert)
+  const straight = parsedGrep.filter((g) => !g.invert)
+
+  return (
+    inverted.every((titleGrep) => !testName.includes(titleGrep.title)) &&
+    (!straight.length ||
+      straight.some((titleGrep) => testName.includes(titleGrep.title)))
+  )
+}
+
+// note: tags take precedence over the test name
+function shouldTestRun (parsedGrep, testName, tags = [], grepUntagged = false) {
+  if (grepUntagged) {
+    return !tags.length
+  }
+
+  if (Array.isArray(testName)) {
+    // the caller passed tags only, no test name
+    tags = testName
+    testName = undefined
+  }
+
+  return (
+    shouldTestRunTitle(parsedGrep.title, testName) &&
+    shouldTestRunTags(parsedGrep.tags, tags)
+  )
+}
+
+function parseGrep (titlePart, tags) {
+  return {
+    title: parseFullTitleGrep(titlePart),
+    tags: parseTagsGrep(tags),
+  }
+}
+
+module.exports = {
+  parseGrep,
+  parseTitleGrep,
+  parseFullTitleGrep,
+  parseTagsGrep,
+  shouldTestRun,
+  shouldTestRunTags,
+  shouldTestRunTitle,
+}