koh3

Most version control is built for teams, with branches to keep people out of each other's way, pull requests to argue in, and merge tools for when two people edited the same line. On your own you need none of that. You need to save your work, see what changed, go back when something breaks, and pick up on your laptop where you left off on your desktop.

That's all Koh does.

koh init
koh save "sketch the parser"
koh status
koh view
koh undo            # step back one save, without losing it
koh offer           # send your saves to your bucket
koh steal           # on the other machine: bring them in

How it thinks

Nothing is erased. Your history is one straight line, and every command adds to it. Undo, revert and load don't rewind anything. They record a new save that puts the files back, so the save you stepped away from is still there tomorrow. The only exception is strip, for the day a secret gets saved, and it makes you type the path twice before it does anything.

Everything lives in one file. A repo's whole history is .koh, a single SQLite file at the root, and there's nothing else to maintain. Copy that file and you've copied the whole history.

Your machines, not a server. Point Koh at an S3 bucket or a folder on a disk once per machine with koh remote, and every save is offered to it automatically. If you worked on both machines without syncing, koh steal combines them file by file. A file changed on only one side just comes along. A file changed on both sides is shown to you, and you pick which version to keep. Your version isn't thrown away either way: the save it came from stays in history.

Safe to hand to an agent. Every command has --json, never waits for input when nothing is typing, and exits 0, 1 or 2. Saves record which agent made them and in which session, so koh undo --session can take back an agent's whole run in one step. A person has to be at the keyboard to strip.

Small on purpose. Koh 3 has 17 commands, down from Koh 2's 45, and a hard ceiling of 10,000 lines of V. A feature that doesn't fit gets cut, so one person can still read all of it.

Setting up sync

koh remote          # asks: a folder, or an S3 bucket?

It tests the remote before saving anything. Scripts can skip the questions:

KOH_ACCESS_KEY=... KOH_SECRET_KEY=... \
  koh remote s3 https://s3.fr-par.scw.cloud my-bucket fr-par
koh remote folder /Volumes/usb/koh

Or write the two files yourself. koh man remote shows the format.

~/.config/koh/remote        kind, endpoint, bucket, region (or path)
~/.config/koh/credentials   access_key, secret_key, mode 600

In your prompt

shell/koh3.plugin.zsh puts the repo in your zsh prompt and adds tab completion:

kiln · v2.1.0 · 6 saves · 4.2 MB !
→

! means unsaved changes, and ⚑ means the save you're on has been flagged. Source it from ~/.zshrc. The comments at the top cover Starship, Powerlevel10k and using your own prompt.

Status

Koh 3 is a rewrite of Koh 2 in V, for macOS and Linux. While it's being built the binary is called koh3. At the cut-over it becomes koh, Koh 2 becomes koh2, and koh migrate converts a Koh 2 repo in place. The specification is /Users/june/Downloads/Koh 3 — God Document.md.

Building

v -o build/koh3 src/koh3.v            # or -prod for a release build
v test src/ && v test tests/
v fmt -verify src/ tests/

Koh is pinned to V master at b9a2d87, because V master can break it. SQLite 3.49.1 is vendored and compiled in, so there are no other dependencies. AGENTS.md has the install steps for the pinned V, the Linux notes and the layout.

.agent/

CONTINUITY.md

plan-8e-guided-steal.md

docs/

koh-kepr-3-master-spec.md

koh2-man.txt

koh3-man.txt

shell/

koh3.plugin.zsh

src/

apply/

apply_test.v

apply.v

build/

build_test.v

build.v

version.v

cli/

args_test.v

args.v

cli.v

cmd_back_test.v

cmd_back.v

cmd_build.v

cmd_diff.v

cmd_doctor_test.v

cmd_doctor.v

cmd_flag.v

cmd_init.v

cmd_man.v

cmd_migrate.v

cmd_offer.v

cmd_peek.v

cmd_pluck.v

cmd_remote.v

cmd_save.v

cmd_status.v

cmd_steal_test.v

cmd_steal.v

cmd_strip.v

cmd_update.v

cmd_view.v

handover.v

output.v

progress.v

prompt.v

repo.v

events/

events_test.v

events.v

exchange/

exchange_test.v

exchange.v

records.v

source.v

steal.v

strip.v

fmt/

fmt.v

history/

history_test.v

history.v

log_md.v

save.v

machine/

machine.v

settings_test.v

settings.v

migrate/

migrate_test.v

migrate.v

release/

release_test.v

release.v

remote/

folder_test.v

folder.v

remote.v

s3_test.v

s3.v