The Manual.

Knockout ships as a single Go binary called ko. The installer autodetects your OS (Linux, macOS) and architecture (amd64, arm64), downloads the matching release, drops it in /usr/local/bin/ko and marks it executable.

# One-liner
curl -fsSL https://fightclub.pro/install.sh | bash

# Verify
ko version

If the installer can't reach the release archive (e.g. air-gapped machine), it falls back to go install from source, which requires Go 1.22+ on the PATH. For fully manual installs, grab a release binary from https://fightclub.pro/releases/ko-<os>-<arch>, make it executable, move it into your PATH.

All of ko's state lives in ~/.ko/: credentials, session history, memory, skills and settings. Projects can also have a local .ko/directory for project-scoped memory and snapshots.

Ko uses scoped API tokens. ko auth login is the interactive path, it opens your browser at the Fight Club platform, you sign in, grant the CLI scope, and a token is written to ~/.ko/credentials.json.

ko auth login       # browser OAuth — for personal machines
ko auth token <tok> # paste an existing token — for CI/headless
ko auth status      # show which account + wallet balance

For CI, servers, or containers where browser-based OAuth isn't possible, create an API token from the web dashboard at /ko/settings, then runko auth token <token> to cache it locally.

The API token itself doesn't expire, revoke it from the platform dashboard if needed. For unlocking your BYOK provider keys so ko can decrypt them, see Vault (BYOK unlock).

Your provider API keys (Anthropic, OpenAI, etc.) are stored encrypted on the server under your vault password. Before ko can use those keys it needs the vault unlocked. You do this once per machine with ko vault unlock. The derived vault key is cached locally in ~/.ko/credentials.json (perms 0600) so every subsequent ko invocation silently reactivates the CLI vault session, no prompts, no timers.

ko vault unlock   # prompts for vault password (once per machine)
ko vault status   # show whether the vault is locked/unlocked + local cache
ko vault lock     # revoke the CLI session + wipe the cached key

Web and CLI sessions are independent. Unlocking from ko does not open the web session, and the web UI's 4-hour idle lock does not affect the CLI, the CLI session has no expiration.

If the machine is lost or compromised: log into the web UI and change your vault password. This re-encrypts every BYOK entry under a new vault key; any cached key on the lost machine is now useless (ko's auto-restore checks the vault verifier before re-creating the session and silently fails against a stale key).

If you never use your own provider keys (only fc:* platform-pool models), you don't need to run ko vault unlock at all, those models route through platform-managed credentials that never touch the vault.

A session is a conversation between you and ko, scoped to the current working directory. Every message, tool call and file edit is persisted to the server so you can resume from any machine with the same account.

ko                      # start a new session in $(pwd)
ko "quick question"     # start with an initial prompt
ko -p "one-shot"        # non-interactive: print answer, exit
ko -c                   # continue the most recent session in $(pwd)
ko -r                   # pick from a list of recent sessions
ko --resume-id <id>     # jump straight to a specific session
ko sessions             # list all past sessions
ko resume <id>          # same as --resume-id

Sessions are bound to their origin directory. If you start ko in ~/project-a and later run ko -c from ~/project-b, you'll get a fresh session for B, ko won't mix them up.

The first time you run ko in a new directory, it auto-registers the folder as a ko project. Subsequent runs pick up the same project record.

A pipeline is the program ko runs on each task: an ordered sequence of steps, each with its own model, system prompt, tool allowlist, temperature, retry policy and conditional next-step logic. Switching pipelines is how the same ko becomes a coder, a legal analyst, a financial bull-vs-bear debater, or a copywriter.

The shipped pipelines cover the main verticals:

Swap pipelines mid-session with the /pipeline slash command. Your conversation history is preserved; the next task uses the new flow. Build custom pipelines in the visual editor at /dashboard/pipelines.

/pipeline              # list available pipelines (TUI)
/pipeline KO_consensus # switch to a named pipeline

Switching a pipeline mid-session also resets any model override you picked with /model, so the new pipeline runs its own per-step models. The TUI prints "Model reset to pipeline default"to make the reset explicit.

During a pipeline run, each step transition banner shows which model is handling that phase, e.g. ─── Plan → Implement: Step Implement · claude-sonnet-4-6 ───. The top-bar model label also swaps to the step's model as soon as streaming starts.

Per-step caps

Each step in the editor has three caps. The pipeline editor surfaces them as Max $, Max In, Max Out (hover the ⓘ icons next to each label for the live definitions). In short:

Pipelines are where ko goes from "generic agent" to "opinionated workflow that beats a single-model baseline." Design matters: the same three frontier models wired differently (parallel vote vs. plan→implement→verify vs. adversarial A/B debate) produce wildly different quality, latency and cost profiles. This section unpacks every field in the editor at /dashboard/pipelines.

Anatomy of a step

Every step in a pipeline has the following fields. Most are surfaced as form controls in the visual editor at /dashboard/pipelines; all of them show up in the JSON if you export or edit a pipeline config directly.

Multi-model strategies

When models has more than one entry, the step runs all N through one of four strategies, chosen by multiModelStrategy. Each has different cost, latency and quality trade-offs:

Transitions

Transitions are the state-machine layer. After a stage emits its structured artifact, an outcome string is derived from the artifact via the stage's outcomeRule (e.g. simpleSuccess returns success or no_work; fieldEnum:verdict reads the artifact's verdict field and returns it directly). That outcome is then matched top-to-bottom against the stage's transitions array; the first match's goto picks the next stage.

The outcome rules ship with the platform; the common ones are:

• simpleSuccess, returns no_work when the artifact set no_work: true, otherwise success.
• implementOutcome, returns success if any executed step in the artifact reported completed, else failure.
• fieldEnum:verdict, reads the artifact's verdict field (pass / fail on Verify stages).
• fieldEnum:outcome, reads the artifact's outcome field (Test / Review stages emit this directly).

The goto side supports three reserved targets plus any step name:

The special condition default matches everything and is almost always the last rule, it's the fallback when no named condition matched.

transitions:
  - { condition: "tests_fail",       goto: "Implement" }   # loop back
  - { condition: "security_issue",   goto: "SecurityFix" } # branch
  - { condition: "budget_exceeded",  goto: "_done" }       # stop on cap
  - { condition: "default",          goto: "_next" }       # otherwise advance

Common patterns

A few recurring shapes worth copying:

Design principles

• Shorter tool allowlists beat longer ones. A planner that can't write files won't try to implement. A reviewer that can only Read + Grep won't "fix" problems instead of reporting them.
• Use slots, not fixed model addresses. slot:code_frontier lets the platform swap the concrete model without touching your pipeline. Your KO_custom stays current through frontier model upgrades automatically.
• Cheaper verifiers, expensive planners. Planning errors cascade; verification errors are local. Spend the budget where a bad decision is costliest to undo.
• Branch on the artifact, not on text. When a stage's outcome has more signal than success/failure ("tests failed", "security issue found", "needs human review"), pick an outcomeRule that reads the structured field carrying that signal (e.g. fieldEnum:verdict for a Verify stage, fieldEnum:outcome for Review). The model emits the field; the orchestrator does the routing.
• Cap ambition with maxCostUsd. Even if the cap fires reactively (after the step finishes), it's still the fastest way to keep a runaway _self loop from draining a wallet.
• Test pipelines on small tasks. Edit your pipeline in the visual editor, switch to it with /pipeline <name>, and ask something cheap like "summarize README.md" to watch the flow execute before committing to an expensive run.

Ko uses model slots, abstract roles like code_frontier, code_planner, code_verifier, budget_fast. The platform admin maps each slot to a concrete model address (e.g. fc:anthropic/claude-sonnet-4.6). Pipelines reference slots, not concrete models, so the same pipeline works across model upgrades without edits.

19 providers are supported, routed through the platform pool for Fight Club models and directly for user-managed API keys:

OpenAI, Anthropic, Google, DeepSeek, Mistral, xAI (Grok),
Cohere, Groq, Together, Fireworks, Cerebras, SambaNova,
Perplexity, OpenRouter, Ollama, Azure OpenAI, Bedrock,
HuggingFace, Replicate

Override the model for a single session with -m, or swap mid-session with the /model command inside the TUI:

ko -m fc:openai/gpt-4o "summarize src/"
ko -m user:<config-id>/mistral-large "write a README"
/model   # list models; pick a number to switch for the rest of this session

The fc: prefix uses Fight Club's platform wallet; the user: prefix uses your own vault-encrypted provider config. Add your own provider keys at /settings on the dashboard.

Model picks are session-scoped, they are not persisted to disk. Closing the TUI and reopening it starts fresh with the pipeline's own per-step models. Swapping pipelines mid-session also drops any active override (see Pipelines). If you want a sticky preference, pass-m on every launch or configure it platform-side in your slot mapping.

Ko agents have 15 tools. Each pipeline step declares which subset it can use.

Pipelines also use auto-generated Emit{Schema} tools (one per stage, named after the stage's declared artifactSchema: EmitPlan, EmitImplement, EmitVerify, etc.). Each stage ends when the model calls its emit tool with a structured artifact; the orchestrator validates the artifact against the schema and the stage's contract rule, then transitions. You don't define these tools; the orchestrator wires them in per stage based on artifactSchema.

Skills are prompt + tool bundles that teach ko a specific domain or workflow (e.g. "write Next.js Server Components correctly", "apply these brand guidelines", "run this CI workflow"). The marketplace at /dashboard/skills lists installable community skills.

ko skills                    # list installed skills
ko skills install <id>       # install from the store
ko skills uninstall <name>   # remove a skill
ko skills update             # update all installed skills
ko skills create <name>      # scaffold a new skill in the current project

Skills are sourced from ~/.ko/skills/ (global) and .ko/skills/ (project-local). Global skills apply to every session; project skills only apply when ko runs in that directory.

Skill Seekers are a specialized skill that read external documentation URLs and cache them as an in-agent reference, point at any library's docs site and ko becomes an instant expert in that library.

Memory is a lightweight, file-based long-term store. Two scopes:

ko memory list           # list all memory files (global + project)
ko memory edit           # open ~/.ko/memory/MEMORY.md in $EDITOR
ko memory edit <file>    # open a specific memory file

Inside a session, ko writes to memory autonomously when you tell it something worth remembering ("I always use pnpm, not npm"), it'll save a memory file and recall it in future sessions. The index file MEMORY.md is loaded into every session's system prompt; individual memory files are loaded on demand.

The memory section above covers human-edited memory files. This section covers the vector-indexed surfaces ko manages for you: workspace index, cross-session memory, session scratchpad and audit log. Chunks are retrieved by meaning rather than by exact string match, which is the difference between "find the auth handler" landing the right file and returning nothing.

All four sit on the same Ringside vector_stores API that ships to external customers, so ko is its own biggest user of that infrastructure.

Workspace (ko workspace)

Indexes the repo so the agent can answer concept queries. A one-shot walk on first init, plus an fsnotify watcher that re-embeds changes with a 5-second debounce. The walker honors .gitignore and an optional .koignore for ko-specific exclusions. It skips files larger than 1 MB and sniffs the first 4 KB for null bytes to filter binaries. Files matching common secret patterns (.env, *.pem, id_rsa*, secrets.*) are never embedded.

ko workspace init           # walk the repo, embed every kept file
ko workspace init --no-watch   # skip the background fs-watcher
ko workspace sync           # one-shot reconcile after offline edits
ko workspace status         # show indexed/pending/skipped counts
ko workspace drop           # delete the workspace store entirely

The differentiator vs Cursor or Claude Code is that retrieval is semantic, not lexical. Ask "where do we rate-limit incoming webhooks" and the agent pulls the right middleware even if the file never uses the word "webhook". Internally the agent calls a VectorSearch tool, so retrieval is paid only when used and the chunks come back as cite-able tool output.

Cross-session memory (ko memory)

Opt-in. When enabled, every completed session is summarized by a cheap model (Gemini Flash or Haiku) and the summary is embedded into your personal episodic store. New sessions get the top 5 relevant past sessions prepended to the system prompt, and the agent can VectorSearch it mid-session if it wants more.

ko memory enable             # turn on episodic indexing, backfill the last 100 sessions
ko memory disable            # stop indexing new sessions, keep what's already there
ko memory status             # show enabled state, episode count, retention
ko memory search "<query>"   # forensic search across your own session history
ko memory export <path>      # dump every indexed episode as JSON
ko memory wipe --yes         # drop the store and soft-delete the episodes

Episodes older than 365 days detach from the vector store but stay in your archive (so memory export still returns them). Exclude patterns on the user record skip sessions matching a regex, --no-episodic on any individual ko -p run opts that one out.

The store lives server-side, so the memory follows the account rather than the laptop. Switch machines, sign in, the agent still knows what you were doing.

Session scratchpad (always on)

Tool outputs above 8 KB get uploaded to a per-session vector store and replaced in the running context with a short stub: [scratchpad:<file_id>] preview: ... (47213 bytes offloaded). The agent gets two retrieval paths back:

No flag, no setting. The scratchpad is an internal optimization. Long sessions stop paying input tokens on cold context and quality stops sliding late in the session. The per-session store self-destructs 24 hours after the session ends.

Audit (ko audit)

Opt-in. When enabled, every tool call from every session indexes one chunk into your audit store: session_id, timestamp, tool name, redacted args, success/error, a 256-char preview of the output and the scope tags the session ran under. Not the full output (that lives in the session log), just the needle-in-haystack lookup row.

ko audit enable                            # provision the store, backfill last 90 days
ko audit search "<query>"                  # natural-language search across all your sessions
ko audit search "<query>" --scope=release=production
ko audit search "<query>" --scope=*=*       # global, ignore the current session's scope
ko audit export --since=2026-04-01 > audit.jsonl
ko audit disable                           # stop indexing; raw events still persist in ko_session_events

Default retention is 90 days, configurable up to several years per scope. Sessions tagged release=production can carry a 2555-day (7-year) retention while everything else expires fast. The admin dashboard exposes a cross-user view at /admin/ko/audit/search for abuse review and compliance evidence.

Concrete use: you finished a 4-hour session yesterday and want to confirm the agent never read prod_secrets.env. ko audit search "prod_secrets" returns every chunk that mentions it. Zero matches is a real answer, not a hope.

Scopes (ko scope)

A scope is an ordered set of (category, value) tags that classifies what a session is doing. project=fightclub, release=production, customer=rubin, severity=p0 or any custom category you want. Every indexed chunk carries the session's scope tags, retention is set per scope, and searches can filter by any subset.

Resolution at session start, later overrides earlier:

1. workspace default (project=<workspace.display_name>)
2. .ko/scope.yaml at the repo root (per-branch overrides allowed)
3. KO_SCOPE env var
4. --scope CLI flag

ko scope                                                 # show the effective scope for cwd
ko scope list                                            # every scope you've ever touched, with use counts
ko scope settings release=production --audit-retention=2555   # 7-year retention for prod
ko scope settings customer=rubin --audit-enabled=true         # always audit Rubin work
ko scope settings project=secrets --scope-widening-locked=true # hard wall, see below

Scope as a privacy boundary. Default behavior treats scope as a convenience filter, the agent can widen beyond the session's scope on its own VectorSearch calls. Setting --scope-widening-locked=true flips that: when a session runs in that scope, the web tier rejects any scope_mode: global or scope_mode: override with a 403, and silently constrains scope_filter to the current scope. Enforced server-side at /api/ko/rag/search, not in the agent prompt, so a model that decides to try anyway gets blocked.

Retrieval is a tool, not an injection

Cursor and Continue.dev inject retrieved chunks into every model call. Linear cost in turns multiplied by context size, even when the agent didn't need RAG that turn, and the agent can't reason about why text appeared in its context. ko ships a VectorSearch tool the agent decides to call. You pay for retrieval only when it's used, and the chunks come back as tool output the agent can cite by source.

The system prompt lists which stores are available this session (workspace, episodic, session, audit) and when to prefer VectorSearch over Grep. Grep is faster and more precise for exact symbols, VectorSearch handles the synonym queries that grep misses.

Model Context Protocol (MCP) is how IDEs and other agents connect to external tools. Ko speaks MCP in both directions: it can expose itself as an MCP server for IDEs to consume, and it can consume other MCP servers as tools.

Ko as an MCP server. Any MCP-compatible client (Cursor, Windsurf, JetBrains with MCP plugin, VS Code with MCP extension, Claude Desktop) can use Knockout as a coding backend:

ko mcp show         # print the MCP config snippet for your IDE

# The snippet to paste into your IDE's MCP config:
{
  "knockout": {
    "command": "ko",
    "args": ["mcp-serve"]
  }
}

ko mcp-serve reads JSON-RPC from stdin, writes to stdout; logs go to stderr so they don't interfere with the protocol channel. Your IDE spawns it as a subprocess.

Ko consuming other MCP servers. Configure external servers in ~/.ko/settings.json under mcpServers. They appear as extra tools the agent can call, alongside the built-in 15.

Ko sync moves work between machines without exposing your code to the server. Snapshots are encrypted locally before upload with a key only you hold; the server stores opaque blobs and cannot read your code.

ko sync push                # encrypt the working tree and upload
ko sync pull [snapshot-id]  # download and decrypt a snapshot (latest if omitted)
ko sync snapshots           # list available snapshots

# Also as slash commands inside the TUI:
/sync push
/sync pull
/sync list

The encryption key is derived from your vault password. Lose the vault password and there is no recovery, the snapshots are unreadable. Set a vault password at /settings on the dashboard; it's never sent to the server.

Snapshots skip .git, node_modules, .next, __pycache__, vendor, .ko, .venv, dist, build, .cache, target, and binary artifacts (.exe, .dll, .so, .pyc, etc.).

Pipeline configs and session messages are also vault-encrypted on the server if you've set a vault password. When you open the dashboard, you unlock the vault once per browser session (30-minute TTL) to view or edit them.

Commands typed inside the TUI, starting with /.

65 project templates that aren't rigid starters. An interactive wizard at /dashboard/templates asks about your business, audience and style, then generates a bespoke project design. The result is a template ID (e.g. tp_abc123) you hand to the CLI:

ko build tp_abc123  # fetch the configured template and start a session

Categories cover business sites, e-commerce, SaaS, blogs, community, education, health, productivity, creative and food. Each template has 4-10 variants.

All ko config lives in ~/.ko/settings.json (global) and optionally .ko/settings.json (project-local, overrides global). Open in your $EDITOR:

ko config

Known keys:

Note: the older defaultModel key is no longer honored. Model picks are session-scoped and stale persisted values are wiped on startup. Pass -m or use /model instead.

{
  "trustedDirs": [
    "/home/me/work/project-a",
    "/home/me/work/project-b"
  ],
  "autoAllow": [
    "Read", "Glob", "Grep",
    "Bash(ls)", "Bash(cat)", "Bash(git)",
    "Bash(pwd)", "Bash(which)", "Bash(echo)"
  ]
}

Ko has multiple layers of defense to make sure you never pay for work you didn't authorize, or, conversely, that OpenRouter never bills us for requests whose cost we can't recover from you. Practical rundown of how they interact:

ESC cancellation

Hit ESC in the TUI at any time. The client POSTs to /api/ko/sessions/:id/abort without dropping the SSE socket. Server-side, the per-turn AbortController fires, the in-flight provider request is aborted, and you're charged only for the tokens that actually streamed before the abort, never the full budget of what the model would have generated.

A synthetic "[Turn cancelled by the user. Abandon any partial work above…]" marker is appended to the conversation so the next turn doesn't silently continue the cancelled task. If you then ask an unrelated question, the model treats it as fresh.

Live cost ticking

The Session $ counter in the status bar updates roughly every 750ms during streaming, not just at end-of-turn, so you can watch spend accumulate on long calls and hit ESC before a runaway model runs away further.

Hard per-call wallet cap

Before every fightclub-billed call we estimate the worst-case cost (input tokens plus the step's maxOutputTokens, or 32k default) and refuse to start the request if it could exceed your wallet balance. This prevents the bad case where OpenRouter bills us for tokens that atomic chargeUsage then refuses to charge you. Applied to both single-call and multi-model steps.

Idle watchdog

The CLI sends a heartbeat ping every 30 seconds while connected. If the server goes 90 seconds without any client activity (heartbeat, message, tool result, …) while a turn is in flight, it aborts the turn. Catches network drops, laptop sleep and browser refresh, anything that would otherwise leave the agent loop billing into the void.

Inside the TUI: