whoqol-toolkit

English · Português · Español

A plugin for Claude Code, Antigravity (agy) and Gemini CLI that scores and analyses WHOQOL quality-of-life questionnaires for publication. You give it the spreadsheet exported from Google Forms, REDCap, LimeSurvey, SPSS or Excel; it applies the official WHO scoring rules, checks data quality, estimates reliability and validity, compares groups and writes APA tables, figures and a draft of the methods and results sections.

All numbers come from a tested, deterministic Python package exposed as an MCP server. The agent's job is to ask the right questions, run the tools and interpret the output; it never computes scores itself.

The first instrument is the WHOQOL-BREF. The package is organised around an instrument registry so other WHOQOL instruments (WHOQOL-100, WHOQOL-OLD, WHOQOL-HIV-BREF, …) can be added without changing the analysis code.

Contents

• Overview

• Pipeline

• Analyses

• Security and confidentiality

• Installation

• Usage

• Data dictionary (optional)

• Parameters

• Outputs

• Limitations

• Development

• Citation

• License and authorship

Related MCP server: Talk2Data InsightGenius

Overview

Pipeline

flowchart LR
    A["Spreadsheet"] --> B["1 · whoqol_inspect<br/>item columns, language version,<br/>other variables"]
    M["Data dictionary<br/>(optional, pre-filled)"] -.-> C
    B --> C["2 · agree on the plan<br/>groups, covariates,<br/>reference values"]
    C --> D["3 · whoqol_analyze<br/>WHO scoring, quality,<br/>psychometrics, statistics"]
    D --> E["4 · interpretation<br/>by the agent, in the<br/>user's language"]
    D --> F["report.md · tables.docx<br/>results.xlsx · figures<br/>methods_results_pt/en/es.md"]

Analyses

Security and confidentiality

• Everything runs locally: the analysis code makes no network calls and the spreadsheet is never uploaded by the tool. The agent you use (Claude, Gemini) does see the tool outputs, which are aggregated statistics; avoid pasting raw rows into the chat.

• Questionnaire answers are personal health data (LGPD, GDPR). Use pseudonymised IDs, keep the files outside the repository (.gitignore excludes data/, *_whoqol/ and spreadsheets) and follow your ethics approval.

• Cell values and column names are treated as data, never as instructions to the agent.

• The scoring, statistics and reports come from tested code; the agent is told never to compute or invent numbers, norms or cut-offs (rules/AGENTS.md).

Installation

Requirements: uv and at least one host CLI.

git clone https://github.com/LaBiOmicS/whoqol-toolkit.git
cd whoqol-toolkit
./install.sh

install.sh syncs the Python environment, installs and validates the plugin in Antigravity (agy) and registers it in Claude Code through the local marketplace labiomics-whoqol.

Claude Code, directly from GitHub:

/plugin install whoqol-toolkit --marketplace LaBiOmicS/whoqol-toolkit

or, on older versions:

/plugin marketplace add LaBiOmicS/whoqol-toolkit
/plugin install whoqol-toolkit@labiomics-whoqol

Antigravity: agy plugin install /path/to/whoqol-toolkit && agy plugin enable whoqol-toolkit

Gemini CLI: gemini extensions install https://github.com/LaBiOmicS/whoqol-toolkit

Usage

Ask in any of the three languages, or use the /whoqol command:

/whoqol ~/data/qol_survey.xlsx compare the domains by sex and education
Analise esta planilha do WHOQOL-BREF e gere tabelas para publicação: ~/dados/whoqol.xlsx
Analiza la fiabilidad y validez del WHOQOL-BREF en ~/datos/encuesta.csv

The agent inspects the file, confirms the detected columns and the analysis plan with you, runs the analysis and interprets the results. Without an agent, use the CLI:

uv run whoqol inspect examples/sample_google_forms_pt.xlsx
uv run whoqol analyze examples/sample_google_forms_pt.xlsx -g Sexo -g Escolaridade -c Idade
uv run whoqol analyze examples/sample_numeric.csv -g Sexo --lang en --instrument-version pt
uv run whoqol guide interpretation

MCP tools

Data dictionary (optional)

A metadata file is never required: a spreadsheet with clear headers is analysed as it is. It helps when the data has coded variables (1/2 instead of labels), ordinal categories (education, income), missing codes (99, -9) or when you want to record the study context. whoqol_template writes it pre-filled with the detected roles; you review two sheets and pass it back with metadata=:

• variables – column, role (item, id, group, continuous, covariate, ignore), item, label, value labels (1=Female; 2=Male), level order, missing codes;

• study – population, design, country, administration mode.

Sheet and column names are accepted in Portuguese, English or Spanish. A variables/variaveis sheet inside the data workbook is read automatically.

Parameters

Outputs

Written to <file>_whoqol/ (or output_dir):

Limitations

• There are no official WHO cut-offs and no established minimal important difference; the tool reports distribution-based benchmarks (½ SD, MDC95). Normative values must come from a cited source.

• The built-in CFA uses maximum likelihood, which treats Likert items as continuous. For a psychometric paper, run the WLSMV script and test measurement invariance.

• Language-version detection needs text answers or question headers; with numeric data, state the version.

• Only the WHOQOL-BREF is implemented so far.

• Use of WHOQOL instruments must follow the WHO's terms; the toolkit does not distribute the questionnaire.

• Questionnaire answers are personal health data: keep them local and pseudonymised (see rules/AGENTS.md).

Development

uv sync --group dev
uv run pytest -q
uvx ruff check src tests examples
uv run python examples/generate_examples.py   # synthetic example data
claude plugin validate . && agy plugin validate . --strict

To add an instrument, create src/whoqol/instruments/<name>.py with an Instrument (items, reversed items, domains with minimum valid items, item texts and patterns in PT/EN/ES, language versions) and register it in instruments/__init__.py. Scoring, psychometrics, reports and the scoring guide follow from that definition.

Citation

@software{menegidio_whoqol_toolkit_2026,
  author  = {Menegidio, Fabiano Bezerra},
  title   = {whoqol-toolkit: scoring, psychometrics and publication-grade statistics for WHOQOL questionnaires},
  year    = {2026},
  version = {0.1.0},
  url     = {https://github.com/LaBiOmicS/whoqol-toolkit}
}

Also cite the instrument and the validated language version you used (see whoqol_guide("references")).

License and authorship

MIT © 2026 Prof. Dr. Fabiano Bezerra Menegidio — Laboratório de Bioinformática e Ciências Ômicas (LaBiOmicS), Universidade de Mogi das Cruzes (UMC).