Koh command reference.
Keep the versions of your project that worked. Save progress as you go, try a change, and bring an earlier version back when you need it.
01Get started
Koh keeps a history of your project as you work. Each save records the whole project, apart from files you ignore. Give it a short message about what changed, then carry on. History lives in one .koh file in the project folder, works offline and stores unchanged files once.
The installer downloads a verified binary for Apple silicon macOS or x86_64/ARM64 Linux and offers the zsh prompt and completions. Then open a terminal in your project and record your starting point:
A day with Koh
Say you want to change your project’s parser. Start from a saved version, make the change, and save again when it works.
koh statusSee whether anything changed since the last save, and read the changes with koh diff. Save unfinished work before starting the next task.
koh checkpoint "before changing the parser"Keep a named starting point. A checkpoint works even when no files have changed.
koh save "reject incomplete input"Edit, run your checks, review koh diff and save. Write a message you’ll recognise later.
koh viewBrowse what you’ve saved. If the change goes badly, save what you have and run koh load --checkpoint. Koh asks before replacing files, and the parser change stays in history if you want it back.
If a coding agent makes the change, record its model and task with the save so you can review or undo the whole session. To carry on from another machine, set up a remote.
Installation options
To install without prompts, run curl -fsSL https://koh.asha.software/install.sh | sh -s -- --yes --no-zsh, or use --zsh to include the plugin. INSTALL_DIR sets where the binary goes. New releases do not support Intel macOS.
Coming from Koh 2, save any unfinished work, run koh update and confirm, then run koh migrate in each repository. Migration keeps every save ID and moves the old data to .koh-v2/.
02How Koh works
One line of history
Saves form one line. Undo, revert, load and pluck each add a save, so earlier saves stay available by ID.
One SQLite file
.koh holds every save, file object, flag, setting and event. Don’t copy it while it is open; koh doctor --backup makes a consistent copy.
Strict confirmation
Destructive actions default to No. Press Enter to cancel, or approve with y, Y or explicit --yes. Replacing a remote and receiving saves also ask, even with --mine or --theirs.
Permanent erasure
Only koh strip erases files from saved history. It carries the removal to the remote and makes you type each path first.
.kohignore, and no machine can save it into this repository again.03Saving & history
Create the repository at the project root.
Save the whole working tree. Koh reuses stored files that have not changed and offers the save to the remote if one is configured.
Show changes since the last save, repository problems and any interrupted restore.
Show unsaved changes, compare the working tree with a save, or compare two saves. --session shows the changes made during an agent session.
Browse saves and checkpoints. On a terminal it opens the interactive list below; piped or with --json, it prints the history.
Record a save you can return to, even if no files have changed. Name the work you are about to start.
Mark a save as unsafe and record the reason, or clear the flag. Flags sync with the history.
Interactive view
| Key | Action |
|---|---|
| ↑ / ↓ | Move through saves |
| Tab | Switch saves and checkpoints |
| / | Search the line |
| Enter | Open one save |
| c | Copy its ID |
| l | Load it |
| f | Flag it |
04Going back
Each restore adds a save, so you can still return to the state you left.
Restore the state from one or more saves ago. With --session, restore the state from before the current session.
Discard unsaved changes after keeping them in a checkpoint. Load that checkpoint to get the work back.
Restore the files from the selected save.
Return to the latest checkpoint without looking up its ID.
Open a save in a temporary folder without changing the working tree or history.
Apply the changes from one save, or reverse them, as a new save. Paths limit which files it touches. If a file has changed since, pluck stops and leaves the tree alone.
05Sync & Kepr
Every repository on a machine shares one remote: a folder, an S3 bucket or storage from a Kepr host. Koh offers each save to it automatically. If that fails, Koh prints a warning and keeps the local save. After any interruption, run offer or steal again; Koh transfers only what the other side is missing.
Sign in to a Kepr host and use the storage it provides.
Use a local folder, mounted drive or USB disk.
Use an S3-compatible bucket. Credentials can come from KOH_ACCESS_KEY and KOH_SECRET_KEY.
Send saves the remote is missing. --builds also builds and publishes every platform named in koh.build.
Receive saves made on another machine. Koh replays local saves after the remote ones and applies files changed on only one side. If both sides changed a file, it shows both versions and asks which to keep; it never merges lines. Choosing mine or theirs sets the working files, and Koh prints the previous local head ID so you can load it later.
Download a public repository, check its complete history and record where it came from. Run koh steal inside it to receive later saves. It stays read-only until this machine signs in to that Kepr host; the next offer then imports the remote saves and drops the read-only source.
06Builds & releases
Run the koh.build recipe for this machine, the named platforms or every platform in the file. The output stays local; Koh does not upload or install it.
Look for a newer Koh release. Koh refuses versions that are not newer and checks the download’s Blake3 hash before replacing the binary.
The koh.build recipe
Define platforms, build commands and output paths in koh.build. Koh substitutes the platform and the project’s version into each command. It takes the first literal version it finds in VERSION, build.zig.zon, v.mod, package.json, Cargo.toml, Info.plist, then Gradle, without running a build tool, and refuses to build a project that has none.
Any project can build for these platforms, including Intel macOS, which Koh’s own releases no longer support.
| Platform | Target |
|---|---|
| linux-x86_64 | 64-bit Intel/AMD Linux |
| linux-aarch64 | 64-bit Arm Linux |
| macos-aarch64 | Apple silicon macOS |
| macos-x86_64 | Intel macOS |
| android-arm64 | 64-bit Arm Android |
| android-x86 | x86 Android |
Publishing
koh offer --builds builds every platform before uploading anything, then uploads the release files, the release record and finally releases/latest. Published versions never change; to correct a build, release a new version.
Building Koh itself needs V 0.5.2 b9a2d87 and the native C toolchain for the target OS and CPU. Boehm garbage collection is bundled and Zig is not required. The source README covers compiler setup and build commands.
07Agents & automation
--agent records the model and --session groups the saves from one task. koh view shows both as [agent · session].
koh diff --session last shows everything the latest named session changed. To throw the result away, koh undo --session restores the state from before it, or koh load --checkpoint returns to the checkpoint. The session’s saves stay in history either way.
Strict Koh Discipline
Read the current stateRead koh status --json, koh view --since today --json and LOG.md. Stop if the tree has unsaved changes.
Checkpoint before startingName the task in the checkpoint message.
Save one result at a timeUse separate saves for unrelated changes, even within one task.
Verify before savingBuild and test each result.
Sessions & attributionUse the real model ID and one short session name for the whole task.
Save seriallyAgents may work in parallel, but only one writes to the history at a time.
Describe the resultName the behavior the save adds or fixes. A message like “update files” tells the reader nothing.
Never end unsavedIf the task is incomplete, save it with a specific wip: message.
JSON & exit codes
Commands that print information accept --json and print one JSON value with no colour or pagination. Errors go to stderr. Without a terminal Koh never waits for an answer, and koh strip refuses to run.
| Command | Useful fields |
|---|---|
| koh status --json | head, dirty state, changed paths, size, flagged state |
| koh view --json | save IDs, parents, messages, agents, sessions, checkpoints |
| koh diff --session last | the complete patch made by one session |
| Exit | Meaning |
|---|---|
| 0 | The command worked |
| 1 | Koh refused or the operation failed |
| 2 | The command line was wrong |
08Care & configuration
Verify every stored object’s hash and each save’s file list. --backup writes a consistent copy of .koh. Old peek folders are cleared only with --yes.
Preview the ignore rules for these files or folders, confirm once, and toggle the matching rules in .kohignore. --global edits ~/.kohignore instead.
Convert a Koh 2 repository in place, keeping every save ID.
Erase these paths from history in one local transaction and from the remote. It needs a terminal, and you must type every path before removal starts; --yes skips only the yes/no question. If remote cleanup is interrupted, run the same batch again.
Read the built-in manual, or one command’s section. koh help prints a shorter reference, and koh help <command> prints one command.
Files
| Path | Purpose |
|---|---|
| .koh | The repository, in one SQLite file |
| .kohignore | Paths Koh leaves out; Koh’s own files and symlinks are always ignored |
| ~/.kohignore | Machine-local rules applied alongside each repository’s .kohignore; names and paths match at any depth |
| LOG.md | The latest 20 saves, rewritten after each save and never saved itself |
| ~/.config/koh/remote | The machine’s folder, S3 or Kepr-derived remote |
| ~/.config/koh/credentials | S3 credentials, stored with mode 0600 |
| koh.build | The project’s build and release recipes |
Ignored files remain in earlier saves. Koh previews broad ignore rules and warns when removing a rule would bring other files in. If a global rule matches a tracked file, the next save records that file as gone. Global rules stay on this machine.
Environment
| NO_COLOR | Turn off colour |
| KOH_NO_COLOR | The Koh-specific form of the same setting |
| KOH_ACCESS_KEY | S3 access key for remote setup |
| KOH_SECRET_KEY | S3 secret key for remote setup |
| KOH_UPDATE_SOURCE | Use another release document for updates |