ghqc is a Quality Control (QC) management system for data analysis workflows. It uses GitHub Issues as the unit of tracking: each file under QC gets a GitHub Issue, issues are grouped into Milestones, and the full QC lifecycle is managed through ghqc.
Available as both an interactive CLI and an embedded web UI.
flowchart TB
A([Create Issue]) --> B[Review File]
B --> C{Review Complete?}
C -- Changes Needed --> D[Comment with Diff]
D --> E[Implement Changes]
E --> B
C -- Approved --> F([Approve & Close Issue])
F -- Iterate for each file --> G([Close Milestone])
G --> H([Generate Record])
G --> I([Archive])
- Create — Open a GitHub Issue for a file, assign a checklist and reviewers.
- Review — The reviewer works through the checklist on GitHub, and optionally post a comment on the issue with a diff between their local, uncommitted changes and a commit.
- Comment — Post a comment on the issue linking two commits, with an optional diff and note, to document changes made in response to review feedback.
- Iterate — Repeat the review → comment cycle until the file is ready.
- Approve — Close the issue with an approval comment pinning the reviewed commit.
- Record — Generate a PDF summarizing the completed QC for a milestone.
- Archive — Bundle the files into a zip archive.
Each file under QC has a dedicated GitHub Issue. ghqc manages the full issue lifecycle:
| Command | Description |
|---|---|
ghqc issue create |
Create a new QC issue for a file |
ghqc issue comment |
Post a comment with commit diff to document changes made (author) |
ghqc issue review |
Post a review comment comparing working directory to a commit (reviewer) |
ghqc issue approve |
Approve the issue at a specific commit and close it |
ghqc issue unapprove |
Reopen an approved issue with a reason |
ghqc issue status |
Print the QC status, git status, and checklist progress |
ghqc issue rename |
Confirm a detected file rename and update the issue title |
Issues are grouped into Milestones for organizational purposes.
| Command | Description |
|---|---|
ghqc milestone status |
Tabular summary of all issues across selected milestones |
ghqc milestone record |
Generate a PDF QC record for selected milestones |
ghqc milestone archive |
Generate a zip archive of the record and associated files |
ghqc reads checklists, a logo, and options from a separate configuration repository.
| Command | Description |
|---|---|
ghqc configuration setup |
Clone the configuration repository |
ghqc configuration status |
Display configuration directory and available checklists |
ghqc can store GitHub tokens locally and show which authentication sources are available for the current repository host.
| Command | Description |
|---|---|
ghqc auth login |
Log in to a GitHub host and optionally store a token in ghqc |
ghqc auth logout |
Remove a token stored in the ghqc auth store |
ghqc auth status |
Display stored tokens and auth source resolution for the selected host |
ghqc auth token |
Print the resolved token for the selected host |
| Command | Description |
|---|---|
ghqc sitrep |
Print a situation report: binary version, repository info, auth status, and configuration status |
| Command | Description |
|---|---|
ghqc ui |
Start the embedded web UI server and open the browser, or print its resolved URL with ghqc ui url (ui feature) |
ghqc serve |
Start the REST API server without the embedded UI (api feature) |
Running ghqc ui serves an embedded React application. The UI provides:
- Status tab — Kanban board of all issues, grouped by QC status. Click the issue title to open GitHub, or click the rest of the card to open the in-app detail modal.
- Create tab — Wizard for creating new QC issues. Previous QC references can include an automatic diff comment, and queued issues plus saved custom checklists persist while switching tabs until refresh.
- Record tab — PDF record generation with file upload for context pages
- Archive tab — Archive generation
- Configuration tab — Configuration repo setup and status
The web UI also supports direct routes for each screen: /status, /create, /record, /archive, and /configuration. Opening / redirects to /status.
Use ghqc ui url to print the exact loopback URL the UI would use on the current machine without starting the server. If --port is omitted, the UI binds a random available port.
Install the latest GitHub Release to ~/.local/bin:
curl -fsSL https://raw.githubusercontent.com/a2-ai/ghqctoolkit/main/scripts/install.sh | bashInstall a specific release tag instead:
curl -fsSL https://raw.githubusercontent.com/a2-ai/ghqctoolkit/main/scripts/install.sh | bash -s -- v0.3.1-rc1Install the latest GitHub Release to %LOCALAPPDATA%\Programs\ghqc and add it to your user PATH:
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1To install a specific release tag:
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Version v0.3.1-rc1If you do not have the repository checked out locally, you can download and run the installer directly:
irm https://raw.githubusercontent.com/a2-ai/ghqctoolkit/main/scripts/install.ps1 | iexManual install:
- Download the latest
ghqc-<version>-x86_64-pc-windows-msvc.zipasset from GitHub Releases. - Extract it to
%LOCALAPPDATA%\Programs\ghqc. - Add
%LOCALAPPDATA%\Programs\ghqcto your userPATH. - Open a new PowerShell window and run
ghqc --version.
ghqc expects Git to be available on PATH, so install Git for Windows if it is not already present.
cargo build --features cli --releasecargo build --features cli,ui --releasecargo run --features cli,api -- serve --port 3104
cd ui && bun run devghqc requires a configuration repository providing checklists, a logo, and optional settings. See the configuration docs for full details.
Quick setup:
# Using environment variable
export GHQC_CONFIG_REPO=https://github.com/your-org/your-config-repo
ghqc configuration setup
# Or pass directly
ghqc configuration setup https://github.com/your-org/your-config-repoAn example configuration repository is available at a2-ai/ghqc.example_config_repo.