hermes-labs-ai/quick-gate-js

Experimental / work in progress: Kwik-E-Gate is under active development. Interfaces and behavior may change; evaluate it on your own repositories before relying on it.

Kwik-E-Gate is a free, local gate for coding agents. It runs the lint, test, build, and other commands your repository declares; chooses a fast or full path from the changed files and project policy; and records what actually ran. No daemon, API key, or model is required. An optional reviewer can add semantic judgment when one is available.

Quickstart

Requires Python 3.11+ and Git. Version 0.4.0 is not yet on PyPI, so install the current source:

python3 -m venv ~/.local/share/kwik-e-gate/venv
~/.local/share/kwik-e-gate/venv/bin/python -m pip install git+https://github.com/hermes-labs-ai/kwik-e-gate.git
. ~/.local/share/kwik-e-gate/venv/bin/activate
cd /path/to/your/git-repository
kwik-e-gate init
# Review .hermes/gate.toml and set the checks your project actually runs.
kwik-e-gate plan
kwik-e-gate run
kwik-e-gate verify

After publication, the install becomes python3 -m pip install kwik-e-gate. The core has no runtime Python dependencies; your project's check tools must already be installed. The workflow generated by init pins the unpublished 0.4.0 package, so use the source-pinned Action for CI until release.

init writes a reviewable gate profile, runner, and CI workflow. plan previews the selected checks without running them. run executes them and issues a receipt. verify checks that the latest receipt still matches this checkout; it does not rerun the checks. A started run returns PASS only when at least one declared check ran and passed. Failed, missing, timed-out, and wholly skipped checks do not become PASS.

The normal loop is short:

change code → plan → run → PASS/FAIL + receipt → verify before claiming completion

The CLI writes JSON to stdout, including the result, route, and receipt path. Receipts live outside tracked source in the worktree's Git directory. To save a copy outside the repository, use kwik-e-gate run --output /external/path/receipt.json and verify it with kwik-e-gate verify --receipt /external/path/receipt.json.

How it works

1. You choose the checks. .hermes/gate.toml names the project's commands and the paths they cover. Kwik-E-Gate never installs ESLint, pytest, or other project tools for you.
2. It picks a route. Ordinary source edits use matching fast checks. Changes to tests, dependencies, CI, gate configuration, auth, schemas, or migrations escalate to full. kwik-e-gate plan shows the choice and why; --mode fast or --mode full selects one explicitly.
3. It runs and receipts. The result records checks, selected paths, outputs, tool versions, and an input/contract binding. Changing included code or gate configuration makes an earlier receipt stale. Run again to get fresh evidence.

The routing decision is local and deterministic. It does not read the code to infer intent or call an LLM. The actual check time depends on the commands your project declares. review is an optional separate step, not a prerequisite for local PASS/FAIL.

Configuration reference covers profiles, file globs, adapters, exclusions, and review policy.

Real example

While building Kwik-E-Gate, we caught a scanner-scope bug in its own fast gate. The profile selected LintLang for AGENTS.md, but the old runner also sent app.py and notes/SKILL.md to that scanner. An out-of-scope warning failed the run. The fix passed only AGENTS.md to LintLang; the same changed inputs and diff digest then passed. Both runs produced receipts.

Read the replay and both saved receipt payloads. This was a gate-wiring bug, not a defect in app.py; the before/after makes that distinction visible.

GitHub Action

The source-pinned Action runs the core without installing the unreleased PyPI package. Put these steps in a job that checks out the repository you want to gate:

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
  with:
    fetch-depth: 0
    persist-credentials: false
- uses: hermes-labs-ai/kwik-e-gate/.github/actions/kwik-e-gate@266898a2b72a2bf92aa4608a6123999eb00b7f6b
  id: gate
  with:
    mode: full
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
  if: always()
  with:
    name: kwik-e-gate-receipt
    path: ${{ steps.gate.outputs.receipt-path }}

The commit pin keeps the Action source fixed. The Action exports status and receipt-path; a path is available when receipt export succeeds. PASS and FAIL runs also publish a concise GitHub job summary (status, routing/mode, check counts, and receipt location) without dumping the full receipt or command output. For unusual detached or merge checkouts, provide its base input. CI examples show scoped profiles for real repositories.

What a receipt means

A PASS says the declared checks ran successfully on the bound local inputs. It is not a claim that the code is correct or that every dependency and external service was captured. Receipts are unsigned and local to the checkout; verify refuses missing, failed, stale, or incomplete evidence. If the code changes, run the gate again. If a repository also requires semantic review, run that separately.

Built by Hermes Labs. Contributing · Security · License · Changelog