Get Started

Install CheatNt in
Minutes

The CheatNt agent runs entirely on the student's machine — no cloud required during the session. Download the package, run the setup script, and start monitoring in under five minutes.

⬇ Download ✓ Requirements 📋 Install Guide 🔌 VS Code ⌨ Commands 🔧 Troubleshoot
Download

Choose Your Platform

macOS

Monterey 12.0+

Available

cheatnt_client + cheatnt_server

Shell scripts (init, track, start…)

VS Code extension (.vsix)

install.sh dependency setup

Download for macOS

macos-cheatnt-v1.0.zip · ~12 MB

Linux

Ubuntu 22.04+

Coming Soon

apt / snap support will mirror the macOS feature set. Join our mailing list to be notified.

Windows

Windows 11

Coming Soon

Native Windows support is on the roadmap. The web dashboard already works on all platforms.

Verify your download: sha256sum cheatnt-macos-latest.zip  ·  SHA-256 checksum published on the About page.

Before You Begin

Requirements

System

  • macOS 12 Monterey or later
  • Apple Silicon or Intel — both supported
  • ~150 MB disk space for binaries + deps

Software

  • Homebrew — brew.sh
  • Visual Studio Code — for the extension
  • Python 3 — usually pre-installed on macOS
  • Bash or Zsh shell

Auto-installed by install.sh

Run once — the script handles everything below automatically

gcc@14 git cmake sqlite3 libzip pkg-config fmt
Step by Step

Installation Guide

Complete walkthrough — from download to first session

1

Install Homebrew (skip if already installed)

Homebrew is the package manager used by CheatNt's setup script to install its C++ dependencies. Open Terminal and paste: 

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2

Download & Extract the Package

Download the zip from the button above, then move it somewhere permanent — the scripts call the binary from that folder, so don't delete it after installation. 

# Move to your Applications folder and unzip
mv ~/Downloads/cheatnt-macos-latest.zip ~/Applications/
cd ~/Applications/
unzip cheatnt-macos-latest.zip
cd cheatnt
3

Run the Setup Script

install.sh installs all C++ library dependencies via Homebrew and makes all scripts executable. You only need to run this once on a machine. 

chmod +x install.sh && ./install.sh
macOS may ask for your password (sudo) to install packages. This is expected — Homebrew needs it for the first run.
4

Navigate to Your Project Folder

All CheatNt commands must be run from inside your project directory — the folder where your source code lives. Each command determines its working directory from $(pwd). 

cd ~/Desktop/MyProject    # ← your actual project folder
5

Initialize the Session

Run cheatnt_init.sh with the session keyword given to you by your instructor. This creates a hidden .cheatnt/ directory containing the local SQLite database. 

~/Applications/cheatnt/cheatnt_init.sh <session-keyword>
# Expected output: "initialized"
Tip: add ~/Applications/cheatnt to your PATH so you can call scripts without the full path. See the Troubleshooting section below.
6

Create & Track Your Files

Every file you want monitored must be created empty first, then tracked immediately — before adding any content. Tracking a file that already has content will be rejected. 

# Create empty files first
touch main.cpp utils.cpp

# Track each file immediately
~/Applications/cheatnt/cheatnt_track.sh main.cpp
~/Applications/cheatnt/cheatnt_track.sh utils.cpp
Important: files that already have content cannot be tracked. You must create them empty (touch filename) before writing any code.
7

Install the VS Code Extension

CheatNt needs its VS Code extension to capture keystroke-level events. Install it from the .vsix file included in the downloaded package.

Option A — Command line (recommended)

code --install-extension ~/Applications/cheatnt/cheatnt-vscode.vsix

Option B — VS Code UI

  1. 1. Open VS Code and press ⌘ Shift P
  2. 2. Type Extensions: Install from VSIX and press Enter
  3. 3. Navigate to ~/Applications/cheatnt/ and select the .vsix file
  4. 4. Click Reload when prompted
Verify the extension is active: the CheatNt status bar item should appear in the bottom-right of VS Code after reloading.
8

Start the Monitoring Agent

Start the agent from your project directory. It runs silently in the background, recording file-system and VS Code events into the local SQLite database. 

~/Applications/cheatnt/cheatnt_start.sh
# The agent is now running — start coding in VS Code!
✓

Stop, Zip & Submit

When you're done, stop the agent, create the submission zip, and upload it to your instructor's CheatNt project portal. 

# Stop monitoring
~/Applications/cheatnt/cheatnt_stop.sh

# Create SUBMIT_ME.zip containing your code + monitoring data
~/Applications/cheatnt/cheatnt_zip.sh

# Upload SUBMIT_ME.zip to your instructor's CheatNt portal
The zip contains only your tracked source files and the .cheatnt/ metadata directory. No other files from your machine are included.
Quick Reference

Command Reference

All scripts must be run from your project directory

Command Arguments What it does
cheatnt_init.sh <keyword> Initializes .cheatnt/ database in the current directory
cheatnt_track.sh <filename> Registers an empty file for monitoring — run before adding content
cheatnt_untrack.sh <filename> Removes a previously tracked file from monitoring
cheatnt_start.sh — Starts the background monitoring agent process
cheatnt_stop.sh — Stops the agent and flushes all pending events to the database
cheatnt_zip.sh — Creates SUBMIT_ME.zip with tracked files + monitoring data
cheatnt_clear.sh — Removes .cheatnt/ entirely — resets the session (irreversible)
~/.zshrc or ~/.bashrc 
# Add to your shell profile to call scripts without the full path:
export PATH="$HOME/Applications/cheatnt:$PATH"
# Then reload: source ~/.zshrc
Help

Troubleshooting

You tried to track a file that already has content. CheatNt requires files to be empty at tracking time so it can build an accurate insertion history from scratch.

Fix:

# Delete the file and recreate it empty
rm myfile.cpp
touch myfile.cpp
cheatnt_track.sh myfile.cpp
# Now open in VS Code and start writing

Every CheatNt command reads $(pwd) to find the .cheatnt/ directory. If you run the script from a different folder, it won't find it.

Fix: always run commands from your project root:

cd ~/Desktop/MyProject   # ← must be here
cheatnt_start.sh

The extension communicates with cheatnt_client over a Unix socket at /tmp/cheatnt.sock. If the socket isn't there, the client isn't running.

Checks:

# Verify the socket exists
ls -la /tmp/cheatnt.sock

# Verify the client process is running
pgrep -x cheatnt_client

# If neither, restart the agent
cheatnt_stop.sh && cheatnt_start.sh

The scripts may have lost their executable bit, especially if the zip was transferred. Fix by making them executable again:

chmod +x ~/Applications/cheatnt/*.sh
chmod +x ~/Applications/cheatnt/cheatnt_client
chmod +x ~/Applications/cheatnt/cheatnt_server

macOS Gatekeeper blocks unsigned binaries from the internet. Remove the quarantine attribute to allow execution:

xattr -dr com.apple.quarantine ~/Applications/cheatnt/

Alternatively: System Settings → Privacy & Security → scroll to the blocked binary → click Allow Anyway.

The most common reasons for an empty report:

  • •VS Code was not open during the session — the extension only sends events while VS Code is running.
  • •Files were edited outside VS Code — file-system events are still recorded, but keystroke-level data requires the extension.
  • •The agent was not running when edits were made — always start with cheatnt_start.sh before opening VS Code.
  • •Files were not tracked before editing — only tracked files appear in the report.
# Check which files are tracked:
cat .cheatnt/tracked

# Check how many events were recorded:
sqlite3 .cheatnt/cheatnt.sqlite3 "SELECT COUNT(*) FROM vscode_events;"

Still stuck? We're happy to help.

Contact Support