Skip to content
Zevqi

Documentation

From install to your first knowledge map in five minutes

Requires Node 20+ and git. No API key. Works with any coding agent, because it reads your git repository.

1. Everything in one paste

In your project folder. This installs Zevqi, joins your team, turns it on and uploads your first knowledge map. Your team admin has the team key (or start a free trial to get one). Works in macOS, Linux and Windows PowerShell.

npm install -g zevqi; zevqi setup --key <your-team-key>

Working alone, with no team? Install, then run zevqi init and zevqi scan --dry-run to see what a scan finds. Nothing is sent anywhere.

Prefer to build it from source, or install from GitHub?
git clone https://github.com/zevqi/zevqi
cd zevqi/packages/cli && npm install && npm run build
npm link

The package on npm is zevqi. It is MIT-licensed and small enough to read before you run it.

2. Turn it on

No model key is needed. zevqi scan maps who holds the knowledge of each file from git, zevqi review records your own description of a change, and your coding agent can write lessons itself. If you want Zevqi to write the questions, add your own key (Zevqi prefers ZEVQI_API_KEY, then your provider variable). It is billed by your provider, never by us.

cd your-project
zevqi init        # no key needed; restart Claude Code afterwards
zevqi scan --dry-run   # see exactly what a scan would share
zevqi doctor

# optional: AI-written questions, billed by your own provider
export ZEVQI_API_KEY=sk-ant-...

3. Code as usual, then learn

When your agent finishes a turn, a lesson is built in the background. Take it whenever you like.

zevqi status
zevqi learn       # terminal quiz
zevqi ui          # or the local web dashboard

4. Join your team

Start a 7-day free trial (no card) or buy a Team plan. Your team key, dashboard link and join command appear straight away. Lost them later? Sign in with the same email to reach your dashboard and rotate the key.

zevqi team join --server https://zevqi.com --key zlt_... --email you@company.com

CI

Gate pull requests

zevqi check asks your team server which files a pull request changes that still have AI-written changes nobody has understood. It sends only file paths and the repository name, and it prints inline GitHub annotations and a job summary. Use a team key from a repository secret.

# .github/workflows/zevqi.yml
name: zevqi check
on: pull_request
jobs:
  understand:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: git clone --depth 1 https://github.com/zevqi/zevqi /tmp/zevqi && cd /tmp/zevqi && npm ci && npm run build:cli
      - run: node /tmp/zevqi/packages/cli/dist/cli.js check --base origin/${{ github.base_ref }} --fail-on unreviewed
        env:
          ZEVQI_TEAM_KEY: ${{ secrets.ZEVQI_TEAM_KEY }}
  • --fail-on none (default) reports only. unreviewed fails when a changed file has an AI change nobody has reviewed. blind fails when nobody has ever understood a changed file.
  • A server outage never breaks your pipeline unless you pass --strict. Exit codes: 0 ok, 1 policy failed, 2 usage error, 3 outage with --strict.
  • Requires a Team plan, because the check reads your team’s shared coverage.

Reference

Commands

zevqi init [--shared|--global] [--gate off|warn|block]Turn it on in this repo and install the hooks.
zevqi learn [id]Take the quiz for the oldest un-reviewed change.
zevqi explainExplain your current uncommitted changes now.
zevqi review <file…> [--commits 5]Review the recent committed changes to files, such as a teammate’s, and add your own evidence. This is how a second person covers a file.
zevqi statusWhat is waiting for review, and which files nobody has reviewed.
zevqi uiLocal dashboard on 127.0.0.1 with lessons, quiz and knowledge map.
zevqi gate off|warn|blockWhat happens when you commit with un-reviewed AI changes.
zevqi config set apiKey|provider|model|baseUrl <value>Settings. Prefer environment variables for keys.
zevqi team join --server <url> --key <zlt_…> --email <you>Join your team. Lessons then sync after each quiz.
zevqi check [--base <ref>] [--fail-on unreviewed|blind]Pull-request gate: which changed files have AI changes nobody understands.
zevqi statsYour streak, XP and level for this project.
zevqi doctorCheck that everything is wired up.
zevqi uninstallRemove the hooks. Your lessons stay in .zlearn/.

Help

Troubleshooting

Hooks do not fire. Restart Claude Code after zevqi init, run zevqi doctor, and open /hooks in Claude Code to confirm they are registered. We have not yet tested every Claude Code version, so please tell us if yours differs.

“No API key”. Export ZEVQI_API_KEY in the shell that launches Claude Code. A key set only in another terminal tab is not visible to the background job.

Zevqi not found on Windows. Add %APPDATA%\npm to your PATH, or run node path\to\packages\cli\dist\cli.js directly.

Still stuck? Visit Support.

Choose how it learns

Every way Zevqi can learn about your code

Pick the least you need to share. Most teams start with the first two.

  • Git knowledge map
    Available

    zevqi scan reads your git history: who changed which files, when, and whether a commit says an AI helped.

    Leaves your machine
    File paths, commit counts, dates and pseudonymous author ids. Names only if you add --names. Never code, commit messages or emails.
    Needs from you
    One command. No model, no key.
  • Attested review
    Available

    zevqi review <file>: you read the real change and describe it in your own words. Not graded.

    Leaves your machine
    The path, a content fingerprint and your own call (understood or not yet). Your words stay on your machine.
    Needs from you
    One or two minutes. No model, no key.
  • Pull-request check
    Available

    zevqi check in CI lists changed files whose AI-written changes nobody has reviewed.

    Leaves your machine
    The changed file paths and the repository name.
    Needs from you
    A team key stored as a CI secret.
  • Written by your coding agent
    Early access

    A block in AGENTS.md makes Codex, Cursor or Claude Code write the lesson itself and hand it to Zevqi.

    Leaves your machine
    File paths, fingerprints and scores. No extra model call and no key.
    Needs from you
    zevqi init adds the block. The agent has to follow it.

    Implemented and tested on our side. Not yet verified in live Codex or Cursor.

  • Claude Code hooks
    Available

    Lessons are prepared in the background after each agent turn.

    Leaves your machine
    File paths, fingerprints and scores. With a model key, the diff goes to your provider.
    Needs from you
    zevqi init, and a model key for the questions.
  • Your own model key
    Available

    Zevqi writes questions that are specific to the diff.

    Leaves your machine
    The diff of the changed files goes to your provider under your own account. Never to us. Zevqi tells you before it installs anything.
    Needs from you
    An API key you provide and pay for.

    Optional. Most of Zevqi works without it.

  • Local model
    Planned

    AI-written questions from a model running on your own machine.

    Leaves your machine
    Nothing leaves your machine.
    Needs from you
    Install and run a model.
  • GitHub app
    Planned

    Show who approved each change, from pull-request reviews.

    Leaves your machine
    Pull-request metadata. No code.
    Needs from you
    An organization admin installs the app.
  • Cursor and Codex hooks
    Planned

    Capture edits directly in each tool.

    Leaves your machine
    File paths.
    Needs from you
    A per-tool install.
  • Lessons written by Zevqi
    Not offered

    We would read your diffs and write the questions.

    Leaves your machine
    Your code would reach us.
    Needs from you
    Nothing.

    By design: your code never reaches us.

  • Using your Claude subscription login
    Not offered

    Running Claude in the background on your behalf.

    Leaves your machine
    The diff would go to Anthropic through your login.
    Needs from you
    Nothing.

    The provider asks products to use API keys, so we do not do this.

Statuses are literal. Available means it is built and tested. Early access means built, but not yet verified in the live tool. Planned means not built. Not offered means we have chosen not to.

Rather have us set it up with you?

Book a demo and we will install it on one of your repositories together.