# Claude Code plugin

Source: https://docs.qualflare.com/docs/ai/claude-code · Last updated: 2026-10-27

Install the Qualflare plugin for Claude Code, run /qf-init once, then generate tests, run your suite, upload results and fix failures from the chat.

To use Qualflare from Claude Code, install the Qualflare plugin and run `/qf-init` once in your project; then `/qf-cover`, `/qf-run` and `/qf-fix` write tests, upload results with `qf <identifier> collect` and fix failures from the chat.

1. **`/qf-cover`** generates tests for the source files you changed, or for a whole file or directory with `--all`, and writes them after your approval.
2. **`/qf-run`** runs your test suite and uploads the results to Qualflare, or uploads a report you produced yourself.
3. **`/qf-fix`** reads the last run's failures, makes the smallest source fix and re-runs once.

An optional **coverage nudge** reminds you, after each response, when you edited source files but no tests.

## Before you begin

You need:

* [Claude Code](https://claude.ai/code), the CLI or desktop app.
* The Qualflare CLI (`qf`) on your PATH; see [Installation](https://docs.qualflare.com/docs/cli/installation).
* Node.js on your PATH, for the coverage nudge: its hook runs `node`.
* A Qualflare project and a project access token. Creating a token: (requires the Editor role or higher in the project). Uploading results doesn't need **Allow writes**. See [Access tokens](https://docs.qualflare.com/docs/api/access-tokens).

### Let your coding agent install qf

Optional: paste this prompt into Claude Code to install `qf` for you.

```
Install the Qualflare CLI (`qf`) on my machine.

1. Detect my operating system (macOS, Linux, or Windows) and CPU architecture
   (amd64 or arm64).
2. If Homebrew is available (macOS/Linux), run: brew install qualflare/tap/qf
3. Otherwise, open https://github.com/qualflare/qualflare-cli/releases/latest,
   download the asset matching my OS and architecture
   (qf_<version>_<os>_<arch>.tar.gz, or .zip on Windows), extract it, and move
   the `qf` binary into a directory on my PATH.
4. Run `qf version` to confirm the install succeeded.
```

## Install the plugin

### Step 1: Add the Qualflare marketplace

```
/plugin marketplace add Qualflare/qualflare-claude-code
```

### Step 2: Install the qualflare plugin

```
/plugin install qualflare@qualflare
```

The first command adds the Qualflare marketplace. The second installs the `qualflare` plugin from it, and the plugin stays installed in later sessions. Claude Code's [plugin documentation](https://code.claude.com/docs/en/discover-plugins) explains where a plugin can be installed.

You should see the `/qf-*` commands in Claude Code.

## Set up your project

### Step 1: Run qf-init from the project root

```
/qf-init
```

`/qf-init`:

1. detects your tech stack (languages, test frameworks and file counts) across the project, or each workspace in a monorepo;
2. confirms the detection with you and accepts corrections;
3. writes `.qualflare/test-state.md`, a context file that every later session reads at startup, so `/qf-cover` and `/qf-run` know your frameworks from the first message;
4. prints one `qf login <identifier>` line for each identifier that isn't logged in yet, and waits;
5. asks whether to turn on the coverage nudge, and writes `.qualflare/config.json`;
6. writes a Qualflare section between markers in your project's `CLAUDE.md`, so later sessions load the test context.

### Step 2: Log in from your own terminal

When `/qf-init` prints the `qf login <identifier>` lines, run each one in your own terminal, not in Claude Code:

```bash
qf login <identifier>
```

Then reply `done` in the chat, or `skip` to log in later.

`qf login` asks for the token at a hidden prompt. Never paste a token into the Claude Code chat: the chat is saved in the session transcript. If you did, revoke that token (or ask a Maintainer or Owner to) and create a new one. In CI, set `QF_TOKEN` instead and run `qf login <identifier> --force`.

### Step 3: Answer the coverage nudge question

Reply `yes` to turn the coverage nudge on, or `no` to leave it off.

Create tokens in your project's **Project Settings** > **Access Tokens** (`https://app.qualflare.com/project/<project-identifier>/settings/access-tokens`). The identifier is only a local name for the CLI, so it doesn't have to match the project. Uploading results doesn't need **Allow writes**. In a monorepo, each package gets its own identifier — run `qf login` once per package.

> **Tip:** `/qf-init` is safe to re-run at any time. It overwrites `.qualflare/test-state.md` with fresh detection results and re-prompts for hook preference and authentication.

## Generate, run and fix tests

Once setup is done, three commands cover the typical cycle.

### Generate tests for what you changed

After writing or editing source files:

```
/qf-cover
```

`/qf-cover` reads `.qualflare/test-state.md` to know your frameworks, finds the source files changed in this session that lack tests, proposes 2 to 5 test cases per function, and writes them after your approval. Pass a path or glob to scope it:

```
/qf-cover src/auth/login.ts
/qf-cover packages/api/src/**
```

By default `/qf-cover` only covers code you changed this session. Pass `--all` to cover an entire file or directory regardless of recent changes:

```
/qf-cover --all src/utils/
```

With `--all`, or in a project with no tests yet, it asks you to narrow the scope to 8 files or fewer per round.

### Run the suite and upload results

When you're ready to verify:

```
/qf-run
```

`/qf-run` runs your test suite and uploads the results to Qualflare via `qf <identifier> collect`. Pass a framework slug, such as `/qf-run jest`, or a package path, optionally followed by a slug, such as `/qf-run packages/web jest`, to run part of the suite. To upload a report you produced yourself, pass its path and slug: `/qf-run zap-report.json zap`. For a directory the slug is required, and without one `/qf-run` asks. For a file without a slug, it detects the format with `qf validate` and asks you to confirm. Cypress results upload as Mochawesome JSON, so add `mochawesome` as a dev dependency first. Uploads go to the environment named in `QF_ENVIRONMENT`, or to `development` when it is unset. Qualflare refuses an environment the project doesn't have.

```
/qf-run jest
/qf-run playwright
```

See [Environments](https://docs.qualflare.com/docs/runs/environments) for `QF_ENVIRONMENT`, and the [`/qf-run` reference](https://docs.qualflare.com/docs/ai/claude-code-reference#qf-run) for the frameworks it runs itself.

> **Warning:** `/qf-run` requires each identifier to be registered locally with `qf login` before it can upload. Run `/qf-doctor` if the upload fails.

### Fix failing tests

When tests are red:

```
/qf-fix
```

`/qf-fix` reads the last run's result files in `.qualflare/results/` and makes the smallest source change for each failing test. It edits source files, not tests: it skips a test whose assertion looks wrong. It then re-runs the affected frameworks once and reports what still fails; run `/qf-fix` again for another pass. It doesn't upload, so run `/qf-run` to send the new results to Qualflare. Pass a slug or path to scope which failures to fix:

```
/qf-fix jest
/qf-fix packages/api
```

## Turn on the coverage nudge

When the nudge is on, the plugin checks the session each time Claude finishes a response. If you edited a source file and no test file, and at least one of those edits was substantive, it prints:

```
🔍 Qualflare: 3 source file(s) changed without test updates. Run /qf-cover to add coverage.
```

It appears after each response until you edit a test file or turn it off with `/qf-hook off`. Config files, type definitions and trivial edits don't count. Turn it on or off at any time:

```
/qf-hook on
/qf-hook off
```

Or check the current setting with `/qf-hook` (no argument).

*Figure: The nudge appears after a response when source files changed without test updates.*

## Keep the state current

**Inspect current state:**

```
/qf-state
```

Shows detected frameworks, file counts, hook setting, and which CLI identifiers are configured locally.

**Refresh counts after adding tests:**

```
/qf-update
```

Faster than a full re-init — re-globs each framework row and updates `.qualflare/test-state.md` in place. Pass a slug or path to scope the refresh.

## Update the plugin

Pull the latest version at any time:

```
/plugin update qualflare
```

## Check that it works

* Run `/qf-state`: each identifier shows `configured`.
* After `/qf-run`, the summary ends with `Uploaded to Qualflare ✅`, and the launch appears in your project ([Analyze launch results](https://docs.qualflare.com/docs/runs/analyze-results)).

## Troubleshoot

Run `/qf-doctor` first when something feels wrong:

```
/qf-doctor
```

It checks the `qf` CLI, each package's login, the slug list, `config.json` and the hook, the age of `test-state.md`, file-count drift and your framework tooling. It reports ✅, ⚠️ or ❌ per check with a fix command; [`/qf-doctor`](https://docs.qualflare.com/docs/ai/claude-code-reference#qf-doctor) lists the checks and thresholds.

When an upload fails, `/qf-run` prints the CLI's error. [Upload errors](https://docs.qualflare.com/docs/ai/claude-code-reference#upload-errors) explains each exit code, and [CLI troubleshooting](https://docs.qualflare.com/docs/faq/troubleshooting) covers the CLI itself.

> **Tip:** Most issues are a missing CLI or a missing `qf login`. Fix what the doctor flags and re-run.

*Figure: The qf-doctor command checks the CLI, logins, state files and tooling, and suggests fixes.*

## How the plugin differs from Quo and MCP

The Qualflare plugin runs in Claude Code, where you write code, and drives the `qf` CLI on your machine to write tests, run them and upload results. [Quo](https://docs.qualflare.com/docs/ai/quo) is the agent inside the Qualflare web app: it works on the project's data, analyzing coverage, suggesting cases and generating steps. The [MCP server](https://docs.qualflare.com/docs/api/mcp) gives any MCP client, Claude Code included, a live connection to the project's data; the plugin uses no MCP connection.

## Related

* **Guides:** [Quo agent](https://docs.qualflare.com/docs/ai/quo) · [Connect a coding agent (MCP)](https://docs.qualflare.com/docs/api/mcp)
* **Reference:** [Claude Code plugin reference](https://docs.qualflare.com/docs/ai/claude-code-reference) · [Collect command](https://docs.qualflare.com/docs/cli/collect)
* **CLI and API:** [Installation](https://docs.qualflare.com/docs/cli/installation) · [Configuration](https://docs.qualflare.com/docs/cli/configuration) · [Access tokens](https://docs.qualflare.com/docs/api/access-tokens)