You describe the change you want. Something else types it. The next few minutes get that happening on your machine, on your code, with you watching every move and approving each one before it lands. Never used a terminal? The first command is a copy and paste, and everything after it is plain English.
Eight steps. Four of them are setup you do once, and by step four you have paid a cent to have your own repo explained back to you. What you need on hand: a terminal, a git repo you do not mind an agent editing and either a few dollars or an API key you already own.
// two passwords, and only one of them reaches us
Ko drives the agent loop on the Fight Club platform, so start with an account. Sign up at knockout.fightclub.pro/register with an email, a username and a password. The same form offers a vault password. Set it now, and pick something you can retrieve, because step 3 needs it and no reset exists.
Then check your inbox. Login stays blocked until you click the verification link, so this is not a step you can skip. Miss it and ko auth login later bounces you back to a form that rejects the password you just set, with no hint why.
No verification email? Request another from the sign-in page.
The form asks for two passwords and that is deliberate. The account password logs you in and lands on our side as a scrypt hash. The vault password never leaves your browser at all: it derives the key that encrypts your provider keys and your session history, and what we store is the ciphertext plus a verifier that can confirm a password without revealing it. Which is also why nobody here can reset it for you.
// one curl, then authorize in the browser
The installer autodetects your OS and arch, drops the binary at /usr/local/bin/ko and marks it executable.
Then ko auth login opens a browser tab. Sign in with the account you just verified, click authorize, and a scoped token lands locally. Notice the wallet reads $0.00. That's expected, and step 3 fixes it.
Already have a token? ko auth token <token> pastes it directly, useful for CI, headless servers or containers.
The login flow hands the CLI a scoped token, not your password, and writes it to ~/.ko/credentials.json at mode 0600 on your machine only. Server-side that token is kept as a SHA-256 hash, so a stolen database yields nothing you can log in with. Revoke it from the dashboard any time without changing your account password. On CI, skip the browser: point KO_TOKEN_FILE at a file holding a token and ko reads it at startup, no on-disk cache and nothing in your shell history.
// top up a wallet, or bring a key we cannot read
A real task makes model calls, and those cost money, so ko refuses to start one against an empty wallet rather than failing halfway through your feature. Two ways to cover it, and you only need one.
Add credits at /dashboard/credits and ko bills you per task at cost plus a small margin, no subscription. Or bring your own keys: add your OpenAI or Anthropic key at /dashboard/byok, run ko vault unlock, and ko spends against your provider account instead. The wallet stays untouched.
ko auth status shows your balance and whether the vault is set up, any time.
Your OpenAI key is a bearer token. Whoever holds it can spend your money, so handing it to a SaaS box normally means trusting that box forever. Ko doesn't. Your keys get encrypted under the vault password only you know, and the server stores the ciphertext without ever holding the password. When ko needs a key you unlock, and the derived key survives four hours of real work before it expires. Idle time does not count, because only actual cryptographic use rolls the window forward. A full compromise of our database still leaves your keys as noise.
// one cent to have your own repo explained back to you
cd into any folder and run ko. First time in a new directory it asks whether you trust it. Say yes and it remembers. Then you get a full-screen terminal app (a TUI) with your model, wallet and context usage along the top and a prompt at the bottom.
Now ask it something. "Explain what this repo does" reads a few files and answers in a paragraph, for about a cent, and that is the whole product working. No config file, no prompt engineering, no ceremony. If you stop reading here you already have something useful.
Want a one-shot answer without the full screen? ko -p "quick question" prints and exits. ko -c later picks up where you left off.
First run in a new folder, ko asks whether you trust it. Say no and it still works, you just approve every tool call by hand. The trust list lives in ~/.ko/settings.json on your machine and nowhere else. A repo you check out cannot add itself to that list: a hostile project shipping its own .ko/settings.json has its auto-allow entries stripped on load, so cloning someone's code never grants it silent permissions. That is the attack everyone forgets about, and it is closed at load time rather than at prompt time.
// needs a git repo, then search stops depending on spelling
Grep finds the word you typed. It's useless when you can't remember the word. You know there's code somewhere that stops people hammering the signup form, but was it called throttle, limiter, guard or something a cat produced by walking across a keyboard at 3am? Indexing fixes that.
ko workspace init needs a git repo. It walks the tree, uploads each file to a private index on your account and turns every file into a set of coordinates where meaning rather than spelling decides what sits near what. Around 30 seconds on a typical codebase. After it finishes, a search for rate limiting lands on the throttle middleware even though the two share no letters.
Skip the background watcher in CI with --no-watch. Check state with ko workspace status. Ko keys the index off the repo hash, so the same project is recognisable across your machines.
The walker honours .gitignore and .koignore, skips anything over 1 MB, sniffs the first few KB for null bytes to drop binaries, and never embeds a file matching a secret pattern like .env, *.pem or id_rsa*. Then the agent gets VectorSearch as a tool it can choose to call, sitting alongside Grep rather than replacing it. Grep still wins for an exact symbol. VectorSearch wins for the query you can only describe.
// describe the outcome, watch the loop close
Describe the outcome, not the steps. "Add a /health endpoint that returns uptime and version". Ko reads the relevant files, plans the change, writes it, then runs the verifier to prove it works.
Reads, greps and a git status run without asking. Anything that writes a file or runs a command stops and waits for your yes. Watch the PLAN, ACTION and VERIFY tags stream past as it goes.
Cost and duration print at the end of every task, and the running total ticks in the status bar throughout. One feature typically runs $0.01 to $0.50 depending on pipeline and model. Hit ESC on a run that is going nowhere and you are billed only for what already streamed.
A chatbot answers and stops. Ko reads some files, decides on a change, makes it, then runs your tests. When the tests fail it reads the error, adjusts and goes round again, and keeps going until they pass or the budget runs out. Round and round. That loop is the whole product, and everything else on this page is plumbing around it.
// same binary, different set of brains
A pipeline is the recipe ko follows for a task. Which models run, in what order, which tools each step may touch and where the job goes when a step fails. /pipeline lists the ones on your account. They seed themselves the first time you look, so the list is never empty.
The default (KO_default) is a generalist. KO_consensus has three frontier models from three vendors implement in parallel and a judge pick the winner. Then there are specialists for legal, finance, research, HR and more. /pipeline <name> switches mid-session and your history carries over, so the next task uses the new recipe with the same context.
Want to build your own? Open the pipeline editor at /dashboard/pipelines to visually wire steps, pick models, set tool allowlists and add failure branches.
Behaviour comes from the tool allowlist more than the prompt. A planning step that lists only Read, Glob and Grep physically cannot start implementing, so it hands back a plan instead of a half-finished patch. That is the lever you pull when a custom pipeline misbehaves, and it works far better than adding another instruction in capitals.
// the session outlives the terminal it started in
ko -c continues the most recent session in this directory. ko -r lists past sessions to pick from. ko --resume-id <id> jumps straight to one.
Low on context? /compact folds the conversation into a short memo. /clear wipes history but keeps the system prompt. Made a mistake last task? /rollback restores every file ko touched, because it snapshots before every edit.
Because the state lives on the server, you can resume from any machine on the same account.
Every message, tool call and file edit is written down as it happens, so the session is not living in your terminal's scrollback. Close the terminal, reboot, come back tomorrow on a different laptop, and ko -c picks the thread back up mid-thought. Sessions are pinned to the directory they started in, which is why continuing from a different project hands you a fresh one instead of bleeding context across unrelated code. One honest caveat. If you disappear mid-turn, a watchdog aborts the turn after 90 seconds of silence, because an agent looping into a void is an agent billing into one.
The next interesting thing to do is open the pipeline editor and change one step. Give the verifier a cheaper model, or take Write away from your planner and watch how differently it behaves. The manual covers every command, flag and config key when you want the depth.