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 explain | Explain 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 status | What is waiting for review, and which files nobody has reviewed. |
zevqi ui | Local dashboard on 127.0.0.1 with lessons, quiz and knowledge map. |
zevqi gate off|warn|block | What 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 stats | Your streak, XP and level for this project. |
zevqi doctor | Check that everything is wired up. |
zevqi uninstall | Remove 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.
| Way | What leaves your machine | What it needs from you | Status |
|---|---|---|---|
Git knowledge map zevqi scan reads your git history: who changed which files, when, and whether a commit says an AI helped. | File paths, commit counts, dates and pseudonymous author ids. Names only if you add --names. Never code, commit messages or emails. | One command. No model, no key. | Available |
Attested review zevqi review <file>: you read the real change and describe it in your own words. Not graded. | The path, a content fingerprint and your own call (understood or not yet). Your words stay on your machine. | One or two minutes. No model, no key. | Available |
Pull-request check zevqi check in CI lists changed files whose AI-written changes nobody has reviewed. | The changed file paths and the repository name. | A team key stored as a CI secret. | Available |
Written by your coding agent A block in AGENTS.md makes Codex, Cursor or Claude Code write the lesson itself and hand it to Zevqi. | File paths, fingerprints and scores. No extra model call and no key. | zevqi init adds the block. The agent has to follow it. | Early access Implemented and tested on our side. Not yet verified in live Codex or Cursor. |
Claude Code hooks Lessons are prepared in the background after each agent turn. | File paths, fingerprints and scores. With a model key, the diff goes to your provider. | zevqi init, and a model key for the questions. | Available |
Your own model key Zevqi writes questions that are specific to the diff. | The diff of the changed files goes to your provider under your own account. Never to us. Zevqi tells you before it installs anything. | An API key you provide and pay for. | Available Optional. Most of Zevqi works without it. |
Local model AI-written questions from a model running on your own machine. | Nothing leaves your machine. | Install and run a model. | Planned |
GitHub app Show who approved each change, from pull-request reviews. | Pull-request metadata. No code. | An organization admin installs the app. | Planned |
Cursor and Codex hooks Capture edits directly in each tool. | File paths. | A per-tool install. | Planned |
Lessons written by Zevqi We would read your diffs and write the questions. | Your code would reach us. | Nothing. | Not offered By design: your code never reaches us. |
Using your Claude subscription login Running Claude in the background on your behalf. | The diff would go to Anthropic through your login. | Nothing. | Not offered The provider asks products to use API keys, so we do not do this. |
- Git knowledge mapAvailable
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 reviewAvailable
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 checkAvailable
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 agentEarly 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 hooksAvailable
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 keyAvailable
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 modelPlanned
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 appPlanned
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 hooksPlanned
Capture edits directly in each tool.
- Leaves your machine
- File paths.
- Needs from you
- A per-tool install.
- Lessons written by ZevqiNot 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 loginNot 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.