kJudge

Your offline Codeforces companion — fetch, test, stress, diff.
A command-line judge for competitive programmers who want their local workflow to feel as tight as submitting on the judge itself.

⚠️ Currently Windows only. Linux and macOS support is planned for a future release.

---

Why kJudge?

Most CP tools make you choose between power and simplicity. kJudge does both — one command to fetch samples, one command to stress test, one command to scaffold an entire contest. No browser tabs, no manual copy-paste, no guessing why your output is wrong.

Feature	kJudge	cf-tool	Competitive Companion
Fetch CF samples	✅	✅	✅
Colored AC/WA/TLE/RTE output	✅	❌	❌
Line-by-line diff	✅	❌	❌
Stress testing (brute vs smart)	✅	❌	❌
Auto-rerun on file save (watch)	✅	❌	❌
Full contest scaffold	✅	✅	❌
Custom checkers (float, token, script)	✅	❌	❌
Interactive problem support	✅	❌	❌
Zero browser dependency	✅	❌	❌

---

Quick Start

mkdir 4A && cd 4A
kjudge init                  # set up problem directory
kjudge fetch cf:4A           # download sample tests from Codeforces
# write your solution in main.cpp...
kjudge run main.cpp          # test against all samples → AC / WA / TLE / RTE
kjudge diff sample_002       # see exactly where your output diverged
kjudge case sample_002 main.cpp  # re-run just that one test

---

Installation

Download kjudge.exe from GitHub Releases and run it. A setup prompt will appear:

⚡ Welcome to the kjudge CLI Setup ⚡
 
It looks like you opened the standalone executable directly.
Would you like to permanently install kjudge to your system?
This will copy it to C:\Users\<name>\.kjudge\bin and add it to your PATH.
Install kjudge? (Y/n):

Pressing Y will:

• Copy kjudge into ~/.kjudge/bin (a permanent hidden folder)
• Add it to your system PATH so kjudge works from any terminal

Note: If kjudge isn't found after installation, open a new terminal window — Windows updates PATH only for new sessions.

Uninstallation

kjudge self-uninstall
# removes all kjudge files and PATH entries
# note: this also deletes your custom templates — back them up first

---

Commands Reference

Core

Command	Description
kjudge init	Initialize problem directory with .kjudge/ config
kjudge fetch cf:1234A	Fetch sample test cases directly from Codeforces
kjudge add	Interactively add a custom test case
kjudge run main.cpp	Run solution on all tests, show verdicts (AC, WA, TLE, RTE)
kjudge case 2 main.cpp	Run a single test case by index or name
kjudge diff sample_002	Show a line-by-line diff comparing output vs expected

Watch Mode (Auto-Rerun)

kjudge watch main.cpp
# reruns all tests automatically every time you save main.cpp
# pairs perfectly with your editor's auto-save

This is one of kJudge's most productive features. Keep a terminal open with watch running while you edit — you get instant feedback without ever switching windows.

Stress Testing

The fastest way to find a counterexample when samples pass but the judge says WA.

# Write three files: your main solution, a brute force, and a test generator
kjudge stress --brute brute.cpp --smart main.cpp --gen "python gen.py" --max 500
# kJudge runs both solutions on random inputs until it finds a mismatch

Or build up a regression suite manually:

kjudge gen --cmd "python gen_1234A.py" --count 50   # generate 50 random inputs
kjudge answer main.cpp                               # fill .out files using your solution
kjudge run main.cpp                                  # regression test all 50

Contest Mode

Scaffold an entire contest in one command:

kjudge contest cf:2050 --problems A B C D E F --template --lang cpp
# creates directories A/ B/ C/ ... each with your starter template ready

Or let kJudge auto-detect the problem list:

kjudge contest cf:2050   # scrapes the contest page for problem IDs

Test Management

Command	Description
kjudge list	Show all test cases in a table
kjudge remove sample_003	Delete a specific test case
kjudge clean --gen	Remove generated tests
kjudge clean --all	Remove everything
kjudge export	Package tests into a zip file

Advanced Options

# Custom checkers — for problems with multiple valid answers
kjudge run main.cpp --checker "python checker.py"
kjudge run main.cpp --checker token          # token-based comparison
kjudge run main.cpp --checker float:1e-6     # float comparison with epsilon
 
# Interactive problems
kjudge run main.cpp --interactive --checker interactor.py
 
# Override time/memory/language per run
kjudge run main.cpp --lang python --time 5000 --mem 512
 
# Control output verbosity
kjudge run main.cpp --quiet                  # summary only
kjudge run main.cpp --show-input --show-output

---

Configuration

Local Config (per problem)

.kjudge/config.json is created by kjudge init and can be edited freely:

{
  "language": "cpp",
  "main_file": "main.cpp",
  "build": "g++ -std=c++17 -O2 -o main main.cpp",
  "run": "main.exe",
  "time_limit_ms": 2000,
  "memory_limit_mb": 256
}

Global Config

Defaults applied to all problems:

kjudge config --set language cpp
kjudge config --set time_limit_ms 3000
kjudge config --show

Custom Templates

Place starter files in ~/.kjudge/templates/:

• main.cpp — used for C++ problems
• Main.java — used for Java problems
• main.py — used for Python problems

These are applied automatically with kjudge init --template and kjudge contest --template.

---

Verdicts

Verdict	Meaning
	Accepted — output matches expected
	Wrong Answer — output differs
	Time Limit Exceeded
	Runtime Error (crash / non-zero exit)

---

Full Workflow Example

Single Problem

mkdir 1234A && cd 1234A
kjudge init
kjudge fetch cf:1234A          # fetch samples
# edit main.cpp
kjudge watch main.cpp          # auto-rerun on every save
kjudge diff sample_002         # if WA, see the diff
# find the bug, save — watch reruns automatically

Stress Test Workflow

# samples pass, but WA on judge:
kjudge stress --brute brute.cpp --smart main.cpp --gen "python gen.py" --max 500
# when a mismatch is found, kJudge saves it as a new test case automatically
kjudge diff stress_001         # inspect the counterexample

---

License

MIT — free to use, modify, and distribute.

---

Built by Tanay Mishra · Documentation · Report a Bug