# Kaptain Docs

Everything about installing, setting up and running Kaptain on one page. Commands come with their real output, and every setting, tool and error is explained.

Version: Kaptain 0.0.9 · Updated 4 November 2026 · Page: https://chynj.ca/kaptain/docs/

<!-- Part: Start -->

## Overview

Kaptain is one program that runs on your own computer and gives your AI work a single home. Every model you use sits in one picker: local models through Ollama or llama.cpp, cloud models with your own API keys, and the Claude Code and Codex command-line assistants you already sign in to. They share one set of tools, one approval gate, one record of what ran, and one project folder that you choose.

Most AI desks are several tools taped together: a chat subscription, a terminal assistant, a local model runner and a scheduler. None of them share context, tools, permissions or an audit trail, so nothing composes. Kaptain puts all of that in one local runtime. A scheduled agent can hand mechanical work to a local model, using the same tools and leaving the same trace as a live chat.

### What Kaptain is made of

| Part | What it gives you |
|---|---|
| The binary | One file per platform. It serves the web interface, runs the tools and talks to your models. There is no installer service and nothing else to install for Kaptain itself. |
| The workbench | The browser interface, at `http://127.0.0.1:8810` by default: chat, files, tools, agents, traces and settings. |
| Model routes | Ollama, GGUF files through llama.cpp, cloud APIs with your keys, and the Claude Code and Codex CLIs. Mixed freely, changeable per chat and per agent. |
| Krew | The toolbelt models use: files, shell, tests, git, web, code search, delegation, memory and agents. Every risky call passes one approval gate. |
| Kapsules | Agents defined as a folder: a model wrapped with a persona, tools, permissions, memory and an optional schedule. |
| KodeGraph | A graph of your project's code, so models are handed the relevant code instead of reading everything. |
| BlackBox | A record of every turn: the context that was sent, each tool call and its result, the reply and the tokens. |
| Network Access | This machine only, or your own Tailscale network. Kaptain has no internet-facing mode. |

### Where things run

Kaptain, your conversations, your settings, your API keys and your project files stay on your machine. CHYNJ's servers hold your account, your licence and your list of devices; a device is identified to them by a hash of its fingerprint. A cloud model you add receives what you send it, under your own key. Downloads Kaptain makes on its own are named where they happen in these docs.

### Quick start

On Linux or macOS:

```sh
$ curl -sL https://chynj.ca/install.sh | sh
$ kaptain start
```

If the installer asks you to add Kaptain to your PATH, do that first ([PATH step](https://chynj.ca/kaptain/docs/#path)). `kaptain start` then opens the setup wizard in your browser. On Windows, download `kaptain-windows-x64.exe` and double-click it. The [install](https://chynj.ca/kaptain/docs/#install) and [first run](https://chynj.ca/kaptain/docs/#first-run) chapters walk through every step, and [Your first 10 minutes](https://chynj.ca/kaptain/docs/#first-10-minutes) takes it from there.

### How to read these docs

- **One page.** Every topic lives here once. Press <kbd>/</kbd> to filter the contents, or search the page with your browser.
- **Version 0.0.9.** Everything here is true for Kaptain 0.0.9. The page is updated when a new version ships; the [release notes](https://chynj.ca/insights/release-notes/) list what changed.
- **Commands.** Lines starting with `$` are commands. The Copy button copies the commands only, never the prompt or the output.
- **Output.** Output blocks show what Kaptain prints on Linux. Names, paths, process ids and numbers will differ on your machine.
- **Values are examples, not rules.** Kaptain is built to be configured. Where a page shows a value, it is the default or one person's choice. The [Settings reference](https://chynj.ca/kaptain/docs/#settings) says what each setting does so you can choose for your own machine and work.
- **For agents.** The same content is published as Markdown at [/kaptain/docs/index.md](https://chynj.ca/kaptain/docs/index.md).

- [Install](https://chynj.ca/kaptain/docs/#install) — Linux, macOS and Windows, with the real installer output and the PATH step.
- [First run](https://chynj.ca/kaptain/docs/#first-run) — Start Kaptain, finish the setup wizard and save your access code.
- [Your first 10 minutes](https://chynj.ca/kaptain/docs/#first-10-minutes) — Pair a browser, pick a model, let it use a tool and read how the turn ended.
- [Customise before your first run](https://chynj.ca/kaptain/docs/#customise) — The settings worth choosing on purpose before you rely on Kaptain.
- [Models and runtimes](https://chynj.ca/kaptain/docs/#models) — Ollama, GGUF, CLI harnesses and cloud APIs, and when to use each.
- [Kapsules](https://chynj.ca/kaptain/docs/#kapsules) — Agents with their own model, tools, permissions, memory and schedule.
- [CLI reference](https://chynj.ca/kaptain/docs/#cli) — Every `kaptain` command, its flags and its output.

## Install

Kaptain is one binary. Installing it never needs administrator rights, never adds a system service and never starts anything on its own.

### Requirements

| You run | Build | Download |
|---|---|---|
| Linux on Intel or AMD, 64-bit | `linux-x64` | [/download/kaptain/linux-x64](https://chynj.ca/download/kaptain/linux-x64) |
| Linux on 64-bit ARM (Raspberry Pi 4 and 5 with a 64-bit OS, Jetson) | `linux-arm64` | [/download/kaptain/linux-arm64](https://chynj.ca/download/kaptain/linux-arm64) |
| macOS 12 or later, Apple silicon | `macos-arm64` | [/download/kaptain/macos-arm64](https://chynj.ca/download/kaptain/macos-arm64) |
| macOS 12 or later, Intel | `macos-x64` | [/download/kaptain/macos-x64](https://chynj.ca/download/kaptain/macos-x64) |
| Windows 10 or 11, 64-bit | `windows-x64.exe` | [/download/kaptain/win](https://chynj.ca/download/kaptain/win) |

There are no builds for Windows on ARM, 32-bit ARM (such as 32-bit Raspberry Pi OS), 32-bit x86 or RISC-V. The Linux builds are statically linked, so any distribution works. To check which build a Linux or macOS machine needs:

```sh
$ uname -sm
Linux x86_64
```

`x86_64` means `linux-x64` (or `macos-x64` on a Mac), and `aarch64` or `arm64` means the ARM build.

**What else the machine needs depends on the models you choose.**

- **Kaptain itself** needs the binary, plus about 180 MB of disk if you choose Kaptain's built-in code search, more on a machine with a GPU, where it downloads a GPU build of llama.cpp (see [Start Kaptain](https://chynj.ca/kaptain/docs/#start)).
- **A CLI harness or a cloud model** needs nothing else on this machine.
- **Local models** need memory for the model. The setup wizard's starter models are the Qwen3.5 family, from 0.8B (a 1.3 GB download through Ollama) to 122B-A10B (81.4 GB). The wizard measures this machine's memory, marks each model **Fits this machine** or **Needs more memory**, and recommends the largest one that fits.
- **A GPU is optional.** NVIDIA, AMD and Apple GPUs are detected and used automatically, by Ollama and by the llama.cpp build Kaptain downloads for GGUF files ([GGUF](https://chynj.ca/kaptain/docs/#gguf)). Everything also runs on the CPU, more slowly.

### Install on Linux

The installer checks CHYNJ's signature on the release, downloads the right build, checks its SHA-256, and puts it in `~/.local/bin`:

```sh
$ curl -sL https://chynj.ca/install.sh | sh
```

```output
  Kaptain for CHYNJ
  ──────────────────
  Platform : Linux / x86_64
  Dest     : /home/you/.local/bin/kaptain

  Checking the release signature...
  Release  : <version> — signature verified (openssl)

######################################################################## 100.0%

  Checking the download...
  Checked  : size and SHA-256 match the signed release

  Add Kaptain to your PATH — paste this into your shell profile:
    export PATH="$HOME/.local/bin:$PATH"

  Installed <version> (release signature, size and SHA-256 checked before it ran).

  Next: `kaptain start` — your browser opens setup.

  It opens at http://127.0.0.1:8810.
  Your 3-day trial starts when you create your CHYNJ account in setup. No card needed.
```

`<version>` is the release's version name. What the installer does, in order:

1. Detects your platform with `uname`, and stops with a clear message on one that has no build.
2. Downloads the release manifest (`releases.chynj.ca/version.json`, the same file [`kaptain update`](https://chynj.ca/kaptain/docs/#update) reads) and checks its signature against CHYNJ's release key, which is written into the installer.
3. Downloads the build to a temporary file next to the destination, and checks its size and SHA-256 against the signed manifest.
4. Runs the checked binary once. If any check fails, the download is deleted, any existing Kaptain is left untouched, and the installer says why.
5. Moves it into place as `~/.local/bin/kaptain`. An existing Kaptain is updated in place: the same data folder, access code, device and licence, with the old binary kept as `kaptain.bak`. A running Kaptain is restarted onto the new binary only when no turn is running.
6. Prints the `export PATH` line if `~/.local/bin` is not on your PATH. It never edits your shell profile.

> [!NOTE]
> The signature check needs `openssl` 1.1.1 or newer, or `ssh-keygen` from OpenSSH 8.1 or newer; macOS uses the second. The trial does not start at install. It runs for 3 days from when you create your CHYNJ account, normally in the setup wizard, or from this machine's first trial if that was earlier.

- **If the installer printed "Add Kaptain to your PATH"**, do the [PATH step](https://chynj.ca/kaptain/docs/#path) next, or `kaptain` will not be found.
- **To update later**, run the installer again: it updates Kaptain to the newest published build. If that version is already installed it says `already installed (verified) — nothing to change`; to install it again anyway, run `curl -sL https://chynj.ca/install.sh | KAPTAIN_REINSTALL=1 sh`.

**Without the installer:** download the build from the table above, then:

```sh
$ chmod +x ~/Downloads/kaptain-linux-x64
$ mkdir -p ~/.local/bin
$ mv ~/Downloads/kaptain-linux-x64 ~/.local/bin/kaptain
```

- The browser saves the file under its build name, such as `kaptain-linux-x64`. Rename it to `kaptain` and keep it in a folder you own.
- [`kaptain update`](https://chynj.ca/kaptain/docs/#update) replaces the binary where it is, and [`kaptain uninstall`](https://chynj.ca/kaptain/docs/#update) looks for a file named `kaptain`. A copy moved into `/usr/local/bin` with `sudo` can be neither updated nor removed by Kaptain.

### Install on macOS

The same installer works on macOS 12 or later.

- **You should see** the same output as on Linux, with `Platform : Darwin / arm64` on Apple silicon or `Darwin / x86_64` on Intel.
- The `Release` line says `signature verified (ssh-keygen)`, because macOS's own `openssl` cannot check this signature.

```sh
$ curl -sL https://chynj.ca/install.sh | sh
```

**Without the installer:** download `kaptain-macos-arm64` (Apple silicon) or `kaptain-macos-x64` (Intel). The macOS builds are not yet notarized by Apple, so a file downloaded in a browser is blocked the first time it runs. Clear the block, make the file executable and move it into place:

```sh
$ chmod +x ~/Downloads/kaptain-macos-arm64
$ xattr -d com.apple.quarantine ~/Downloads/kaptain-macos-arm64
$ mkdir -p ~/.local/bin
$ mv ~/Downloads/kaptain-macos-arm64 ~/.local/bin/kaptain
```

- Instead of `xattr`, you can run it once and then choose **System Settings › Privacy & Security › Open Anyway**.
- The installer is not affected, because files fetched with `curl` are not quarantined.
- Double-clicking the binary in Finder opens Terminal and prints the command list; start Kaptain with `kaptain start` once it is on your [PATH](https://chynj.ca/kaptain/docs/#path).

### Install on Windows

Download [kaptain-windows-x64.exe](https://chynj.ca/download/kaptain/win) and run it. The commands on this page for Windows are **PowerShell** commands: open **PowerShell** from the Start menu, not the old Command Prompt, where `$env:LOCALAPPDATA` means nothing (Command Prompt writes the same folder as `%LOCALAPPDATA%`).

Before you run a file you downloaded in a browser, you can check it against the SHA-256 CHYNJ published. In PowerShell, go to your Downloads folder first:

```powershell
PS> cd $HOME\Downloads
PS> $m = Invoke-RestMethod https://releases.chynj.ca/version.json
PS> (Get-FileHash .\kaptain-windows-x64.exe -Algorithm SHA256).Hash -eq $m.assets.'kaptain-windows-x64.exe'.sha256
True
```

`True` means it matches. `False` means delete it and download it again. In Git Bash, the [installer script](https://chynj.ca/kaptain/docs/#install-linux) works too: it downloads the `.exe` into the current folder and checks it the same way, but never runs it.

1. Windows SmartScreen may say "Windows protected your PC", because the build is not yet signed. Choose **More info**, then **Run anyway**. This happens once.
2. Double-clicking the file starts Kaptain in the background and opens your browser on the setup wizard. The console window closes by itself; Kaptain keeps running.
3. To use it from a terminal, do the [PATH step](https://chynj.ca/kaptain/docs/#path) for Windows. Then `kaptain start`, `kaptain status` and `kaptain stop` work from PowerShell.

From PowerShell in the download folder, without renaming:

```powershell
PS> .\kaptain-windows-x64.exe start
```

Run with no command from a terminal, the binary prints its command list and exits. Models' shell commands on Windows run through Git Bash; see **Agent Shell (Windows)** in the [Settings reference](https://chynj.ca/kaptain/docs/#settings-runtimes).

### Add Kaptain to your PATH

The installer puts Kaptain in `~/.local/bin`. Your shell finds `kaptain` only if that folder is on your PATH, and the installer never edits your shell settings for you. Skip this step if `kaptain version` already works in a new terminal.

**bash (most Linux)**
```sh
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc
```
**zsh (macOS)**
```sh
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc
```
**fish**
```sh
$ fish_add_path ~/.local/bin
```
**Windows (PowerShell)**
These are **PowerShell** lines; open PowerShell from the Start menu, not Command Prompt. The first line goes to the folder the browser downloaded to:

```powershell
PS> cd $HOME\Downloads
PS> New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Programs\Kaptain"
PS> Move-Item .\kaptain-windows-x64.exe "$env:LOCALAPPDATA\Programs\Kaptain\kaptain.exe"
PS> [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Programs\Kaptain", "User")
```

Then close PowerShell and open a new window, so it reads the new PATH. What the lines do, and where things are:

- `$env:LOCALAPPDATA` is your own `C:\Users\<your name>\AppData\Local`. Every Windows account has its own, under its own user folder, so each person who uses the computer has their own folder and their own Kaptain.
- The `New-Item` line creates the folder `Programs\Kaptain` inside it. `cd "$env:LOCALAPPDATA\Programs\Kaptain"` works only after that line has run.
- `AppData` is a hidden folder, so Explorer does not show it while you click through your user folder. To open it, run `explorer $env:LOCALAPPDATA` in PowerShell, or paste `%LOCALAPPDATA%` into Explorer's address bar and press Enter.
- In Command Prompt the same folder is `%LOCALAPPDATA%`: `cd %LOCALAPPDATA%\Programs\Kaptain`.

**Two folders, kept apart.** The program is `%LOCALAPPDATA%\Programs\Kaptain\kaptain.exe`. Kaptain's data, `kaptain.json` with your access code, your chats (`sessions.db`) and your models list and keys (`models.db`), is in `%LOCALAPPDATA%\Kaptain\`, which Kaptain creates on its first start ([The data folder](https://chynj.ca/kaptain/docs/#data-folder)). Deleting the program leaves the data; [`kaptain uninstall`](https://chynj.ca/kaptain/docs/#uninstall) removes both.

Then open a new terminal and [check the install](https://chynj.ca/kaptain/docs/#verify-install). Not sure which shell you use? `echo $SHELL` prints it. To start Kaptain without changing your PATH, use the full path instead: `~/.local/bin/kaptain start`.

### Check the install

```sh
$ kaptain version
kaptain <version>
claude sidecar: embedded (linux-amd64, <size> MB)
```

- **You should see** the version name of this build on the first line. The second line says whether this build carries the helper Kaptain uses to run Claude; [`kaptain sidecar check`](https://chynj.ca/kaptain/docs/#cli-sidecar) tests that it runs on this machine. `kaptain --version` and `kaptain -v` print the same.
- **If the shell says `command not found`**, do the [PATH step](https://chynj.ca/kaptain/docs/#path).
- **If an older `kaptain` answers**, another copy earlier on your PATH shadows it: `type -a kaptain` lists every copy the shell can see.

## First run

The first run is three things in order: start Kaptain, answer the setup wizard (in your browser, or in the [terminal](https://chynj.ca/kaptain/docs/#setup-terminal) on a machine without one), and keep the access code it shows you. You agree to CHYNJ's [Terms of Service](https://chynj.ca/legal/terms/) before you download Kaptain from chynj.ca, where the install dialog asks first, and before your CHYNJ account is created, in setup or at [chynj.ca/account](https://chynj.ca/account/). Signing in uses that account; it does not ask again.

### Start Kaptain

```sh
$ kaptain start
kaptain started (pid 3150395)
  UI:    http://127.0.0.1:8810
  bind:  127.0.0.1:8810
  logs:  /home/you/.local/share/kaptain/kaptain.log
  stop:  kaptain stop
```

- **Do.** Open a terminal in your home folder, or in the project you want to work in, and run `kaptain start`.
- **You should see.** The lines above, then your browser opening on the setup wizard. `kaptain start` waits up to 30 seconds for the web interface to answer before it opens the browser.
- **If nothing happens.**
    - `command not found`: Kaptain is not on your PATH yet. Do the [PATH step](https://chynj.ca/kaptain/docs/#path), or run `~/.local/bin/kaptain start`.
    - The browser did not open: open the `UI:` address it printed, `http://127.0.0.1:8810`, yourself.
- **Why.** `kaptain start` runs Kaptain in the background, in its own session, so closing the terminal does not stop it. A fresh install lands on the setup wizard.

What Kaptain does on its own around the first start:

- **It may start Ollama.**
    - If Ollama is installed but not answering, Kaptain starts it.
    - An Ollama that is already running is never reconfigured or restarted, and Kaptain only ever stops an Ollama it started itself.
    - Kaptain never installs Ollama on its own; on Linux it offers **Install Ollama for me** in the setup wizard and in Settings.
- **It downloads nothing for code search until you choose.**
    - The setup wizard asks how code search should work (or you choose later under **Settings › Model Handling › KodeGraph Embedder**).
    - With Kaptain's built-in runtime, it downloads llama.cpp release b10106 for this machine (from the llama.cpp releases on GitHub: about 20 to 60 MB for the CPU build, more for a GPU build) and the nomic-embed-text model (146 MB, from Hugging Face) into the data folder, about 180 MB in all with the CPU build.
    - A `llama-server` you installed yourself (build 6000 or newer) is used instead of the llama.cpp download.
    - If the downloaded build cannot start because a system library is missing, **Install llama.cpp now** under **Settings › Model Handling › KodeGraph Embedder** names the library and offers to install it.
    - Choosing Ollama, None or a custom endpoint downloads nothing. Without an embedder, [KodeGraph](https://chynj.ca/kaptain/docs/#kodegraph) ranks by keywords.
    - `KAPTAIN_EMBED_PREPROVISION=0` stops every background code-search download.
- **It may pull an embedding model into Ollama**, but only if you chose Ollama for code search and Ollama has none. It pulls `nomic-embed-text`.

> [!NOTE]
> Kaptain works inside one project folder. Until the wizard sets one, it is the folder you ran `kaptain start` from, so run the first start from your home folder or the project you want to work in.

### The setup wizard

The wizard runs once in your browser, and everything it sets can be changed later in Settings.

- The progress bar shows seven steps; the install step appears only when something is downloading.
- Every step from the second to the network step has **← Back**.
- If you refresh the page, the wizard comes back to the first step you have not finished, still tracking any downloads.
- Each step below says what to do, what you should see, what to do if nothing happens, and why the step is there.

1. **Account**
    - **Do.** Press **Sign in** and sign in to your CHYNJ account, or press **Create account** and tick **I agree to the Terms of Service and Privacy Policy**. Passwords are at least 12 characters. If your account uses two-factor sign-in, the wizard asks for the 6-digit code.
    - **You should see.** The Plan step. Signing in to an account you already have does not ask again. A new account works at once; its free trial waits until you verify your email.
    - **If nothing happens.** The box and **Create account** stay off until the wizard has read the current Terms from CHYNJ; if it cannot, it says "Can't confirm the current Terms right now; try again shortly." with **Try again**. If the Terms change while the form is open, the wizard shows the new ones, unticks the box and asks again. From a place CHYNJ cannot serve, no account is made and the wizard says why.
    - **Why.** The account holds your licence and trial, and CHYNJ records which versions of the Terms you agreed to, and when. An account is required. Kaptain itself has no sign-in, and the account is not how a browser reaches it (that is the access code).
2. **Plan**
    - **Do.** Press **Start Free Trial**. With a paid plan, open **Have a license key?** and save your key (`KAPTAIN-XXXXXXXX-XXXX-XXXX`) on this machine instead.
    - **You should see.** Your plan's state. The trial is 3 days on this machine, with no card; the 3 days count from when your CHYNJ account was created, or from the first trial on this machine if that was earlier. With a paid plan, this step may still offer the trial on a new machine.
    - **If nothing happens.**
        - **Connect to verify your plan** with **Retry**: the wizard cannot reach CHYNJ. It needs an internet connection.
        - A key typed with no account signed in is refused with "A licence key alone never registers this computer — sign in to your CHYNJ account" and the button **Sign in to your CHYNJ account**, which goes back to the account step and keeps the key for you.
        - If CHYNJ refused this machine, for example because its trial was already used, the step's title is CHYNJ's reason, with a box for a licence key and **Save key & Continue**.
    - **Why.** The wizard says it plainly: "A licence key alone never registers a computer. Signing in is always required." **Finish setup** registers the machine on your paid licence because you are signed in ([How a computer gets registered](https://chynj.ca/kaptain/docs/#how-registered)). The trial belongs to this machine; reinstalling does not restart it.
3. **Models**
    - **Do.** Under **Choose your models**, tick what you want to use: one box each for the Claude CLI, the Codex CLI, Ollama and llama.cpp. Choosing nothing is fine, and you can tick both CLIs.
    - **You should see.** For each one, whether it is here and where it was found, starter models sized to this machine's memory, and how to install what is missing. The first box you tick (Claude, Codex or an Ollama model) becomes the default.
    - **If something is missing.** A missing CLI shows its own one-line installer to copy. **Install llama.cpp for me** downloads the official llama.cpp build ([GGUF](https://chynj.ca/kaptain/docs/#gguf)); on Linux, **Install Ollama for me** asks for your computer password once and runs Ollama's installer. The page re-checks every few seconds.
    - **Why.** This chooses your default model. You can switch per chat later.
4. **Installing**
    - **You should see.** One row per download, with its progress until it reports Installed. This step appears only when something is downloading.
    - **If it fails.** The row shows the reason, with **Retry**.
5. **Project**
    - **Do.** Under **1 · Project folder**, pick a folder with the folder picker, which suggests a new folder and creates it, or type the full path of an existing folder. Under **2 · Semantic code search**, choose **Use Ollama**, **Use Kaptain's built-in runtime (llama.cpp)** or **None — keyword-only search**.
    - **You should see.** The folder accepted. Kaptain adds a `.kodegraph/` index there.
    - **If nothing downloads.** That is expected with Ollama or None: only the built-in runtime downloads anything ([Start Kaptain](https://chynj.ca/kaptain/docs/#start)).
    - **Why.** Kaptain works inside one project folder, and code search is how it finds code by meaning.
6. **Network**
    - **Do.** Under **Who can reach Kaptain?**, keep **Local only** (recommended, preselected) or choose **Remote + local — Tailscale**, then press **Finish setup**.
    - **You should see.** Tailscale offered only when it is installed and connected ([Network and remote access](https://chynj.ca/kaptain/docs/#network)).
    - **If registration fails.** The wizard says why and setup stays open. The usual causes are an unverified email on a trial account, a trial already used on this machine, or a licence that already has its maximum number of devices. CHYNJ also refuses accounts, trials and licence renewals from places Canadian sanctions law does not let it serve ([Licence and devices](https://chynj.ca/kaptain/docs/#licence)).
    - **Why.** Local only means nothing off this machine can connect. **Finish setup** is the moment this machine is registered with your account.
7. **Done**
    - **You should see.** **You're all set**, with **Your access code — save it now** and **Copy code**. The code is shown once.
    - **Do.** Copy the code somewhere safe ([Your access code](https://chynj.ca/kaptain/docs/#access-code)). If you chose Tailscale, press **Restart Kaptain now**: it restarts Kaptain on the tailnet address and reopens the page there. **Not now — open Kaptain here** waits for your next restart.
    - **Why.** Any other browser or device asks for this code before it can use this Kaptain.

### Your access code

- **What it is.** `chynj_` followed by 48 characters, shown **once** on the done screen, with a copy saved to `access-code.txt` in the data folder, readable only by your user. Copy it somewhere safe.
- **What it is for.** Any other browser or device asks for it before it can use this Kaptain. CHYNJ never receives or stores the code itself, only a salted hash of it.
- **Whose it is.** The access code belongs to this Kaptain, not to your CHYNJ account. You sign in to your CHYNJ account at chynj.ca or in setup; that is how the machine gets its licence. There is no sign-in to Kaptain itself: a browser reaches this Kaptain on this machine, or over your tailnet, with the access code. Connection codes for [lending models](https://chynj.ca/kaptain/docs/#pairing) are issued from it in Settings.
- **Open Kaptain** signs this browser in, for 14 days at a time. In Local only mode the done screen says to open `http://127.0.0.1:8810` in a browser on this machine. In Tailscale mode it shows **One restart to finish** with **Restart Kaptain now**, because the tailnet address answers only after the restart.

> [!WARNING]
> Nothing in Kaptain shows the access code again. `kaptain status` prints where it is: `access-code.txt` while that file exists, otherwise `api_token` in `kaptain.json`. Delete `access-code.txt` once your devices are paired. To replace the code, see [Get a new access code](https://chynj.ca/kaptain/docs/#access-code-new).

### Get a new access code

- **When.** The code may have leaked, or you want to sign out every browser at once.
- **Where.** In Settings, or in a terminal on the computer where Kaptain runs. Kaptain does not need a restart either way.

**In Settings**

- **Do.** Open **Settings › Network Access › New access code**, type the current code and press **New access code**.
- **You should see.** The new code once, with **Copy**. It is saved to `access-code.txt`, and the browser you used stays paired.
- **If it is refused.** Typing the current code is the confirmation: a wrong code changes nothing, and after a few wrong tries in a minute Kaptain asks you to wait.

**In a terminal**

- **Do.** Run `kaptain access-code rotate`. It asks for no current code, because whoever can run it on this computer can already read `kaptain.json`.
- **You should see.** The new code, printed once:

```output
Kaptain made a new access code for this computer.
  Access code (shown once — save it): chynj_…
  Saved to /home/you/.local/share/kaptain/access-code.txt (only you can read it).
  The old code has stopped working: every browser and device must pair again with the new one.
  Cluster tokens you issued to other Kaptains keep working; cancel any of them in Settings › Network Access.
  The running Kaptain (pid 4121449) uses the new code now.
```

**Either way**

- The old code stops at once. Every other browser and device paired with it, tabs already open included, shows **Pair this browser with Kaptain** and needs the new code; scripts that send the old code get `401`.
- [Connection codes](https://chynj.ca/kaptain/docs/#pairing) you issued to other Kaptains keep working: they are separate credentials, and each one is cancelled on its own under **Settings › Network Access**.

**Kaptain serves only with a code it made**

- Once setup is done, a code that is empty, shorter than 32 characters after `chynj_`, or has characters a generated code never has is refused.
- `kaptain start` and `kaptain serve` stop with one line naming the file and the way back, `kaptain status` shows the same line, and every request gets `401` with `access_code_refused`:

```output
kaptain: the access code (api_token) in /home/you/.local/share/kaptain/kaptain.json is too short (4 characters; Kaptain makes codes of 32 or more) — Kaptain will not serve with it; run "kaptain access-code rotate" to get a generated one
```

- The way back: run `kaptain access-code rotate`, then `kaptain start`.

**By hand, as a fallback.** If you cannot run `kaptain` on that computer, put a generated code in place yourself:

1. Stop Kaptain: `kaptain stop`.
2. Make a code of the shape Kaptain makes. On Linux or macOS, this prints one; copy it:
    ```sh
    $ echo "chynj_$(openssl rand -hex 24)"
    ```
3. Open `kaptain.json` in the [data folder](https://chynj.ca/kaptain/docs/#data-folder) in a text editor (`~/.local/share/kaptain/kaptain.json` on Linux). Replace the value of `"api_token"` with the new code, keep the quotes, change nothing else, and save. Delete `access-code.txt` in the same folder if it is there: it holds the old code.
4. Start Kaptain: `kaptain start`.
5. Pair every browser and the app again. Each one shows **Pair this browser with Kaptain**; enter the new code.

- The access code is this Kaptain's own. It is not your CHYNJ account and not its password: a new access code changes nothing in your account, and changing your account password does not change the access code.
- [`kaptain device register`](https://chynj.ca/kaptain/docs/#device-register) keeps the access code: it registers the machine through an approval at chynj.ca and changes nothing paired.

### Set up from the terminal

On a machine without a browser, such as a server or a Raspberry Pi, the same setup runs in the terminal, against the same steps as the browser wizard. Stop Kaptain first, because the terminal wizard serves on the same port while it runs:

```sh
$ kaptain setup
```

It asks one question at a time. Pressing Enter takes the answer shown in brackets `[ ]` when there is one, else the one in parentheses `( )`. The password and licence key prompts do not show what you type. Step by step:

1. **Account.** `Sign in, create an account, or skip for now? [signin/signup/skip]:`
    - `signin` asks `Email:` and `Password:`, and `Enter your 6-digit authenticator code:` if your account uses two-factor sign-in.
    - `signup` prints the links to the Terms of Service and the Privacy Policy and asks `Do you agree to the Terms of Service and Privacy Policy? [y/N]:`. Only `y` (or `yes`) goes on, to `Name:`, `Email:` and `Password (12+ chars):`. Any other answer stops setup, and no account is made. Setup also stops, with the reason and no account, when Kaptain cannot read the current Terms from CHYNJ, or when CHYNJ refuses the account, for example because you are connecting from a place it cannot serve. Once the account is made it says "Account created. Its free 3-day trial started now (or with this computer's first trial, if that was earlier) — no card needed."
    - `skip` prints "Skipped — continuing without an account: this computer is not registered and no trial starts. Kaptain cannot be used until it is registered — run `kaptain device register` after setup." Setup still finishes; [register the machine](https://chynj.ca/kaptain/docs/#device-register) afterwards to use it. A failed sign-in prints its reason, then the same words.
2. **Plan.** It shows your plan's state, then `License key (Enter to skip):`. Press Enter unless you have a key. **A licence key alone never registers this computer — sign in.** Typed with no account signed in, a key is answered with that sentence and `Sign in now and keep this key? [Y/n]:`; Enter signs you in and keeps the key, so you never type it twice.
3. **Models.** Under `What this machine has:` it lists the Claude CLI, the Codex CLI, Ollama and llama.cpp, each Ready, Found or Not found, with where it was found. Then it asks only what applies here:
    - `Download llama.cpp b10106 for you now (into Kaptain's own folder, no administrator rights)? [y/N]:` when llama.cpp is missing.
    - `Install Ollama for you now? It installs a system service, so you will type this computer's password. [y/N]:` on Linux when Ollama is missing; `y` asks `This computer's password (for sudo):` once.
    - `Press Enter to go on — or type check to look again after installing or signing in` when something is missing that you install yourself, such as a CLI. Type the full path of a command Kaptain did not find to point it there.
    - `Use the Claude CLI? [y/N]:` and `Use the Codex CLI? [y/N]:` for each CLI that is installed. You can say yes to both.
    - `Ollama models Kaptain can download for you:` and `GGUF models Kaptain can download for llama.cpp:` list the [starter models](https://chynj.ca/kaptain/docs/#ollama), each marked for this machine's memory, then ask `Download which? Numbers separated by commas, Enter for none:`.
    - `Which should Kaptain use by default? [claude/codex/ollama] (claude):` when you chose more than one. You can switch per chat later.
4. **Project directory.** It offers `1) /home/you/Kaptain (a new folder, created now)` and, when you ran it from another folder, `2) this folder: …`, then asks `Choose 1 or 2, or type the full path of a folder [1]:`. A folder it cannot use is refused with the reason, and it asks again.
5. **Code search.** Right after the folder: `Which? [ollama/managed/none] (ollama):`. `ollama` uses Ollama. `managed` is Kaptain's built-in runtime, which downloads nomic-embed-text v1.5 (about 146 MB) when you answer. `none` is keyword-only search and downloads nothing. The default in parentheses is Ollama when it is running here, otherwise `managed`.
6. **Network.** `Who can reach Kaptain? [localhost/tailscale] (localhost):`. Enter keeps Kaptain on this machine only. `tailscale` is offered only when Tailscale is installed and connected, and is never preselected ([Network and remote access](https://chynj.ca/kaptain/docs/#network)).
7. **Done.** It prints `Kaptain is set up.` and `Access code (shown once — save it): chynj_…`, saves the code to `access-code.txt` in the data folder, and ends by telling you to run `kaptain serve` or `kaptain start`. If nothing can run a model yet, the first line says so and names what to add.

The models step onward, from a run on a machine that already had both CLIs, Ollama and llama.cpp, started from the home folder, with every download declined (trimmed, and this machine's paths shortened):

```output
3. Models

  What this machine has:
  Claude CLI  Ready — signed in · /home/you/.local/bin/claude
  Codex CLI   Ready — signed in · /home/you/.npm-global/bin/codex
  Ollama      Running · /usr/local/bin/ollama · 9 model(s) downloaded
  llama.cpp   Ready · /home/you/llama/llama.cpp/build/bin/llama-server
              Uses Vulkan0: AMD Unknown (RADV RENOIR) (34192 MiB, 33720 MiB free)
              4 chat GGUF model(s) found — ready to use.
  Use the Claude CLI? [y/N]: n
  Use the Codex CLI? [y/N]: n
  Ollama models Kaptain can download for you:
    1) Qwen3.5 0.8B — 1.3 GB · Fits this machine
    2) Qwen3.5 2B — 2.7 GB · Fits this machine
    3) Qwen3.5 27B — 17.5 GB · Fits this machine
    4) Qwen3.5 35B-A3B — 22.1 GB · Fits this machine (recommended)
    5) Qwen3.5 122B-A10B — 81.4 GB · Needs more memory — about 81.6 GB at an 8K context; this machine has 63.1 GB (61.5 GB after what the system needs)
  Download which? Numbers separated by commas, Enter for none: none
  ...

4. Project directory
  1) /home/you/Kaptain (a new folder, created now)
  Press Enter for 1, or type the full path of a folder [1]:

  Code search (KodeGraph)
  With Kaptain's built-in runtime, its embedding model (nomic-embed-text v1.5 (~146 MB)) downloads when you answer, so it finds code by meaning, not just keywords.
  Nothing downloads before that, and nothing ever with none.
    ollama   — use Ollama, detected at http://127.0.0.1:11434
    managed  — Kaptain's built-in runtime (llama.cpp), already present
    none     — keyword-only search: nothing is downloaded, noticeably weaker. You can turn it on later in Settings.
  Which? [ollama/managed/none] (ollama): none
  Kaptain will work in /home/you/Kaptain.

5. Network
  Tailscale detected at 100.x.y.z — choose tailscale to reach Kaptain from your other devices.
  Who can reach Kaptain? [localhost/tailscale] (localhost):

Kaptain is set up.
  Access code (shown once — save it): chynj_…
  Saved to /home/you/.local/share/kaptain/access-code.txt (only you can read it).
  This Kaptain is local-only: open http://127.0.0.1:8810 in a browser on this machine.
  To use it from your phone or another computer, turn on Tailscale in Settings ▸ Network Access.

Run `kaptain serve` (or `kaptain start`) to use Kaptain now.
```

Delete `access-code.txt` once your other devices are paired. A wizard stopped part-way goes on where it stopped the next time you run `kaptain setup`; the steps already done print one line each. On a machine that is already set up, `kaptain setup` changes nothing and says so: "Kaptain is already set up here — … Nothing to do. Change choices in Settings, or run `kaptain setup --force` to go through the wizard again (your access code, device and licence stay)." 

### Run setup again

- **In a browser** that is already paired with this Kaptain, open `http://127.0.0.1:8810/?force_setup=1` (or your tailnet address with `/?force_setup=1`). The wizard opens again with the choices on record filled in, including the network mode.
- **In a terminal**, stop Kaptain and run `kaptain setup --force`.
- **Either way** your access code, device and licence stay the same. To change one setting, use [Settings](https://chynj.ca/kaptain/docs/#settings) instead.

## Customise before your first run

Kaptain ships with defaults that work, but they are not tuned to your machine or your work. These are the settings worth choosing on purpose before you rely on Kaptain. Each one is a trade-off, and each can be changed later without losing anything. The examples come from one owner's setup and show the kind of choice you might make, not a recommendation for yours.

| # | Setting | Where | Default |
|---|---|---|---|
| 1 | Project folder | Settings › General › Project Directory | the folder Kaptain was started from |
| 2 | Your chat model | the model picker in Chat | the wizard's pick, remembered per browser |
| 3 | Tools and Delegate | the two switches next to the picker | off |
| 4 | Tool approval | the ⚙ next to the picker | Ask |
| 5 | Delegation worker and Summarizer | Settings › Model Handling | worker: none (**Choose a model**); summarizer: the worker, else a model on this machine |
| 6 | Context window for local models | the ⚙ next to the picker | at most 8192 on Ollama |
| 7 | Compaction | Settings › Model Handling › Context & Compaction | every 20 messages |
| 8 | Network mode | Settings › Network Access | Localhost only |
| 9 | Vision tool | Settings › Model Handling › Vision tool | Automatic |
| 10 | Run memory for scheduled agents | each kapsule's settings | off |

**1. Project folder.** Every tool a model uses (files, shell, skills, delegation) and the KodeGraph index are rooted here. A broad folder gives models more reach and makes indexing slower; a narrow one is faster and safer. A home folder is never re-indexed automatically. Set it under **Settings › General › Project Directory** with **Set & Index**; it applies immediately.

**2. Your chat model.** The wizard saves your first choice as the default. The model you pick in Chat is remembered by that browser, so a phone and a laptop can use different models. Agents without their own model use the default chosen at startup, so give each [kapsule](https://chynj.ca/kaptain/docs/#kapsules) an explicit model if it should not follow yours.

**3. Tools and Delegate.** Both switches in the Chat header start off, and this browser remembers how you leave them. With both off, a chat is plain conversation with no tool loop. Turn on **Tools** when you want the model to read files, run commands or search. **Delegate** hands mechanical work to the worker model and needs Tools on. The tool loop adds latency on a slow GPU, so leave it off for quick questions.

**4. Tool approval.** Each model has an approval mode: **Ask (default)**, **Ask before risky actions** (the two Ask choices behave the same), **Read-only**, **Auto-approve in workspace** or **Full access (unrestricted)**. Ask pauses for you before anything risky. Auto-approve and Full access run without prompts. For agents that run on a schedule, set the kapsule's own **Permissions** on purpose: on Ask, an unattended run stops at its first risky step. See [Tools and approvals](https://chynj.ca/kaptain/docs/#approvals).

**5. Delegation worker and Summarizer.** The worker runs delegated briefs, and the summarizer writes the rolling summary that keeps long chats inside the model's window. No worker is chosen for you: **Settings › Model Handling › Delegation** shows **Choose a model**, and delegation stays off until you pick one and press **Save**. With no summarizer chosen, Kaptain uses the worker, then a GGUF or Ollama model on this computer, then a model on a paired machine, then a cloud model; it never uses Claude or Codex for summaries unless you choose one. If no model can write the summary, Kaptain folds the older messages into a text-only summary without a model, and the chat's context card says so: "summarised without a model (none can chat) — pick a summary model in Settings".

> [!EXAMPLE] One owner's setup
> The summarizer is a small model on another of the owner's machines (`node:<their other computer>/gemma4:e4b`), so summaries cost this machine nothing. Any model in the picker can do this job, including one you lend yourself from another computer ([Pairing machines](https://chynj.ca/kaptain/docs/#pairing)).

**6. Context window for small local models.** The context window (`num_ctx`) is everything the model sees at once: instructions, tools, history and room for the reply. Ollama models default to half their advertised window, capped at 8192 tokens, even when the model advertises 128K or more. GGUF models default to half their advertised window, cut to fit your free memory. A bigger window holds more history and tool output but needs more memory: the cache grows with the window, and a 4B model at 131K tokens can need about 19 GB for it. Change it per model with the ⚙ next to the picker; the value is capped at the model's advertised maximum.

> [!EXAMPLE] One owner's setup
> A 1.5B Ollama model advertises 131,072 tokens and runs at 8,192, the default. A 26B model on the owner's other machine runs at 32,000 tokens with 24,000 for output, set on that machine and followed here.

**7. Compaction.** When a chat on a local or cloud model grows, Kaptain folds older messages into a summary. The defaults: compact after **20** new messages, always keep the **2** most recent verbatim, and write at most **1,200** words. A lower threshold keeps prompts small for small windows but summarizes more often. **Compact inside long turns** (off by default) lets a long tool-heavy turn summarize its own earlier steps and keep going. Claude and Codex manage their own context, so compaction does not apply to them.

> [!EXAMPLE] One owner's setup
> The owner keeps 20, 2 and 1,200 and turns **Compact inside long turns** on, so long tool-heavy turns finish instead of stopping at the window.

**8. Network mode.** **Localhost only** (the default) means nothing outside this machine can connect. **Tailscale** lets your own devices on your tailnet pair with this Kaptain, for example your phone. Changing the mode needs a restart, which the card offers as **Restart Kaptain now**, and in Tailscale mode even this machine reaches Kaptain at its tailnet address. See [Network and remote access](https://chynj.ca/kaptain/docs/#network).

**9. Vision tool.** When a model needs to look at an image, Kaptain hands it to the vision model. **Automatic** uses your chat model if it can see images, otherwise the first Ollama model that can. You can pick a local model, a GGUF with its projector file, a cloud model, a Claude or Codex CLI, or a model on a paired machine, and choose whether it may think first. See [Images and vision](https://chynj.ca/kaptain/docs/#vision).

**10. Run memory for scheduled agents.** Off by default: each scheduled run starts fresh from its task, the way you would brief a person. Turn **Remember previous runs** on only when a job builds on its own last answer, such as a tracker that must know what it already reported. See [Schedules and run memory](https://chynj.ca/kaptain/docs/#schedules).

Code search downloads its files only when you choose Kaptain's built-in runtime; [Start Kaptain](https://chynj.ca/kaptain/docs/#start) says what they are and how to stop them. Everything else, every setting and what it does, is in the [Settings reference](https://chynj.ca/kaptain/docs/#settings).

<!-- Part: Use -->

## Your first 10 minutes

Setup is done and Kaptain is running. This is the path from an empty screen to a model doing work in your project folder.

1. **Open Kaptain.** `kaptain start` opens your browser. Otherwise open `http://127.0.0.1:8810` on this machine, or `http://100.x.y.z:8810`, this machine's tailnet address, in Tailscale mode. A browser that has not paired yet shows **Pair this browser with Kaptain**: paste the [access code](https://chynj.ca/kaptain/docs/#access-code) (`chynj_…`) and press **Connect**. The browser stays paired for 14 days.
2. **Pick a model** in the picker at the top of **Chat**. It says **Choose a model** until one is chosen; [Pick a model](https://chynj.ca/kaptain/docs/#first-model) below says which kind to pick. Your choice is remembered in this browser.
3. **Ask something.** Type a question and press Enter. With **Tools** off, this is a plain conversation: fast, and nothing on your computer is touched.
4. **Let it work.** Turn on **Tools** next to the picker, then ask for something in your project, for example "List the files in this project and summarize the README." Each tool call the model makes folds under its answer; open one to see the request and the result.
5. **Answer a permission pop-up.** In the default **Ask** mode, anything that could change something stops at **Permission required** ("Kaptain is paused until you decide."), with **Review tool input**, **Deny** and **Allow once**. Reading inside the project never asks. [Tools, approvals and safety](https://chynj.ca/kaptain/docs/#tools) explains each mode.
6. **Read the status under the answer.** A turn that did not do its whole job says so in a line of its own ([Run status](https://chynj.ca/kaptain/docs/#run-status)).

### Pick a model

| You have | Pick | Thinking and effort |
|---|---|---|
| Ollama with a model pulled | its name, such as `qwen3.5:4b` | **Thinking** on or off; **Reasoning per step** for models that think |
| A GGUF file and llama.cpp | `gguf:<file>.gguf` | the same as Ollama |
| A cloud API key | `cloud:<model id>`, after **＋ Add a model… › Cloud API** | **Reasoning effort** when you ticked reasoning for it |
| Claude Code or Codex installed and signed in | `claude-cli` or `codex-cli` | **Reasoning effort**: the levels your installed Claude Code reports (low, medium, high, xhigh and max today); the levels your installed Codex reports for its model |

The ⚙ next to the picker holds these per model. **Thinking** shows the model's reasoning as it writes; off is faster and quieter. **Reasoning per step** sets how much a local or cloud model may think before each step: **Auto — sized from the room left in the window**, **No limit from Kaptain**, or **Fixed number of tokens**. **Reasoning effort** starts on **Provider default** (**CLI default** for a CLI). A control the model does not support is not shown. The [Models and runtimes](https://chynj.ca/kaptain/docs/#models) chapter has every route and setting.

**Switching models in the middle of a chat** is allowed at any time. The chat shows a divider, `model changed: <old> → <new>`, and the conversation goes on:

- **Between local and cloud models,** the new model gets the same conversation, with the summary of older messages if the chat was compacted.
- **To Claude or Codex,** the CLI starts its own thread from the conversation and any earlier summary.
- **From Claude or Codex to another model,** the CLI first writes a hand-over summary of its own thread (cards **EXPORTING CLI CONTEXT**, then **CLI HANDOFF READY**), and the last three messages go across word for word. A short chat, under 4 messages or 4,000 characters, goes across word for word with no summary. **Settings › Model Handling › Context & Compaction › Handoff written by** chooses who writes the summary. If it fails, **CLI HANDOFF FAILED** says why and the new model is not called.

### Run status

Every turn ends with one of five outcomes. The chat shows the word; BlackBox and the kapsule board show it too.

| The chat shows | Recorded as | What it means |
|---|---|---|
| nothing; BlackBox shows **Done** | `complete` | The turn finished: no change it made failed, and its review did not flag the final answer. |
| **Incomplete** — reason | `incomplete` | It finished, but a change failed and is not in place, or the final answer failed its review. The reason names it, such as "1 change failed and is not in place: …". |
| **Not verified** — reason | `unverified` | It finished, but the review could not judge the answer, for example "the review did not finish in time". |
| **ERROR** row with **Retry**, or **Failed** — reason | `failed` | The model returned an error, gave no answer, or the turn hit a limit. **Retry** sends the same message to the same model again. |
| **STOPPED** row | `stopped` | You pressed Stop, Kaptain shut down, or the browser disconnected. |

**A turn that stops early says why**, in words and with the setting behind it: for example `stall guard: no model output or tool progress for 12m0s (stall_timeout)`, or `stopped by the user: Stop was pressed`. Some limits do not end the turn but make the model answer with what it has, with a note in the chat: `tool-round budget reached (50 rounds)` (the `max_tool_rounds` setting) or `context window nearly full`. The [Troubleshooting](https://chynj.ca/kaptain/docs/#trouble-turns) table lists the reasons and what to change.

### When a tool result is too big

A model's window has room for only so much tool output. One result may use 15% of the window and all of a message's results together 30% (`tool_result_window_percent` and `turn_results_window_percent` in [`kaptain.json`](https://chynj.ca/kaptain/docs/#settings-json)). A result larger than its share is never cut and never lost:

1. Kaptain **saves the whole result**, in the run's record and as a file in `results/<session>/` in the data folder.
2. The model gets **a notice instead of the content**: how big the result is, its shape (a sketch of its fields or lines), the result id, and how to read it. It is told to say what part it read before it summarizes the result or claims something is not in it.
3. The model **reads the parts it needs by id** with `tool_result_recall`: one item, a search across all of it, or a page of lines.

The tool card in the chat shows `saved as <id> (N items); the model got a notice with how to read it`. When a turn's results have used most of their share, a note says so and the next results arrive the same way. [`tool_result_recall`](https://chynj.ca/kaptain/docs/#tool-tool-result-recall) has the parameters.

## The workbench

The workbench is Kaptain's browser interface. An activity bar on the left switches between eight views; the sidebar next to it shows what belongs to the current view.

| View | What it is for |
|---|---|
| **Chat** | The main conversation, with the model picker, the **Tools** and **Delegate** switches and the ⚙ model settings in its header. The sidebar lists saved chats. |
| **Views** | Two explorers. **Deview** opens, edits and previews the files, images and databases in your project, with project-wide search and Markdown rendered as an editor would; right-click a file or folder for **Copy path** or **Copy relative path**. **God's Eye** draws your project as a graph from the KodeGraph index. |
| **Krew** | The tools. **Native Tools** lists every built-in tool with its own switch, **MCP Servers** manages the servers you connect, and **Skills** holds instruction documents models can load. |
| **Kapsules** | Your agents. Each has its own chats, settings, schedule and jobs. |
| **Channels** | Chat surfaces outside Kaptain, each one your own bot run from this machine. |
| **BlackBox** | What happened: every turn's context, tool calls, reply and tokens, and model usage totals. |
| **Settings** | General, Model Handling, Runtimes and Network Access. See the [Settings reference](https://chynj.ca/kaptain/docs/#settings). |
| **Brain Logs** | Kaptain's own runtime log events. |

### Working in a chat

- **Pick a model** from the picker. It lists every model Kaptain can reach, grouped by route, and remembers your choice in this browser. If no model has been chosen yet, it says **Choose a model**. **＋ Add a model…** at the bottom adds Ollama, GGUF and cloud models.
- **Tools** lets the model use Krew tools in this chat. **Delegate** lets it hand bounded work to the [worker model](https://chynj.ca/kaptain/docs/#delegation); it needs Tools on.
- **Type `/`** for commands and installed skills. Skills also open from a `/` in the middle of a sentence; commands such as `/new` work only at the start. A Claude or Codex model also lists that CLI's own skills.
- **Attach files** with the paperclip. A model that cannot see images can have one described by the [vision tool](https://chynj.ca/kaptain/docs/#vision).
- **Steer a running turn.** On a local or cloud model, a message you send while the model works joins the running turn instead of waiting for it to end.
- **Every turn's tool calls** fold under its answer, and **Show result** lays each result out field by field. Older tool-heavy turns load as one line you can open, so long chats open quickly.
- **Long commands** a model started show in a strip above the chat box with **Stop** ([Long commands and background jobs](https://chynj.ca/kaptain/docs/#jobs)).
- **A failed run says why** in the chat, with **Retry** to send the same message to the same model again.
- **Questions come to you.** When a model needs a decision, including Claude's and Codex's own questions, a question card opens. **Skip — you decide** tells the model to choose and say what it assumed.
- **Links on this machine are checked.** When a reply from a local or cloud model points at an address on this machine or your own network, such as `http://localhost:8080`, Kaptain opens it before the answer goes out. A link that still does not answer gets a line under the reply, such as "✗ Kaptain checked http://localhost:8080 — not reachable: connection refused (nothing is listening there)."

Each kapsule has its own chats as well, so a question you ask an agent stays with that agent and never lands in your main chat.

## Models and runtimes

Kaptain reaches models four ways and treats them alike: every route works in chat, in kapsules, as the delegation worker and as the summarizer. Mix them freely.

| Route | Best when | What it needs |
|---|---|---|
| [CLI harness](https://chynj.ca/kaptain/docs/#cli-harnesses) (`claude-cli`, `codex-cli`) | You already use Claude Code or Codex and want their models with Kaptain's tools and scheduling | The CLI installed and signed in. No model download, no GPU. |
| [Ollama](https://chynj.ca/kaptain/docs/#ollama) | You want local models with the least effort | Ollama installed; memory for the model |
| [GGUF through llama.cpp](https://chynj.ca/kaptain/docs/#gguf) | You want a specific GGUF file and direct control | A `llama-server` binary; memory for the model |
| [Cloud API](https://chynj.ca/kaptain/docs/#cloud-models) | A low-powered machine, or a model only a provider hosts | An API key and the model id your account has |

A fifth source is another of your machines: once two Kaptains are [paired](https://chynj.ca/kaptain/docs/#pairing), the other machine's models appear in your picker under its name.

Spend strength where it matters. A strong model is worth it for ambiguous reasoning, planning and final judgement; a cheaper or local model is enough for mechanical, reviewable work. [Delegation](https://chynj.ca/kaptain/docs/#delegation) does that split for you.

### Ollama

Kaptain finds Ollama on your PATH and starts it when it is installed but not running. Ollama installs a system service, so Kaptain never installs it on its own. On Linux, **Install Ollama for me**, in the setup wizard's Ollama box or under **Settings › Runtimes › Ollama Runtime**, installs it when you ask: Kaptain asks for the password you log in to this computer with, downloads Ollama's official installer, shows the start of its SHA-256 checksum and runs it with administrator rights. The password is used once and never stored. On macOS and Windows, or to do it yourself:

**Linux**
```sh
$ curl -fsSL https://ollama.com/install.sh | sh
```
**macOS**
```sh
$ brew install ollama
$ ollama serve
```
**Windows**
```powershell
PS> winget install Ollama.Ollama
```

Then pull models from Kaptain: open the model picker, choose **＋ Add a model…**, go to the **Ollama** tab, type any name from the Ollama library (for example `qwen3.5:4b`) and press **Pull Model**. Progress shows live. The setup wizard offers a starter set when Ollama is running, and the same models as GGUF files for llama.cpp:

| Model | Ollama download | GGUF download |
|---|---|---|
| Qwen3.5 0.8B (`qwen3.5:0.8b`) | 1.3 GB | 0.7 GB |
| Qwen3.5 2B (`qwen3.5:2b`) | 2.7 GB | 2.0 GB |
| Qwen3.5 4B (`qwen3.5:4b`) | 3.3 GB | 3.4 GB |
| Qwen3.5 9B (`qwen3.5:9b`) | 6.6 GB | 6.6 GB |
| Qwen3.5 27B (`qwen3.5:27b`) | 17.5 GB | 17.7 GB |
| Qwen3.5 35B-A3B (`qwen3.5:35b`) | 22.1 GB | 22.9 GB |
| Qwen3.5 122B-A10B (`qwen3.5:122b`) | 81.4 GB | 77.4 GB |

Each one is marked for this machine: **Fits this machine**, or **Needs more memory** with the memory it would need at the context window it would run at (8K for Ollama) and what this machine has. The largest one that fits is marked recommended. Models you already have are shown as **Installed** and cannot be ticked. All of them can use tools, think and see images.

Kaptain talks to Ollama at `http://127.0.0.1:11434`. To use another address, set `ollama_url` in [kaptain.json](https://chynj.ca/kaptain/docs/#files) or the `KAPTAIN_MODEL_URL` environment variable. Ollama models default to a context window of at most 8,192 tokens; raise it per model with the [⚙ model settings](https://chynj.ca/kaptain/docs/#model-settings). Settings › Runtimes › **Ollama Runtime** shows the installation, version and GPU in use, with start and stop buttons.

### GGUF files and llama.cpp

Kaptain runs a GGUF file with `llama-server` from llama.cpp, one server per loaded model, on `127.0.0.1` starting at port 8090. The setup wizard's **Install llama.cpp for me**, or **Install llama.cpp now** under **Settings › Model Handling › KodeGraph Embedder** while no llama.cpp is installed, downloads the official llama.cpp release `b10106` into the data folder (`runtimes/llama.cpp/`), checks that `llama-server` runs, and saves it as the **Executable path** below. No compiler is needed. It tries the builds your GPU can use first (Vulkan or ROCm on Linux; CUDA, Vulkan or ROCm on Windows; Metal on Apple silicon) and the CPU build last, and keeps the first one that runs. llama.cpp publishes no CUDA build for Linux, so an NVIDIA GPU on Linux gets the Vulkan build; **Build llama.cpp for this GPU** in **Settings › Runtimes › llama.cpp Runtime** builds it from source for CUDA. When the machine has a GPU but only the CPU build runs, the install says `DEGRADED: this build runs on the CPU only` and names the GPU it is not using. If `llama-server` cannot start because the system lacks a library, such as `libgomp1` on a minimal Ubuntu, Kaptain names it, offers **Install libgomp1 for me** (Linux, with your computer password), and shows the command for your package manager. On a platform without a release build, the wizard builds llama.cpp from source, which needs `git`, `cmake` and a C++ compiler. A `llama-server` you installed any other way works too, if it is on your PATH or its path is set in Settings.

Kaptain looks for `llama-server` in this order: the `KAPTAIN_LLAMA_SERVER_BIN` environment variable, the path saved in **Settings › Runtimes › llama.cpp Runtime › Executable path**, your PATH, `~/llama/llama.cpp/build/bin/llama-server`, `/usr/local/bin/llama-server`, then Kaptain's own install under `runtimes/llama.cpp/` in the data folder. **Use auto-detect** clears a saved path.

**Add a GGUF model:** open **＋ Add a model…**, go to **Local GGUF** and paste a direct download link. For Hugging Face that is the `…/resolve/main/<file>.gguf` form, not the model's page. Kaptain downloads to a `.part` file, checks that the file really is a GGUF, and only then gives it its name, so a broken link never leaves a corrupt model behind. Downloads go to `~/.local/share/kaptain/models` on every operating system, even when `KAPTAIN_DATA_DIR` points elsewhere, or to `KAPTAIN_MODELS_DIR` if you set it.

GGUF files you already have are found automatically in these folders: `KAPTAIN_MODELS_DIR`, `OLLAMA_MODELS`, `LLAMA_MODELS_DIR`, `~/models`, `~/llama`, `~/gguf`, `~/.local/share/kaptain/models`, `~/.cache/huggingface/hub` and `/opt/models`. **Scan system for GGUF files** in the same dialog re-runs that search.

A GGUF model's context window defaults to half of what the model was trained for, cut to fit your free memory. Saving a new window in the ⚙ restarts that model's `llama-server` on the next message.

**Vision GGUFs** need their projector file, the publisher's `mmproj-*.gguf`, in the same folder as the model. A Hugging Face link for a vision model downloads both in one step. A GGUF without a projector is not offered as a vision model.

### Claude Code and Codex

If the `claude` or `codex` command-line assistant is installed, Kaptain lists it in the picker as `claude-cli` or `codex-cli` and drives it as a model: your subscription and sign-in, with Kaptain's tools, scheduling, approvals and traces. There is no switch to turn them on; being on your PATH is enough. Install and sign in with the CLI itself. When a CLI is not found, its box in the setup wizard shows these commands for your system, each with a **Copy** button:

**Linux**
```sh
$ curl -fsSL https://claude.ai/install.sh | bash
$ claude
$ curl -fsSL https://chatgpt.com/codex/install.sh | sh
$ codex
```
**macOS**
```sh
$ curl -fsSL https://claude.ai/install.sh | bash
$ claude
$ curl -fsSL https://chatgpt.com/codex/install.sh | sh
$ codex
```
**Windows**
```powershell
PS> irm https://claude.ai/install.ps1 | iex
PS> claude
PS> npm install -g @openai/codex
PS> codex
```

Running `claude` or `codex` once signs you in. With Node 18 or newer, `npm install -g @anthropic-ai/claude-code` and `npm install -g @openai/codex` work too. A CLI that is installed but not signed in shows **Found, not signed in** in the setup wizard.

These are each CLI's own installer. On Linux and macOS both put the command in `~/.local/bin`.

In the ⚙ model settings for a CLI model:

- **Model** chooses the model the CLI runs. **CLI default** uses the CLI's own setting. Claude offers Fable, Opus, Sonnet and Haiku (always the latest of each); Codex lists the models from its own catalogue.
- **Reasoning effort** offers the levels the installed CLI supports. For Claude that is low, medium, high, xhigh and max; Codex levels depend on the model.
- **Tool approval** maps onto the CLI's own permission modes:

| Kaptain | Claude Code | Codex |
|---|---|---|
| Ask | default mode, with Kaptain asking you | untrusted approvals, workspace-write sandbox |
| Auto-approve in workspace | accept edits | on-request approvals, workspace-write sandbox |
| Read-only | plan mode | never ask, read-only sandbox |
| Full access | bypass permissions | never ask, full access |

Kaptain's tools reach the CLI as an MCP server named `kaptain-engine`, attached to every turn. Each CLI also keeps the MCP servers you added to it yourself, and Claude keeps your own Claude settings and skills. Kaptain's own older entries there are switched off for the session, so the CLI never sees Kaptain twice. A server you added to one CLI works only in that CLI: connect it to Kaptain instead ([MCP](https://chynj.ca/kaptain/docs/#mcp)) and every model can. A CLI waits up to 900 seconds for a Kaptain tool such as a long delegation or image description; set `KAPTAIN_CLI_TOOL_TIMEOUT_S` to change that.

The Gemini CLI is not offered as a model, and Anthropic's API is not a cloud provider; Claude is reached through Claude Code.

### Cloud models

Open **＋ Add a model…**, go to **Cloud API**, choose a provider and fill in the fields:

| Provider | Base URL Kaptain fills in |
|---|---|
| OpenAI | `https://api.openai.com` |
| Google Gemini | `https://generativelanguage.googleapis.com/v1beta/openai` |
| DeepSeek | `https://api.deepseek.com` |
| Groq | `https://api.groq.com/openai` |
| Mistral | `https://api.mistral.ai` |
| Together AI | `https://api.together.xyz` |
| OpenRouter | `https://openrouter.ai/api` |
| Custom (OpenAI-compatible) | any endpoint that speaks the OpenAI chat-completions format |

- **Model ID** is the exact id your account has; Kaptain does not guess a catalogue. The model appears in the picker as `cloud:<id>`.
- **API key** is stored in `models.db` in your data folder and never sent back to the browser.
- **Model size**, the capability boxes (reasoning, vision, prompt cache, parallel tool calls, JSON mode, structured output, assistant prefill), **Context window** (128,000 by default) and **Max output** (4,096 by default) tell Kaptain how to use the model. Declare a smaller window and Kaptain sends less history.

Kaptain adds `/v1/chat/completions` to the base URL unless it already ends in a version such as `/v1`. To replace keys later, use **Settings › Runtimes › Providers & keys › Update keys**: a blank field keeps the saved key.

### Per-model settings

The ⚙ next to the model picker opens **Model settings** for the selected model. Settings are saved per model and used from the next message. **Revert to default** clears every override for that model.

| Setting | What it does | Values |
|---|---|---|
| **Thinking** | Lets the model reason before answering, and shows it. Saves as soon as you click it. | on or off |
| **Stream tokens live** | Shows the reply as it is written, or only when it is done. | on or off |
| **Context window (num_ctx)** | The whole window: instructions, tools, history and room for the reply. The hint shows the default and the model's maximum. | a number; empty uses the default |
| **Max output (tokens)** | Caps the reply and keeps room for it in the window. | a number; 0 uses the model's own cap |
| **Tool approval** | What tools may do without asking. See [Tools and approvals](https://chynj.ca/kaptain/docs/#approvals). | Ask (default), Ask before risky actions (the same as Ask), Read-only, Auto-approve in workspace, Full access |
| **Tool calls** | How the model is asked to call tools. Auto tries native tool calls and switches to a taught text format if the model writes calls as text. | Auto, Native, Text protocol |
| **Reasoning per step** | How much a local or cloud model may think before each step. Shown only for models that declare reasoning. | **Auto — sized from the room left in the window**, **No limit from Kaptain**, or **Fixed number of tokens** |
| **Reasoning effort** | Shown only when the model declares effort levels: CLI models, and cloud models added with reasoning ticked. | the model's levels |
| **Model** | CLI models only: the model the CLI runs. | CLI default, or a model |

A model on a paired machine shows **Tool approval**, **Tool calls** and **Stream tokens live** here, and nothing else: its thinking, context window and output cap are set on the machine that owns it, and Kaptain follows them. Its tool calls run on this machine, so the approval you choose here applies to them (a kapsule's **Permissions** still win in that kapsule). A lent Claude or Codex CLI is the exception: it runs its own tools on the other machine, under that machine's rules, and this panel says so ([Pairing machines](https://chynj.ca/kaptain/docs/#pairing)).

### Images and vision

When a turn includes an image and the chat model cannot see it, the `vision_analyze` tool hands the picture to a vision model and returns a description. Choose that model under **Settings › Model Handling › Vision tool**:

- **Automatic** uses your chat model if it can see images, otherwise the first Ollama model that declares vision.
- **A local model** that declares vision, or a **GGUF with its projector**.
- **A cloud model**. Cloud models are tried even when vision was not declared.
- **A Claude or Codex CLI**, which looks at the picture with its own tools.
- **A model on a paired machine**, which describes the picture there and sends back the words.

**Thinking** is Auto (no thinking first, then one retry with thinking if the answer comes back empty), Off or On, with answer budgets of 1,000 tokens without thinking and 2,500 with it. Images larger than 2,000 pixels on a side or over 5 MB are scaled down first; one that still does not fit in 5 MB is refused. A description may take up to 600 seconds; set `KAPTAIN_VISION_TIMEOUT_S` for a slower machine.

### See your models from the terminal

```sh
$ kaptain models
claude-cli
codex-cli
gguf:Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf
gguf:gemma-4-12B.gguf
qwen3:4b
qwen3.5:9b
mistral:latest
```

The list is installed CLIs first, then cloud models, then GGUF files, then Ollama models. It also lists embedding models, which are not chat models. `kaptain doctor` checks everything a model route needs in one go:

```sh
$ kaptain doctor
Kaptain environment check
  GPU:      vulkan (AMD Unknown (RADV RENOIR))
  llama:    /home/you/llama/llama.cpp/build/bin/llama-server
  uses:     Vulkan (Vulkan0: AMD Unknown (RADV RENOIR) (34192 MiB, 33720 MiB free)) → -ngl 999
  ollama:   reachable — 9 models (nomic-embed-text:latest, llama3.2:1b, qwen3.5:4b …)
  claude:  available (CLI harness, spawn: direct)
  codex:   available (CLI harness, spawn: direct)
  gemini:  not on PATH
  gguf:     5 local model(s) via llama-server
  shell:    /usr/bin/sh (posix, via default)
  probe:    cli_exec echo OK in 0ms

chat is ready for whatever is reachable above.
```

`kaptain doctor --json` prints the same as JSON. Doctor only reads: it installs and changes nothing. The `uses:` line says what llama.cpp runs on; `-ngl 999` means every layer runs on the GPU. On a machine with no GPU the first line is `GPU: cpu (CPU)` and `uses:` ends in `-ngl 0`. Set `KAPTAIN_GPU_LAYERS` to override it.

## Kapsules

A **kapsule** is an agent you define as a folder: a model wrapped with a persona, a tool allowlist, a permission mode, skills, memory and an optional schedule. It has its own chat threads, its own jobs and its own workspace, and it ships as one reviewable `kapsule.json` file you can diff, copy and keep in git.

A kapsule is a harness, not just a prompt. The model decides how to think; the kapsule fixes what it may touch, how much it may do unattended, and what it remembers. When **Can bring in workers** is on, a kapsule may split a job across workers it creates for that job: each worker gets only the tools its part needs and never more than the kapsule itself, and a worker that provably completes its part is kept and reused.

### Two kinds of agents

| | Kapsule agent | Worker |
|---|---|---|
| Defined by | you, in `kapsule.json` | a kapsule, while a job runs |
| Lifetime | persistent | born for one role in one job; kept only if it completed with evidence |
| Named | by you | by its role; earns a place in the kapsule's **Workers** list by succeeding |
| Reached from | chat, a schedule, the terminal, other agents | its own job |
| Powers | bounded by the kapsule's permissions and allowlist | never wider than the kapsule that made it |

### Create a kapsule

Open **Kapsules**, press **+ New kapsule** and fill in:

| Field | What it means |
|---|---|
| **Name** | Letters, numbers, `-` and `_`. It names the folder and the tool other agents call (`agent_<name>`). |
| **Purpose** and **Generate persona** | One line about the job; the button drafts a persona from it. |
| **Persona** | The kapsule's instructions. Required; edit the draft freely. |
| **Model** | Any model in the picker. Leave it on engine default to use Kaptain's default model. |
| **Tools** | An allowlist. Nothing ticked means the whole catalogue, every call still approval-gated. |
| **Schedule** and **Time** | On demand, every day at a time, or an interval. The time is your local time. |
| **Standing task** | What each scheduled run does. A schedule without a task is refused. |
| **Can bring in workers** | Lets the kapsule split a job across workers ([above](https://chynj.ca/kaptain/docs/#kapsules)). |
| **External paths** | Optional. Folders outside its workspace it may change: **Add path** adds one, and **Add the project folder** adds your project folder in one tap ([What a kapsule may write](https://chynj.ca/kaptain/docs/#kapsule-writes)). |

You can also ask Kaptain chat to create or change a kapsule for you; it uses the `agent-creation` skill ([Edit access](https://chynj.ca/kaptain/docs/#kapsule-edit-access)). **Create kapsule** saves it and it is live at once. Permissions, skills, run memory, trusted scopes and delegation are set afterwards under the kapsule's **Settings**, where you can also change its folders. An on-demand kapsule has no standing task until you add one under **Settings › Instructions**, and **Run now** needs one.

### Schedule a kapsule, step by step

A kapsule that writes a short digest every morning, from nothing:

1. Open **Kapsules** and press **+ New kapsule**.
2. Give it a **Name**, such as `news-digest`. Write one line under **Purpose** and press **Generate persona**, or write the **Persona** yourself.
3. Choose a **Model**. A small local model is enough for a digest; leave it on engine default to use Kaptain's default model.
4. Under **Schedule**, choose **Every day at a set time** and a **Time** in your local time, or an interval such as **Every 6 hours**.
5. Write the **Standing task**, what every run does: "Write today's digest to digest.md in your workspace." A schedule without a task is refused.
6. Press **Create kapsule**. It is live at once.
7. Open its **Settings › Model & permissions › Permissions** and decide what an unattended run may do. On **Ask** a scheduled run stops at its first risky step, because nobody is there to answer; **Auto-approve in workspace** lets it change its workspace, and any folder you added under **Edit access**, without asking ([What a kapsule may write](https://chynj.ca/kaptain/docs/#kapsule-writes)).
8. Press **Run now** to watch one run, then read it under **Jobs** and in [BlackBox](https://chynj.ca/kaptain/docs/#blackbox) before you trust the schedule.

The file it writes is in its workspace, `.kaptain/kapsules/news-digest/` in your project folder. To change a kapsule later, use its **Settings**, or ask Kaptain chat in plain words ([Edit access](https://chynj.ca/kaptain/docs/#kapsule-edit-access)).

### Design a good kapsule

- **One job each.** Specific enough to judge: "summarize last night's logs", "draft release notes from the changelog". If two jobs need different tools or different review rules, make two kapsules.
- **Pick the model for the job.** A small local model is fine for watching and summarizing; give judgement-heavy work your strongest route.
- **Bound the workspace.** The agent reads your project but, by default, writes only in its own workspace, `.kaptain/kapsules/<name>/` inside the project folder, under its permission mode. Any other folder, the project folder too, has to be added under **Settings › Edit access › Folders this kapsule may change**. It can never change its own definition, `kapsule.json` and its files in the data folder, even inside a folder you granted ([What a kapsule may write](https://chynj.ca/kaptain/docs/#kapsule-writes)).
- **Decide what unattended means.** The permission mode is the real decision for a scheduled kapsule (below).
- **Read its first runs.** Check the first scheduled results in **Jobs** and in [BlackBox](https://chynj.ca/kaptain/docs/#observability) before trusting a schedule.

### Kapsule settings

Under the kapsule's **Settings**:

| Fold | Setting | What it does |
|---|---|---|
| Model & permissions | **Model**, **Enabled** | The model, and whether it runs at all |
| | **Permissions** | Inherit from model, Ask before risky actions, Read-only, Auto-approve in workspace or Full access. Travels with the kapsule file. |
| | **Remember previous runs**, **Reset run memory** | Run memory, off by default ([below](https://chynj.ca/kaptain/docs/#schedules)) |
| Schedule | **Runs** | On demand, daily at a time, every N hours, or every N minutes |
| Swarm | **Can bring in workers**, **Delegation** | Workers, and whether this kapsule may call other kapsules |
| Edit access | **Folders this kapsule may change**, **Can edit kapsules** | Its workspace, then every folder you listed for it (external paths and trusted scopes, one list), and the other kapsules it may change ([below](https://chynj.ca/kaptain/docs/#kapsule-edit-access)) |
| Trusted scopes | one entry per line | Folders it may change (`rw`) or read without asking (`ro`), MCP servers it may use without asking, and the web hosts it is limited to ([below](https://chynj.ca/kaptain/docs/#allowed-paths)) |
| Tools | the allowlist | Ticking an `agent_<name>` tool lets it call that kapsule |
| Skills | skill names | Skills woven into its instructions on every turn |
| Instructions | **Persona**, **Task** | What it is, and what each run does |
| Danger | **Delete kapsule** | Moves it to `agents_deleted/` in the data folder, where it can be recovered; the 20 most recent deletions are kept |

**Permissions for unattended runs.** A scheduled run has nobody to answer a prompt; [What a kapsule may write](https://chynj.ca/kaptain/docs/#kapsule-writes) says where it can change files at all. On **Ask**, it stops at its first risky step and reports what it could not do. **Auto-approve in workspace** and **Full access** run without prompts. For a Claude or Codex kapsule, **Full access** is the only mode that runs to completion unwatched. On a local or cloud model, the kapsule's mode replaces the model's; on a CLI model whose own approval you set, the stricter of the two applies, so a kapsule can never widen what you allowed the CLI.

### Trusted scopes

Trusted scopes name **targets**, never whole tools. Write one per line under the kapsule's **Settings › Trusted scopes**:

```text
path:/home/you/reports rw
path:/home/you/reference ro
mcp:mcp-github
host:news.ycombinator.com
```

- `path:<folder> rw` gives the kapsule that folder to change, for every tool. It is the same grant as an external path and shows in the same list, **Settings › Edit access › Folders this kapsule may change**. How it writes there follows its approval mode: **Full access** or **Auto-approve** does it, **Ask** asks you first, **Read-only** refuses. Any folder you choose is allowed, your home folder too; `/` and folders inside Kaptain's data folder are refused when you save.
- `path:<folder> ro` (the default when you leave the access off) lets it read that folder without asking.
- `mcp:<server id>` lets the kapsule use that MCP server's tools without a prompt. Write the server's id: `mcp-` followed by the name you gave it, such as `mcp:mcp-github`, or `kapsule-<name>` for a kapsule's own server.
- `host:<domain>` **restricts** web tools: once any `host:` entry exists, the kapsule may fetch only those hosts and their subdomains.

**This kapsule can never change its own definition (kapsule.json and its files), even inside a folder you granted — edit it from Settings or Kaptain chat.**

### Letting a kapsule edit files outside its workspace, or other kapsules

**Only the kapsule's workspace is allowed by default. Any other folder needs to be added**, the project folder too. A kapsule changes files only in its **workspace** and in the folders you list for it; each listed folder includes everything under it. You list them under the kapsule's **Settings › Edit access**, in one list:

| Setting | What it does |
|---|---|
| **Folders this kapsule may change** | Its workspace first, always, with no Remove. Then every folder you listed, each row saying where it came from: **External path** or **Trusted scope** (a `path:<folder> rw` [trusted scope](https://chynj.ca/kaptain/docs/#allowed-paths)). Both are the same grant. **Remove** takes a folder off, from wherever it was stored. **Add folder** adds a box for one absolute folder, kept as an external path. **Add the project folder (`<path>`)** adds your current project folder in one tap. Press **Save edit access** to keep the changes. |
| **Can edit kapsules** | The other kapsules this one may change: their definition (task, tools, model, schedule, folders) and the files in their workspaces. Empty by default. |

- **How it writes there follows your approval mode.** In its workspace and in every folder you listed: **Full access** or **Auto-approve**, it does it; **Ask**, it asks you first; **Read-only**, it refuses. No folder skips the approval mode.
- **Any folder you choose is allowed, your home folder too.** If you give a kapsule your whole projects folder, it works there the way its approval mode allows.
- **This kapsule can never change its own definition (kapsule.json and its files), even inside a folder you granted — edit it from Settings or Kaptain chat.** A write there is refused (`definition_read_only`) on every path, file tools, patches, delegated files and shell commands alike, and written to the [Brain Log](https://chynj.ca/kaptain/docs/#brain-logs). Changing its task, tools, model, schedule or folders through `kapsule_edit` is refused too (`self_edit_refused`).
- **Kaptain chat**, your own session, may create and change any kapsule. Ask it in plain words; it uses the `agent-creation` skill and the `kapsule_create` and `kapsule_edit` tools. Every change goes through your permission mode first: on **Ask** you approve it before anything is written.
- **Another kapsule's workspace stays closed** to a kapsule, even inside the project folder or a folder you granted, unless that kapsule is ticked under **Can edit kapsules**.
- A kapsule that may edit others can hand them only what it holds itself: a tool it has, a folder it may change, a kapsule it may edit. A kapsule it creates runs under its own permission mode. Delegate and card workers never change a kapsule's definition.
- **Kapsules you made before this rule get nothing added.** If one used to write in the project folder, its next write there is refused with `path_not_allowed`, naming the file and **Settings › Edit access › Folders this kapsule may change**, and the refusal is written to the [Brain Log](https://chynj.ca/kaptain/docs/#brain-logs). Add the project folder there if it should keep doing that work. Kaptain chat, your own session, writes in the project as before.
- **A trusted scope no longer skips the prompt.** Before, a `rw` trusted scope let a kapsule on **Ask** write there without asking. Now it asks like every other folder; set the kapsule to **Auto-approve** or **Full access** if it should write there unattended.

A folder is refused when you save, with the reason, when it is not absolute, does not exist, is `/` (the whole computer), is inside Kaptain's data folder, or is inside another kapsule's workspace that is not ticked under **Can edit kapsules**. A folder that holds Kaptain's data folder or other kapsules' workspaces (your home folder, the project folder) is allowed: the data folder and those workspaces stay closed inside it. If a listed folder is deleted later, the kapsule's next run says so and leaves it out.

### Schedules and run memory

| Write | Means |
|---|---|
| (empty) | On demand only: chat, **Run now**, the terminal, or another agent |
| `daily@08:30` | Every day at 08:30 in the kapsule's time zone |
| `every 6h@08:00` | Every 6 hours on fixed slots counted from 08:00: 02:00, 08:00, 14:00, 20:00 |
| `30m`, `1h`, `90m` | Every interval after the last run, with no clock anchor |

- The time zone is an IANA name such as `America/Toronto` in `schedule_tz`; the create form fills in your browser's. Empty means this machine's zone. Interval schedules ignore it.
- The shortest interval is 1 minute. A schedule needs a standing task.
- **Each occurrence runs at most once.** If Kaptain was not running when a run was due, that run is skipped, not caught up, so a laptop that sleeps never fires a burst of make-up runs.
- The same kapsule never runs twice at once. At most two different local models run scheduled jobs at once by default; change that under **Scheduled Agents & Local Models** in Settings.

**Run memory is off by default.** Each scheduled run starts fresh from its task, the way you would brief a person. Replaying past runs compounds: one bad run steers the next, old evidence reads as current, and the window fills with yesterday. Turn **Remember previous runs** on only when a job builds on its own last answer, such as a tracker that must know what it already reported. **Reset run memory** clears a run history that went wrong. Separately, a kapsule can keep short **lessons** with the `remember` tool: one-sentence rules kept only when a run finishes cleanly, written to `kapsules/<name>/<name>_workspace/guidelines.md` in the data folder, where you can read and edit them and the kapsule can only read them. Resetting run memory does not clear lessons.

### Agents calling agents

By default an agent cannot call another. A kapsule may call another when:

- its **Tools** include `agent_<name>` for that kapsule, or
- its **Delegation** is **On (auto)** or **On (aggressive)**. With no names listed in `allow_agents`, that means any kapsule.

**Off** refuses every call, whatever else is set. Calls nest at most three deep, and a loop is refused. Claude and Codex models reach agents through the `agent_list` and `invoke_agent` tools instead. Whatever one agent passes to another is material to work on, never an instruction with the caller's authority.

### kapsule.json

Each kapsule's definition lives in `kapsules/<name>/` in the data folder, and its workspace in the project folder:

```text
<data folder>/kapsules/<name>/kapsule.json                     the definition
<data folder>/kapsules/<name>/<name>.md                        optional persona file, used when "system" is empty
<data folder>/kapsules/<name>/<name>_workspace/guidelines.md   its lessons, kept by Kaptain
<project>/.kaptain/kapsules/<name>/                            its workspace: the files it makes and keeps
```

The definition folder is read-only to the kapsule. The workspace is made on the kapsule's first run, with a `README.md` saying what it is; files an older Kaptain kept in `<name>_workspace/` are copied into it once, and nothing is deleted. To put the workspace elsewhere, set `workspace` in the kapsule's `agent` block, or `kapsule_workspace_dir` in `kaptain.json` for every kapsule (it must contain `{name}`; `{project}` and `{name}` are filled in, and a leading `~/` is your home folder). A workspace inside the data folder is refused.

The smallest valid kapsule:

```json
{ "name": "notes", "agent": { "system": "You keep tidy meeting notes." } }
```

A fuller one:

```json
{
  "name": "news-digest",
  "agent": {
    "name": "news-digest",
    "system": "You write a short morning digest of AI news.",
    "model": "qwen3:8b",
    "tools": ["web_search", "web_fetch", "file_write", "time_now"],
    "skills": ["house-style"],
    "max_rounds": 8,
    "task": "Write today's digest to digest.md in your workspace",
    "schedule": "daily@08:30",
    "schedule_tz": "America/Toronto",
    "approval_mode": "auto",
    "memory": false,
    "trusted_scopes": ["host:news.ycombinator.com"],
    "delegation": { "mode": "off" }
  }
}
```

| Field | Meaning | Default |
|---|---|---|
| `name` | The kapsule's name | the folder name |
| `enabled` (top level) | `false` hides the whole kapsule | true |
| `agent` / `agents` | One agent, or a list of agents in one folder | |
| `agent.system` | The persona | `<name>.md` |
| `agent.model` | A model id as the picker shows it: an Ollama name such as `qwen3:8b`, `gguf:<file>.gguf`, `cloud:<id>`, `claude-cli`, `codex-cli`, or `node:<machine>/<model>` | Kaptain's default model |
| `agent.tools` | The allowlist; empty means the whole catalogue | empty |
| `agent.skills` | Skill names injected every turn | none |
| `agent.task`, `agent.schedule`, `agent.schedule_tz` | The standing task and when it runs | on demand |
| `agent.approval_mode` | `ask`, `sandbox` (Read-only), `auto`, `full`, or empty to inherit the model's | inherit |
| `agent.memory` | Run memory | off |
| `agent.max_rounds` | Tool rounds per run | 50 |
| `agent.trusted_scopes` | [Trusted scopes](https://chynj.ca/kaptain/docs/#allowed-paths); its `rw` folders are folders it may change | none |
| `agent.external_paths` | Absolute folders outside its workspace it may change; one list with its `rw` trusted scopes ([Edit access](https://chynj.ca/kaptain/docs/#kapsule-edit-access)) | none |
| `agent.can_edit_kapsules` | Other kapsules it may change ([Edit access](https://chynj.ca/kaptain/docs/#kapsule-edit-access)) | none |
| `agent.swarm` | Can bring in workers | false |
| `agent.delegation` | `{ "mode": "auto", "allow_agents": [...] }`; the mode is `"off"`, `"auto"` or `"aggressive"` | see [above](https://chynj.ca/kaptain/docs/#agents-talking) |
| `agent.use_kapsule_tools` | Also grant every tool of this kapsule's own MCP server | false |
| `skills` (top level) | `{ "paths": ["./skills"] }`: skill folders shipped with the kapsule | none |
| `mcp` (top level) | `{ "command": ["./server"], "env": {}, "dir": "" }`: the kapsule's own MCP server | none |

Kapsules created or changed in the Kapsules view apply at once. A `kapsule.json` you add or edit by hand is read the next time Kaptain starts, and a kapsule's own `mcp` server and `skills` folders are loaded at start. The Kapsules view edits single-agent kapsules; a kapsule with an `agents` list is edited in its file.

### From the terminal

```sh
$ kaptain agent list
news-digest          model=qwen3:8b             enabled  schedule=daily@08:30
notes                model=                     enabled  schedule=on-demand
```

| Command | What it does |
|---|---|
| `kaptain agent list` | Every kapsule agent with its model, state and schedule |
| `kaptain agent run <name> "<task>"` | One turn with that agent's persona and memory, without tools. Use the web interface for runs that need tools. |
| `kaptain agent chat <name> "<message>"` | One turn of the agent's direct chat, which remembers the conversation |
| `kaptain agent history <name>` | Prints that direct chat |
| `kaptain agent enable <name>`, `kaptain agent disable <name>` | Pauses or resumes an agent without editing its file |
| `kaptain agent set-model <name> <model>` | Changes its model from the next run |

## Skills

A **skill** is a Markdown document a model loads when it is relevant: a checklist, a runbook, your house style. Models see each skill's name and one-line description, and load the full text only when they need it.

```markdown
---
name: deploy-runbook
description: Exact steps and checks for deploying the storefront.
---
# Deploy runbook
1. Run the test suite …
```

A skill is a folder with a `SKILL.md` (scripts and files beside it are kept) or a single `<name>.md`. Without a `name`, the folder or file name is used; without a `description`, the first line of text.

### Where skills come from

When two skills share a name, the first source in this list wins:

1. **The project:** `.kaptain/skills`, `.claude/skills` and `.agents/skills` in the project folder. These follow the project as it changes.
2. **This machine:** `skills/` in the data folder, where the Krew view and `kaptain skill add` put them.
3. **Kapsules:** the skill folders a kapsule ships with.
4. **Your CLIs:** `~/.claude/skills`, `~/.codex/skills` (and the skills of Codex plugins you enabled) and `~/.gemini/skills` are offered only when that CLI is the model answering, so they do not appear in **Krew › Skills** or in `skill_list`; `~/.agents/skills` is shared with every model.
5. **Imported folders** listed in `KAPTAIN_SKILL_IMPORT_ROOTS`.
6. **Kaptain's own:** skills built into Kaptain, such as `agent-creation`.

### Add a skill

- **Krew › Skills › + Add skill** writes a new one: name, description and instructions.
- **Import…** installs from a folder, a `.zip`, a git URL or a GitHub `owner/repo`. **Upload .zip** takes a file. Every `SKILL.md` found is installed.
- **Drop a folder** with a `SKILL.md` into any of the locations above. There is no registration step.

```sh
$ kaptain skill add ./release-notes-skill
installed  release-notes                1 file(s) → /home/you/.local/share/kaptain/skills/release-notes/SKILL.md
$ kaptain skill list
release-notes                    global       Draft release notes from a git log range.
```

`kaptain skill add` takes a folder, a `.zip`, a git URL or `owner/repo`, and refuses to overwrite a skill of the same name unless you add `--replace`. `kaptain skill list --harness claude` adds that CLI's own skills.

### How models use skills

- **On their own.** Models call `skill_list` to see what exists and `skill_load` to read one. Sharp names and descriptions get used without being asked.
- **For one turn.** Type `/` in the chat and choose a skill. It shows as a chip and applies to that message only.
- **Always.** A kapsule's **Skills** list weaves those skills into its instructions on every turn. Use this for rules that always apply, and `skill_load` for the ones that sometimes do.

## Tools, approvals and safety

What a model may do on your computer is decided by five things, and all five are yours to set:

1. **Whether it has tools at all.** In Chat, **Tools** is off until you turn it on. A kapsule run always has tools, limited to its allowlist.
2. **Its approval mode** ([below](https://chynj.ca/kaptain/docs/#approvals)): Ask, Read-only, Auto-approve in workspace or Full access.
3. **Where it may write.** The project folder, a kapsule's own workspace, and folders you name. Never Kaptain's data folder, and never a kapsule's own definition ([What a kapsule may write](https://chynj.ca/kaptain/docs/#kapsule-writes)).
4. **Sudo**, which is one switch, and every sudo shows you a pop-up ([below](https://chynj.ca/kaptain/docs/#approvals)).
5. **Which MCP servers** are connected; their tools pass the same gate ([MCP](https://chynj.ca/kaptain/docs/#mcp)).

**Krew** is Kaptain's toolbelt: everything a model can do besides talk. A model gets tools when **Tools** is on in the chat, or always in a kapsule run. Every tool has its own switch under **Krew › Native Tools**, and nothing is off by default. A tool a kapsule lists explicitly stays available to that kapsule even when its global switch is off.

| Family | Tools |
|---|---|
| Code search (KodeGraph) | `kodegraph_explore`, `kodegraph_context`, `kodegraph_search`, `kodegraph_node`, `kodegraph_callers`, `kodegraph_callees`, `kodegraph_impact`, `kodegraph_files`, `kodegraph_status`, `kodegraph_index` |
| Files | `file_read`, `file_search`, `file_write`, `file_edit`, `patch_apply` |
| Shell | `cli_exec`, `test_run`, `git_op` |
| Web | `web_search`, `web_fetch`, `web_fetch_raw`, `web_extract` |
| Skills | `skill_list`, `skill_load` |
| Memory | `remember`, `session_recall`, `tool_result_recall` |
| Workflow | `todo`, `time_now`, `ask_user` |
| Delegation | `delegate`, `delegate_batch`, `assemble`, `delegate_status` |
| Vision | `vision_analyze` |
| Agents | `agent_cards` (workers), `kapsule_create`, `kapsule_edit`, and one `agent_<name>` per kapsule |

The [Krew tools reference](https://chynj.ca/kaptain/docs/#tools-reference) has one entry per tool: what it does, when a model uses it, its permission and its parameters.

### How tools reach the model

When **Tools** is on, a local or cloud model is not handed every tool's full description. A few are defined in full: `file_read`, `file_search`, `file_edit`, `file_write`, `cli_exec`, `kodegraph_explore`, `tool_result_recall`, `todo` and `ask_user`, plus every tool a kapsule names. The others are listed one line each under "Other tools available", and the model fetches the descriptions it needs with `tool_schema_resolve` before calling them. A listed tool called straight away runs when its arguments are right; otherwise its description comes back with the error, so the next call can be right. There is no switch: this is how tools work in every chat. Claude and Codex get Kaptain's tools through their own MCP connection instead.

**Earlier results come along.** Tool results have their own share of the window ([When a tool result is too big](https://chynj.ca/kaptain/docs/#big-results)). The chat's last 5 tool calls, with their results, are passed along whole into your next messages, within a quarter of the window, so a follow-up question is answered from what the model already read instead of reading again. When fewer fit, the newest that fit are kept and older ones are read by id with [`tool_result_recall`](https://chynj.ca/kaptain/docs/#tool-tool-result-recall). `tool_result_tail_calls` in [kaptain.json](https://chynj.ca/kaptain/docs/#settings-json) changes the 5, up to 32. Within a turn, the same read repeated is answered with a pointer to the result the model already has, until something may have changed it, such as an edit or a command.

### Approval modes

Every tool call that could change something passes one approval gate. Each model has a mode, and each kapsule can set its own:

1. **For a model:** open the ⚙ next to the model picker and choose **Tool approval**. It applies from the next message, for that model.
2. **For a kapsule:** open the kapsule's **Settings › Model & permissions › Permissions**. **Inherit from model** uses the model's mode. The choice is saved in its `kapsule.json` as `approval_mode`.

| Mode (`kapsule.json` value) | Local and cloud models | Claude Code | Codex |
|---|---|---|---|
| **Ask** (default), also listed as **Ask before risky actions** (`ask`) | Kaptain pops up **Permission required** — "Kaptain is paused until you decide." — with **Review tool input**, **Deny** and **Allow once**, and the turn waits | default mode, asking through Kaptain | untrusted, workspace-write |
| **Read-only** (`sandbox`) | Every change is refused, and the model is told "User denied the operation" | plan mode | read-only sandbox |
| **Auto-approve in workspace** (`auto`) | Changes run without asking | accept edits | on-request, workspace-write |
| **Full access (unrestricted)** (`full`) | Changes run without asking | bypass permissions | full access |

The two Ask entries behave the same. **Allow once** applies to that one action only. Questions a model asks you appear in every mode.

For local and cloud models, Auto-approve and Full access behave the same; they differ for the CLIs, which have their own permission systems. Whatever the mode:

- **Reading inside the project never asks.** Code search, reading files, web lookups, skills and memory run freely.
- **Read-only shell commands never ask.** A command such as `ls`, `cat`, `grep`, `git status` or `git diff`, without redirection or substitution, runs at once in every mode. Everything else asks in Ask mode.
- **Tests always ask in Ask mode**, even for a safe command.
- **Writing outside the project is refused** in every mode, except a kapsule's own workspace and the [folders you listed for it](https://chynj.ca/kaptain/docs/#kapsule-edit-access), external paths and `rw` [trusted scopes](https://chynj.ca/kaptain/docs/#allowed-paths), where its approval mode decides ([What a kapsule may write](https://chynj.ca/kaptain/docs/#kapsule-writes)). Writing in Kaptain's data folder is always refused. Reading outside the project asks.
- **Every `sudo` asks you**, in every mode except Read-only, where nothing privileged runs. Sudo is one switch, **Settings › Model Handling › Sudo requests › Ask me for my password**, on by default, and with it on every sudo opens a pop-up, whoever runs it: a local or cloud model, Claude Code or Codex, or a program a model started. The pop-up names the command (`sudo: <command>`, and which program asked) and has one field, **Administrator (sudo) password — used once, never stored**, with **Cancel** and **Run with password**. The password goes only to sudo on this computer, never to a model, a transcript or a file. It is remembered for the rest of that task, 2 minutes by default (0 to type it every time, at most 30), so later pop-ups in the task need one click; every sudo still shows a pop-up. Turn the switch off and sudo commands are not run, and the model is told why. A program that calls sudo by its full path, such as `/usr/bin/sudo`, is not stopped for the pop-up first; it reaches one only if sudo itself asks for the password. There is no sudo on Windows.
- **Tools from MCP servers ask on every call** in Ask mode, read-only or not, unless a kapsule pre-approves the server. In **Read-only**, every MCP tool call is refused, even one that only reads, unless a kapsule pre-approves the server.

An approval waits 300 seconds once shown. When a run is unattended and nobody can answer, the model is told so, rather than told you refused, and it does what it can without that step.

### Long commands and background jobs

`cli_exec` gives a command 30 seconds unless the model asks for more, up to 300. For a local or cloud model, a command still running at its limit is not stopped: it carries on in the background as a job, and the model gets the output so far and the job's id, so it can wait for it, read new output or stop it. A model starts a server or watcher with `background: true`, which has no time limit. A process a command leaves running, such as a server started with `&`, is kept as a job as well, so nothing runs unseen.

Jobs show in a strip above the message box, such as "1 running in the background", each with how long it has run, its last line of output and **Stop**. A job ends when it finishes, when you or the model stop it, when its chat is deleted or when Kaptain stops; a command that outran its limit is also stopped after `shell_job_max_minutes` in `kaptain.json` (60 minutes; 0 means no limit). Jobs do not survive a restart, and one chat can have 8 running at once. Commands that Claude or Codex run through Kaptain's tools still end at their time limit.

### What a kapsule may write

**Trusted scopes and external paths are how you give a kapsule write access.** A kapsule granted a folder works there the way its approval mode allows: **Full access** or **Auto-approve**, it does it; **Ask**, it asks you first; **Read-only**, it refuses. The one thing it never edits is its own definition. Its file tools decide every write in this order, and the first rule that matches wins:

| The path is | The write is |
|---|---|
| Its own definition: `kapsule.json` and its files in Kaptain's data folder | **refused**, in every mode, even inside a folder you granted: "this kapsule can never change its own definition (kapsule.json and its files), even inside a folder you granted — edit it from Settings or Kaptain chat" |
| Anywhere else in Kaptain's data folder, other kapsules' definitions included | **refused**, in every mode |
| Another kapsule's workspace | **refused**, unless that kapsule is ticked under **Can edit kapsules** |
| A folder you listed for it, an external path or a `rw` trusted scope, the project folder included once you list it | allowed, under its approval mode |
| Its own workspace, `.kaptain/kapsules/<name>/` in the project | allowed, under its approval mode |
| Anywhere else, **the project folder too** | **refused** (`path_not_allowed`) |

**Only the workspace is allowed by default; any other folder needs to be added.** The kapsule still reads your project; it changes project files only after you add the project folder under **Settings › Edit access › Folders this kapsule may change** (**Add the project folder** does it in one tap). Kaptain chat, your own session, is not a kapsule and writes in the project as before.

In **Read-only**, every write is refused, even in its workspace. **A kapsule never edits its own definition**: changing its own task, tools, model, schedule or reach through `kapsule_edit` is refused as `self_edit_refused`, and writing its `kapsule.json` or another file in its definition folder is refused as `definition_read_only`; both are written to the [Brain Log](https://chynj.ca/kaptain/docs/#brain-logs). You change a kapsule from its **Settings**, or ask Kaptain chat. The refusals the model reads say what to do instead, and a refused write is written to the Brain Log too, for example:

```output
refused: path_not_allowed — /home/you/project/notes/todo.md is outside every folder this kapsule may change — add it under Settings › Edit access › Folders this kapsule may change (the project folder /home/you/project is writable for a kapsule only when it is listed there: "Add the project folder" adds it). This kapsule may change files only in its workspace /home/you/project/.kaptain/kapsules/digest; nothing was changed
```

To let a kapsule change any folder besides its workspace, the project folder included, add it under **Settings › Edit access › Folders this kapsule may change** ([Edit access](https://chynj.ca/kaptain/docs/#kapsule-edit-access)), or write `path:<folder> rw` in its [trusted scopes](https://chynj.ca/kaptain/docs/#allowed-paths); both land in the same list and both follow its approval mode.

**Shell commands and delegated files follow the same list.** A kapsule's `cli_exec` and `test_run` run in its workspace unless you give them a folder it may change. A command that runs in, or names, any other folder is refused the same way (`path_not_allowed`, or `not_permitted` for another kapsule's workspace) and written to the Brain Log; a command that only reads, such as `ls` or `cat`, may look anywhere. A `git_op` that changes the repository needs the project folder in the kapsule's folders, and git started from its workspace does not reach the project's repository. This check reads the paths a command names; it is not an operating-system sandbox, so a script can still write where its own code decides. A file that `delegate`, `delegate_batch` or `assemble` writes takes the same decision as `file_write`, for a kapsule and in Kaptain chat alike: never in the data folder, on **Ask** you are asked before the model runs, and in **Read-only** it is refused.

### Add your own tools

A tool is a program that speaks MCP, in any language. There are three supported ways in, and all three land in the same catalogue, behind the same switches and the same gate:

1. **Connect it as an MCP server** in **Krew › MCP Servers** or with `kaptain mcp add` ([MCP](https://chynj.ca/kaptain/docs/#mcp)).
2. **Ship it inside a kapsule** with the kapsule's `mcp` entry, so the tools, the agent and its skills travel as one folder.
3. **Drop an executable into `plugins/`** in the data folder. Kaptain registers it at start and runs it as `<program> mcp`.

There is deliberately no way to paste a shell script as a tool: tools are real programs behind a real protocol, so they can be reviewed, versioned and gated.

## MCP

MCP works in both directions. **In:** any MCP server's tools join Kaptain's catalogue, for every model. **Out:** Kaptain's own toolbelt is an MCP server named `kaptain-engine` that Claude Code, Codex and other MCP clients can use.

### Connect a server

Install the server's own runtime first (for example Node for `npx` servers, or Docker for a server shipped as a container). Then, in **Krew › MCP Servers**:

- **+ Add from JSON** takes the `{"mcpServers": {...}}` block from the server's README, as is: "Paste the server's own config block. Kaptain reads the standard shape, so a README snippet works as-is — local (command/args/env) or remote (url/headers), one server or several." 
- **Add manually** takes a name (lowercase), then either a local command with arguments or a remote URL, and one `KEY=VALUE` per line: environment variables for a local server, headers for a remote one. **How does this server authenticate?** offers OAuth sign-in for servers that need it.

Each row shows the server's status and tool count, with **Enable** or **Disable**, **Reconnect**, **Edit**, **Remove** and **Sign in** where it applies. A server that failed shows an (i) that opens the reason and the last lines it wrote. A value copied from a README example, such as `{path/to/storage.json}`, is pointed out on the row; **Edit** changes the command, arguments or address and keeps your stored keys. A removed server leaves the list at once. Connected tools appear in Native Tools with their own switches. From a terminal:

```sh
$ kaptain mcp add tavily --env 'TAVILY_API_KEY=${TAVILY_API_KEY}' -- npx -y tavily-mcp
added tavily (stdio)
  Kaptain is not running; it will connect on next start
$ kaptain mcp add linear --url https://mcp.linear.app/mcp --oauth
added linear (http)
  Kaptain is not running; it will connect on next start
$ kaptain mcp list
linear               http   enabled  https://mcp.linear.app/mcp · oauth
tavily               stdio  enabled  npx -y tavily-mcp
```

| Command | What it does |
|---|---|
| `kaptain mcp add <name> [flags] -- <command> [args…]` | A local server. Flags: `--env K=V` (repeatable), `--transport` with `stdio`, `http` or `sse`, `--oauth` |
| `kaptain mcp add <name> --url <url> [flags]` | A remote server. Flags: `--header K=V` (repeatable), `--transport` with `http` or `sse`, `--oauth` |
| `kaptain mcp add-json [file]` | Adds every server in a `{"mcpServers": {...}}` block, from a file, or from standard input with `-` or no file |
| `kaptain mcp list [--json]` | Your servers |
| `kaptain mcp enable <name>`, `disable <name>`, `remove <name>` | Turns one on or off, or removes it |

> [!WARNING]
> Keep the single quotes around `${VAR}`. Kaptain stores `${VAR}` and reads the variable from its own environment each time the server connects, so the secret never lands in its config file. Without quotes your shell replaces it first and the real key is saved.

Servers are saved in `mcp_servers.json` in the data folder, in the same shape as the README blocks, so you can also edit it by hand. A Kaptain running in Localhost only mode picks up a change from `kaptain mcp` immediately. In Tailscale mode the command cannot reach Kaptain on this machine's local address, so it says Kaptain is not running even when it is; the change applies at the next start, as it does when Kaptain is stopped. OAuth tokens are kept in their own file, never in `mcp_servers.json`, and the interface shows key names, never values. A local command that is not installed is refused before anything is saved.

Tools from MCP servers pass the same approval gate as built-in tools and ask on every call in Ask mode. Connect only servers you trust.

### Worked example: GitHub

GitHub publishes its MCP server as a container, `ghcr.io/github/github-mcp-server`, which reads a personal access token from `GITHUB_PERSONAL_ACCESS_TOKEN`. Kaptain keeps the token out of its files by reading it from its own environment.

1. **Install Docker** and check that `docker run hello-world` works for your user.
2. **Make a token** on github.com under **Settings › Developer settings › Personal access tokens**, with only the access you want models to have. GitHub's README names `repo`, `read:packages` and `read:org` as the scopes it uses.
3. **Start Kaptain with the token in its environment.** In the terminal you start Kaptain from, read the token without showing it, then restart:
    ```sh
    $ read -rs GH_PAT
    $ export GH_PAT
    $ kaptain stop
    $ kaptain start
    ```
    `kaptain start` passes its environment to Kaptain. Put the two lines in your shell profile, or a file only you can read, if Kaptain should always have it.
4. **Add the server.** In **Krew › MCP Servers**, press **+ Add from JSON** and paste:
    ```json
    {
      "mcpServers": {
        "github": {
          "command": "docker",
          "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
          "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GH_PAT}" }
        }
      }
    }
    ```
    Kaptain saves `${GH_PAT}` as written and fills in the value each time it starts the server.
5. **Check it.** The **github** row shows its status and tool count, and its tools appear under **Krew › Native Tools** with their own switches. In Chat, turn on **Tools** and ask "List the open pull requests in <owner>/<repo>". On **Ask**, each GitHub call shows **Permission required** first.
6. **Let a kapsule use it without prompts**, if you want: add `mcp:mcp-github` to the kapsule's [trusted scopes](https://chynj.ca/kaptain/docs/#allowed-paths).

The same from a terminal, with the block saved as `github.json`:

```sh
$ kaptain mcp add-json github.json
added github (stdio)
  Kaptain is not running; it will connect on next start
$ kaptain mcp list
github               stdio  enabled  docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
```

If the row shows the server failed, its (i) opens the reason and the last lines the server wrote; an unset `GH_PAT` or a token GitHub refuses shows up there.

### Sign in with OAuth

A hosted server that uses OAuth needs no key in Kaptain: you approve Kaptain in the vendor's own page, and Kaptain keeps the token in `mcp_oauth.json` in the data folder, readable only by you.

1. In **Krew › MCP Servers**, press **Add manually**. Give it a name, the server's **Remote URL**, and under **How does this server authenticate?** choose **OAuth — sign in after adding**. From a terminal: `kaptain mcp add <name> --url <url> --oauth`.
2. On the server's row, press **Sign in**. A new tab opens the vendor's page asking you to approve the connection.
3. Approve it. The tab then goes to a local address that does not load; that is expected.
4. Back in Kaptain, **Finish signing in to <name>** asks for the **Redirected URL (or just the code)**. Copy the whole address from that tab's address bar, paste it, and press **Complete sign-in**.
5. The row now says **signed in**, and **Sign out** removes the token.

If the vendor needs an app of your own first, step 2 opens **Sign in to <name>** asking for the **Client ID from the vendor's OAuth app**; enter it and press **Continue**. Kaptain refreshes the token by itself; when it can no longer be refreshed or the server refuses it, the row shows **Sign in** again, and tools from that server answer with a sign-in hint until you do.

### Kaptain as an MCP server

`kaptain mcp` runs Kaptain's toolbelt as an MCP server over stdio, named `kaptain-engine`.

**Inside Kaptain** there is nothing to set up: when Claude Code or Codex is the model, Kaptain attaches `kaptain-engine` to every turn with the chat's project, approval mode and grants. Your connected MCP servers are passed through to them too, as `ext__mcp-<name>__<tool>` (or `ext__kapsule-<name>__<tool>` for a kapsule's own server).

**Outside Kaptain**, in your own terminal or editor, a CLI needs `kaptain-engine` in its own configuration. Use **Register standalone** in the CLI model's ⚙ settings, or:

```sh
$ kaptain mcp register claude
$ kaptain mcp install-status claude
```

| CLI | What `register` writes | Check from the CLI |
|---|---|---|
| Claude Code | `claude mcp add -s user kaptain-engine -- <kaptain> mcp`, or the entry in `~/.claude.json` | `claude mcp get kaptain-engine` |
| Codex | `[mcp_servers.kaptain-engine]` in `~/.codex/config.toml` | `codex mcp list` |
| Gemini CLI | `mcpServers.kaptain-engine` in `~/.gemini/settings.json` | |

Every file change keeps a backup beside the file as `<file>.kaptain.bak`, and a config that does not parse is never overwritten. `kaptain mcp unregister <cli>` removes exactly what Kaptain added. After `kaptain update`, run `register` again if the CLI reports the server missing; it is safe to repeat.

Registered this way, outside Kaptain, `kaptain-engine` offers Kaptain's reading tools: code search, reading and searching files, read-only shell commands, web lookups and skills. Tools that change files or run other commands are refused with "User denied the operation", because there is no Kaptain approval prompt in that setup. It also cannot find a running Kaptain from outside: `agent_list` reads your kapsule folders directly, `invoke_agent` answers that it cannot reach the Kaptain engine, tools from your connected MCP servers do not appear, and `sudo` is refused, because its pop-up needs Kaptain. For the full toolbelt under your approval mode, use the CLI as a model inside Kaptain.

**Check the server:**

```sh
$ kaptain mcp smoke
kaptain MCP smoke passed (/home/you/.local/bin/kaptain)
$ kaptain mcp health
```

```output
{
  "ok": true,
  "server": "kaptain-engine",
  "version": "<version>",
  "tool_count": 42,
  "sample_tool": "kaptain_models",
  "sample_ok": true,
  ...
  "detail": "kaptain-engine MCP healthy — 42 tools, kaptain_models returned a live result"
}
```

`kaptain mcp health` exits non-zero when the server is unhealthy, so it can run in scripts. The 42 tools, with every Krew switch on, are the 38 Krew tools plus four that exist only on this server: `kaptain_models`, `kaptain_chat`, `agent_list` and `invoke_agent`.

## Delegation and token use

<span id="tokens"></span>**Delegation** lets the model in your chat hand bounded, mechanical work, such as summaries, extraction, boilerplate or log digests, to a second model, the **worker**, while it keeps the conversation and the final judgement; the worker can be any model, and a local one's tokens cost nothing. Choose it under **Settings › Model Handling › Delegation › Worker model** and press **Save** (there is none until you do, and the delegate tools answer "no worker model chosen — pick one in Settings ▸ Delegation"), then turn on **Tools** and **Delegate** in the chat: the model decides when a piece of work suits the worker, or you ask outright. A worker without tools has its result checked for quality, so a failed check comes back as a failure, never as substituted text; a worker given tools reports `output_written` true only when the file it was asked to write really changed. Most of what a model is billed for is not your question but everything resent around it, the history, earlier tool results and the instructions, so Kaptain cuts cost by mechanism rather than by picking a cheaper model: [KodeGraph](https://chynj.ca/kaptain/docs/#kodegraph) hands the model the code that matters instead of whole files, [compaction](https://chynj.ca/kaptain/docs/#settings-model-handling) folds old history into a summary, scheduled runs start fresh from their task, tools are described in full only when a model needs one, and [big results](https://chynj.ca/kaptain/docs/#big-results) are read by id instead of resent; see what you spent in **BlackBox › Model usage**, or with [`kaptain usage`](https://chynj.ca/kaptain/docs/#cli-usage) for Claude and Codex.

## Observability

Unattended agents are only trustworthy if you can see afterwards exactly what they did and what it cost.

### BlackBox

**Session turns** lists recent turns, for **This session** or **All sessions**, so a run at 3 a.m. is as inspectable as your live chat. Open a turn to see:

- **Context sent:** the context window and budget, the instructions, the messages and the tools that went to the model. For Claude and Codex it shows what was actually sent to the CLI and why: continuing the thread, handing it over with a summary, or starting fresh.
- **Each tool call,** with its request and response.
- **The reply,** and the error if there was one.

In the chat itself, each turn's context card, `What <model> received`, says in plain words what the model was handed: Kaptain's standing instructions, the earlier messages and any summary, the tools (ready to use, or listed by name), the room for tool results, the model's memory and the tool history carried along. **Developer details** (i) holds the raw numbers. Each turn opens with its [trace record](https://chynj.ca/kaptain/docs/#traces). A kapsule's turns also show inline in its own chat. **Model usage** shows provider-reported tokens with totals for today, the last 7 days and this month, and the plan allowance of your Claude or Codex subscription.

### Traces

Every run leaves one trace record, however it started: your chat, a message to a kapsule, a scheduled or invoked kapsule run, a channel message, a swarm card or a delegate worker. The record looks the same wherever you open it: a turn in **BlackBox › Session turns**, the trace under an answer in a kapsule's chat, and a run in **Kapsules › Traces** or **Jobs**. It shows:

- **Context passed:** every part the model was handed, with its size. The instructions, the operating brief, the environment, **About this run** (the date and time, and the address you opened Kaptain on), a kapsule's lessons, the tool definitions, the summary of older messages, the earlier messages, tool calls carried from earlier turns, and your message. **View** opens a part of the instructions exactly as it was sent.
- **Tool calls:** each call with the size of what it sent and got back, how long it took, and whether it was refused. **Result** opens the result.
- **Model rounds** with tokens in and out and how long the model took to read and write; the quality gates' decisions and the review; the answer's size; the tokens; and how the run ended, with the reason when it did not finish.

Your message reaches the model exactly as you typed it. What Kaptain knows about a run goes in **About this run**, never into your words. A conversation is told the hour, so its cached instructions change at most once an hour; a scheduled run or a worker, with nothing after its instructions but its task, is told the minute. To have the send time stamped at the end of each of your messages instead, set `turn_time_stamp` to `message` in [`kaptain.json`](https://chynj.ca/kaptain/docs/#settings-json).

The record keeps sizes and fingerprints, never text: the text stays in the chat's own history, which **View** and **Result** read. A delegate worker has no history of its own, so its record holds sizes only. A run without a record says why: it ran before 0.0.9, or its record has expired. Deleting a chat deletes its runs' records. Messages about Kaptain's own health stay in [Brain Logs](https://chynj.ca/kaptain/docs/#brain-logs).

### God's Eye and KodeGraph

**KodeGraph** indexes your project into a graph of files, symbols and calls, stored in `.kodegraph/` inside the project. Models query it with the `kodegraph_*` tools instead of reading whole files. It re-indexes changed files every two minutes in the background (a home folder is never re-indexed automatically). Semantic search uses the embedder chosen under **Settings › Model Handling › KodeGraph Embedder**. **Automatic (recommended)**, the default, uses Kaptain's built-in model if it is already running, else an embedding model already installed in Ollama, else the built-in model ([Start Kaptain](https://chynj.ca/kaptain/docs/#start)). You can also pick the built-in model, an Ollama embedding model, a GGUF embedding file on this machine, **None (keyword search only)** or **Custom endpoint…**. With **None**, or while no embedder can be reached, it ranks by keywords.

**God's Eye** (spelled **Gods Eye** in the interface), under **Views**, draws that graph: search symbols, open the file atlas, and inspect a symbol's callers, callees and impact. **Build index** indexes on demand. The same queries work from a terminal:

```sh
$ kaptain kodegraph index
$ kaptain kg status
```

```output
Project: ~/project (kaptain.json project_dir)
{
  "call_edges": 1,
  …
  "files": 1,
  …
  "index_status": "ready",
  …
  "ok": true,
  …
  "root": "/home/you/project",
  "stale": false,
  …
  "store": "sqlite+fts5",
  "symbols": 2,
  "vectors": 0
}
```

| Command | What it does |
|---|---|
| `kaptain kg index [--root DIR] [--confirm]` | Builds or refreshes the index of the current folder (`--confirm` allows a home folder or a very large tree) |
| `kaptain kg status` | Index statistics. The project and where it came from go to the error stream first. The embedder in use is under **Settings › Model Handling › KodeGraph Embedder**. |
| `kaptain kg search "<name>" [--kind K]` | Finds a symbol; `K` is `function`, `method` or `class` |
| `kaptain kg node "<symbol>"` | One symbol with its source |
| `kaptain kg callers "<symbol>"`, `callees "<symbol>"` | Who calls it, and what it calls |
| `kaptain kg impact "<symbol>"` | Everything affected if it changes, three levels deep |
| `kaptain kg context "<task>" [--budget N]` | The code relevant to a task, within a token budget |
| `kaptain kg ensure-embedder` | Pulls `nomic-embed-text` into Ollama when Ollama has no embedding model |

`kaptain kg` is short for `kaptain kodegraph`. Output is JSON.

### Brain Logs

**Brain Logs** shows Kaptain's own activity as it happens: compaction, models loading and unloading, tool and delegation events, MCP servers. Filter by errors, brain, local or tools. The server's process log is a separate file, `kaptain.log` in the data folder.

### Token usage from the terminal

`kaptain usage` reads the Claude Code and Codex session records on this machine and prints token totals per session. It covers every session of those CLIs on the machine, inside Kaptain or not. Local and cloud model usage is in **BlackBox › Model usage**.

```sh
$ kaptain usage
```

```output
TOTAL processed: 28282520 tokens  (in 1204311 · cacheRead 26943618 · out 134591)

PROVIDER SESSION                                 CALLS    PROCESSED
claude   0d5f2c1e-8a4b-4f0e-9c2d-6b1a7e3f9d10      412     18402113
codex    7a91b3c4-2d5e-4f6a-8b7c-9d0e1f2a3b4c      205      9880407
```

`--json` prints every session as JSON, and `--watch` streams updates.

## Channels

Channels let you talk to Kaptain from the messaging apps you already use. Each channel is **your own bot**, run from this machine, so no public address and no open port is needed. Kaptain 0.0.9 supports **Telegram**, **Signal**, **Discord** and **Slack**.

1. Open **Channels**, choose an app and follow its steps, or run `kaptain channels setup <app>` for the same steps in the terminal. Telegram takes about five minutes with BotFather. Signal links Kaptain to your own account as an extra device, like Signal Desktop (Kaptain downloads its own Signal client, about 110 MB, once). Discord and Slack use your own bot or app.
2. Message your bot. It answers with a pairing code, because it does not know you yet.
3. Approve yourself in Channels, or with `kaptain channels approve <app> <CODE>`. Codes expire after 15 minutes.

**Who a channel serves:** **Assistant** answers only you and reads everyone else as context; **Bot** gives strangers a pairing code to request access. Groups are a second gate: add the bot to a group, mention it once, then allow that group.

| Command | What it does |
|---|---|
| `kaptain channels list` | Available and connected channels |
| `kaptain channels setup <app>` | Step-by-step setup for `telegram`, `signal`, `discord` or `slack` |
| `kaptain channels pending`, `approved` | Who is waiting, and who can talk to Kaptain |
| `kaptain channels approve <app> <CODE>` | Lets someone in, using the code from their pairing message |
| `kaptain channels revoke <app> <user>` | Takes access away; the user is an id or `@name` |
| `kaptain channels groups <app>` | Groups the bot has been mentioned in |
| `kaptain channels allow-group <app> <chat-id>`, `deny-group …` | Lets the bot answer in a group, or stops it |

Add `--account ID` to choose a connection when you have more than one. Messages that arrive through a channel are content to work on, never instructions carrying your authority. By default, an approval a channel turn needs is shown to you in the chat app for you to decide in Kaptain.

<!-- Part: Configure -->

## Settings reference

Settings has four sections: **General**, **Model Handling**, **Runtimes** and **Network Access**. Each card saves on its own; unless a row says otherwise, a change applies immediately with no restart. A card with a longer explanation shows an (i) next to its title; press it to read the explanation. Per-model choices live in the [⚙ model settings](https://chynj.ca/kaptain/docs/#model-settings), and per-agent choices in each [kapsule](https://chynj.ca/kaptain/docs/#kapsules). Settings are stored in `kaptain.json` in the [data folder](https://chynj.ca/kaptain/docs/#files), apart from per-model settings and API keys, which are stored in `models.db`.

### General

| Card | Setting | What it does | Default |
|---|---|---|---|
| Project Directory | **Set & Index** | The folder Kaptain works in: Deview, God's Eye, KodeGraph and every model tool are rooted here. Setting it re-indexes in the background. The path must exist. | the folder Kaptain was started from |
| Appearance | **Toggle light / dark** | Switches the theme for this view. The theme button in the header remembers your choice in this browser. | your system's preference |
| Update Kaptain | **Check for updates**, **Update now** | Checks the published version; **Update now** downloads, verifies and swaps the binary. Restart Kaptain to run it. See [Update and uninstall](https://chynj.ca/kaptain/docs/#update). | checks when the card opens |
| Feedback & Support | **Email the Kaptain team**, **Report a bug** | Opens an email draft with your version filled in. Nothing is sent by itself. | |
| Account & License | **Refresh entitlement**, **Open CHYNJ account**, **Subscribe / manage billing**; under **This computer**, **Sign in to register** and **Approve with a code** | Shows your plan, whether this computer is registered, your account and the trial's time left. The two **This computer** buttons register it without changing its access code ([Register a machine](https://chynj.ca/kaptain/docs/#device-register)). Always reachable, even when the licence has lapsed. See [Licence and devices](https://chynj.ca/kaptain/docs/#licence). | |

### Model Handling

**Vision tool:** which model looks at images for models that cannot. See [Images and vision](https://chynj.ca/kaptain/docs/#vision).

| Setting | Values | Default |
|---|---|---|
| Vision model | Automatic, or any model that can see images, a cloud model, a CLI, or a paired machine's model | Automatic |
| Thinking | Auto (off, then one retry with thinking if the answer is empty), Off, On | Auto |
| Answer budget, thinking off | 100 to 4,000 tokens | 1,000 |
| Answer budget, thinking on | 100 to 8,000 tokens | 2,500 |

**Delegation:** **Worker model** runs delegated briefs. Any chat model works; embedding models are not offered. There is no default: it reads **Choose a model** until you pick one and press **Save**, and delegation stays off until then. Saving the empty choice clears it. See [Delegation](https://chynj.ca/kaptain/docs/#delegation).

**Context & Compaction:** how long chats on local and cloud models stay inside the model's window. Raw messages are never deleted; models can pull old ones back with the `session_recall` tool. Claude and Codex chats are not compacted by Kaptain, because each CLI manages its own context.

| Setting | What it does | Values | Default |
|---|---|---|---|
| Summarizer | The model that writes the rolling summary | the delegate worker, or any model | the delegate worker |
| Handoff written by | Who writes the digest when a chat moves off a CLI model to another model | The CLI itself; the CLI with the summarizer as fallback; or any model | The CLI itself |
| Compact after | Summarize once this many new messages are not yet covered | 2 or more | 20 |
| Always keep verbatim | The newest messages that are never summarized | at least 1, fewer than Compact after | 2 |
| Summary size | Longest summary, in words | 100 to 8,000 | 1,200 |
| Compact inside long turns | Lets a long tool-heavy turn summarize its own earlier steps and continue | on or off | off |
| Show detailed context events | Full cards with ids and timings instead of one-line chips; this browser only | on or off | off |

**Compact this chat now** runs the summarizer on the open chat. Embedding models are not offered as summarizer or handoff author. With no summarizer chosen, Kaptain uses the delegation worker, then a model on this computer (GGUF, then Ollama), then a model on a paired machine, then a cloud model; it never picks Claude or Codex unless you choose one here. If no model can write summaries, Kaptain folds the older messages into a text-only summary without a model, and the chat's context card says so.

**KodeGraph Embedder:** the model behind semantic code search.

| Setting | What it does | Default |
|---|---|---|
| Embedding model | **Automatic (recommended)** uses an embedding model already installed in Ollama, otherwise Kaptain's built-in model (nomic-embed-text v1.5, downloaded once; see [Start Kaptain](https://chynj.ca/kaptain/docs/#start)). You can also pick **Kaptain's built-in model**, an embedding model installed in Ollama, an embedding GGUF on this machine, **None (keyword search only)** or **Custom endpoint…**. **Add a model…** adds one. Switching re-embeds your index in the background. | Automatic |
| Endpoint URL, Endpoint model | For **Custom endpoint…**: any OpenAI-compatible or Ollama embeddings endpoint, and the model name it expects | empty |
| Downloads | Lets Kaptain download the built-in model automatically when it is needed | on |

**Now serving** and **Kaptain runtime** show what is in use. **Install llama.cpp now** appears when Kaptain's own runtime is missing.

**Scheduled Agents & Local Models:** **Distinct local models running agent jobs at once**, 0 to 16. When scheduled agents collide, local models beyond this number wait their turn instead of stacking in memory; runs that share a model, and cloud runs, are never held. 0 means the default of 2; set 1 on a machine where two models crowd your memory. Applies from the next scheduled run.

**Sudo requests:** **Ask me for my password** (on by default) means every sudo a model or CLI runs, including one inside a program it started, opens a pop-up and you decide. Off means sudo commands are not run and the model is told why. **Remember a typed password within a task for** sets how long the password is kept for later pop-ups in the same task: 2 minutes by default, 0 to type it every time, at most 30. Every sudo still shows a pop-up. See [Approval modes](https://chynj.ca/kaptain/docs/#approvals).

**Models:** a read-only count of every model Kaptain can reach, by route.

### Runtimes

| Card | What it does |
|---|---|
| Ollama Runtime | Shows whether Ollama is installed and running, who manages it, its version and the GPU it uses, with **Start**, **Stop** and **Update** where they apply, and **Install Ollama for me** on Linux when it is missing. Actions on a system service ask for your password once and never store it. |
| llama.cpp Runtime | Shows the `llama-server` in use and the GPU. **Start server** and **Stop server** load or unload a GGUF model. **Executable path** with **Save path** sets a specific `llama-server`; **Use auto-detect** clears it. A saved path is used from the next load. |
| Toolchain Paths | Kaptain reads your login shell's PATH, so commands models run find the same tools you do. **Extra PATH directories** adds folders it cannot find; **Rescan** re-reads the PATH. Applies immediately. |
| Agent Shell (Windows) | Windows only. Which shell runs model commands: **Install portable Git Bash** (about 37 MB) or set **Manual bash path**. Without Git Bash, commands fall back to `cmd.exe`, with fewer tools available. |
| Providers & keys | Whether the Claude CLI, Codex CLI, cloud models and local GGUF files are available. **Update keys** replaces cloud API keys; a blank field keeps the saved key. |

### Network Access

| Card | Setting | What it does | Default |
|---|---|---|---|
| Connection | | Shows the address Kaptain serves on, the engine, and the GPU. **Fix GPU access** appears when a GPU is present but unusable. | |
| Network Access | **Localhost only** or **Tailscale** | Who can connect. Needs a restart: the card says **Saved — one restart to apply it** and offers **Restart Kaptain now**. Tailscale cannot be chosen until it is installed and connected. See [Network and remote access](https://chynj.ca/kaptain/docs/#network). | Localhost only |
| | **Require an allowlisted Tailscale device for non-local access** | Admits only the tailnet devices you choose. Your own machine is always allowed. Changes to the list are staged until **Save changes**. | off |
| | **Share models between your computers** | Lend models to, and borrow models from, your other Kaptains. See [Pairing machines](https://chynj.ca/kaptain/docs/#pairing). | off |
| New access code | **Current access code**, **New access code** | Makes a new access code after you type the current one; the old one and every other browser's pairing stop at once. The new code is shown once, with **Copy**. See [Get a new access code](https://chynj.ca/kaptain/docs/#access-code-new). | |
| Access log | **Refresh** | The last 200 requests: time, status, address, method, path and duration. Requests without credentials are marked unauth. | |

### Settings without a screen

A few settings are read from `kaptain.json` but have no control in Settings. Edit the file while Kaptain is stopped, then start it; the network keys below are also picked up within about 30 seconds while running.

| Key | What it does | Default |
|---|---|---|
| `allowed_hosts` | Extra host names the browser may use, such as a Tailscale name. See [HTTPS over Tailscale](https://chynj.ca/kaptain/docs/#https). | none |
| `allowed_client_cidrs` | Extra client address ranges allowed to connect, for example a trusted proxy | none |
| `ollama_url` | Where Ollama listens | `http://127.0.0.1:11434` |
| `max_tool_rounds` | Tool round trips allowed in one turn | 50 |
| `max_parallel_tools` | Read-only tool calls run at the same time, up to 8 | 4 |
| `approval_timeout_seconds` | How long an approval waits for you once shown | 300 |
| `stall_timeout_seconds` | A turn with no model output and no tool progress for this long is stopped by the stall guard. `KAPTAIN_STALL_TIMEOUT` wins when set. | 720 (12 minutes) |
| `agent_turn_timeout_seconds` | How long one kapsule run, direct message to an agent or agent call may take | 7200 (2 hours) |
| `agent_run_memory` | Run memory for every kapsule that does not set its own | off |
| `shell_allow_project_tests` | Lets `cli_exec` run `pytest`, `go build`, `go vet`, `go test` and `npm test` without asking in Ask mode; the `test_run` tool still asks | off |
| `shell_readonly_extra` | Your own commands to treat as read-only in Ask mode | none |
| `shell_job_max_minutes` | How long a command that outran its time limit may keep running in the background; 0 means no limit | 60 |
| `tool_result_window_percent` | The share of the model's window one tool result may use, 5 to 50 | 15 |
| `turn_results_window_percent` | The share all of a message's tool results may use together, 10 to 80 | 30 |
| `tool_result_tail_calls` | How many of the chat's most recent tool calls ride whole into the next messages, at most 32; a negative number carries none | 5 |
| `turn_time_stamp` | Where a run's date and time go: `brief` (under **About this run**, your message unchanged) or `message` (stamped at the end of each of your messages). See [Traces](https://chynj.ca/kaptain/docs/#traces). | `brief` |
| `run_record_ttl_days` | How many days a run's [trace record](https://chynj.ca/kaptain/docs/#traces) is kept | 30 |
| `run_record_max_rows` | How many runs' trace records are kept at most; the oldest go first | 20000 |

> [!WARNING]
> `kaptain.json` also holds this machine's credentials: the access code, the device key and account details. Do not share it, and never edit the keys you do not recognise.

## Security model

Kaptain's security comes from a few blunt decisions rather than subtle ones.

- **Local first.** Kaptain, your chats, keys and files live on your machine. No Kaptain cloud sees your prompts. CHYNJ's servers hold account and licensing records; your device is known to them by a hash of its fingerprint.
- **No internet exposure by default.** The network mode is this machine or your own Tailscale network; no other mode is offered. The operator override `KAPTAIN_ADDR` can bind another address, but every request is still refused unless it comes from this machine, from your tailnet in Tailscale mode, or from a range you add to `allowed_client_cidrs`.
- **One gate for every risky action.** Built-in tools, MCP tools and shell commands all pass the same approval gate, with the same [approval modes](https://chynj.ca/kaptain/docs/#approvals). Read-only shell commands run without a prompt, so you are not asked about every `ls`.
- **Scopes name targets, never tools.** A kapsule can be pre-approved for a folder or one MCP server. The approval mode stays the ceiling.
- **Three codes, three jobs.** The **access code** (`chynj_…`) signs a person into this Kaptain. A **connection code** (`kcat_…`) lets another of your Kaptains use this one's models, and nothing else. The **device certificate** identifies this machine to the licence server. None can stand in for another.
- **Messages are data.** Text that arrives from another agent, another machine or a channel is material to reason about, never an instruction carrying the receiver's authority. Authority comes only from the receiving kapsule's own settings.

## Network and remote access

Kaptain has exactly two network modes, and neither reaches the internet: **Localhost only**, this machine, and **Tailscale**, your own tailnet.\*

> [!NOTE] * Your network is yours
> CHYNJ does not manage or warrant the security of your network, your devices or your Tailscale account. Kaptain uses the tailnet you set up and run; who is on it, and how it is secured, is up to you. The [Terms of Service](https://chynj.ca/legal/terms/), which you accept before you download Kaptain and before your CHYNJ account is created, apply.

| Mode | Kaptain listens on | Who can connect |
|---|---|---|
| **Localhost only** (default) | `127.0.0.1:8810` | Programs and browsers on this machine |
| **Tailscale** | this machine's tailnet address, such as `100.x.y.z:8810` | Devices on your own tailnet that know the access code. In this mode, this machine also uses the tailnet address; `127.0.0.1` is refused. |

### Reach Kaptain from your phone or another computer

1. Install [Tailscale](https://tailscale.com/download) on the Kaptain machine and on the other device, and sign both into the same tailnet. On the Kaptain machine, `tailscale ip -4` prints its `100.x.y.z` address.
2. Switch Kaptain to Tailscale: **Settings › Network Access › Tailscale**, or `kaptain remote on` in a terminal (below).
3. Restart Kaptain: **Restart Kaptain now** in Settings, or `kaptain stop`, then `kaptain start`.
4. On the other device, open `http://100.x.y.z:8810` and enter the [access code](https://chynj.ca/kaptain/docs/#access-code).

In Tailscale mode, start Tailscale before Kaptain. If Kaptain starts while Tailscale is down, it falls back to `127.0.0.1` and only this machine can reach it; start Tailscale and restart Kaptain, or switch back with `kaptain remote off`.

### kaptain remote

`kaptain remote` shows the current mode and checks whether this machine is ready for remote access. It changes nothing:

```sh
$ kaptain remote
```

```output
  Remote access: OFF — Kaptain listens on 127.0.0.1 only

  ✓ Tailscale                  up, this machine is 100.x.y.z
  ✗ Setup complete             no access code yet, so anyone on your tailnet could complete setup and take over this box
  ✗ Device registered          this machine is not registered to your CHYNJ account
  ✗ Licence                    Your 3-day free trial has not started.
  ! MFA                        off — the access code alone opens a session from any tailnet device
  ! Device allowlist           off — every device on your tailnet may reach Kaptain

  Not ready yet — see the ✗ lines above.
```

`kaptain remote on` refuses while any ✗ check fails, and says how to fix each one:

```output

Remote access was NOT enabled. Fix these first:

  ✗ Setup complete
    no access code yet, so anyone on your tailnet could complete setup and take over this box
    → run `kaptain setup` first
  ✗ Device registered
    this machine is not registered to your CHYNJ account
    → run `kaptain device register`
  ✗ Licence
    Your 3-day free trial has not started.
    → run `kaptain license refresh` (or `kaptain license status` to see why)
```

It switches to Tailscale only when every ✗ check passes: Tailscale up, setup finished, the device registered to your account, and a current licence. A machine set up in the terminal with `skip`, or one whose registration failed, has no device certificate and fails the "Device registered" check: run `kaptain device register` first, or switch in **Settings › Network Access**, which does not run these checks. `kaptain remote off` always works:

```sh
$ kaptain remote off
```

```output
  Remote access disabled. Kaptain will listen on 127.0.0.1 only.

  Restart Kaptain for this to take effect:
      kaptain stop && kaptain start
```

When it is already off: `Remote access is already off — Kaptain listens on 127.0.0.1 only.`

Add `--json` to any form for machine-readable output.

### Pair a browser or the app

A browser or app that reaches Kaptain without credentials sees **Pair this browser with Kaptain**. Enter the access code and press **Connect**. The browser stays paired for 14 days, or until the access code changes. When the code changes, every other browser pairs again with the new one; the browser that made the change stays paired. Scripts and other programs can send the code as `Authorization: Bearer chynj_…`. The pairing screen says where the code is saved: `access-code.txt` in the data folder, and `kaptain status` prints the path. If you deleted that file, the code is `api_token` in `kaptain.json`. To replace it, see [Get a new access code](https://chynj.ca/kaptain/docs/#access-code-new).

### Allow only some devices

By default any device on your tailnet that knows the access code can connect. To narrow that, turn on **Require an allowlisted Tailscale device for non-local access** in Settings › Network Access, tick the devices that keep access, and confirm. Tailscale vouches for each device's identity. You can also type a machine name, a tailnet address, a Machine ID, or a Tailscale login, which admits every device that person owns. This machine is always allowed, and turning the lock off never needs confirmation.

The **Access log** card shows who reached this Kaptain. A burst of unauth entries from one address is usually an unpaired browser tab polling; pair it and it stops.

## HTTPS over Tailscale

Kaptain itself serves plain HTTP. Tailscale already encrypts traffic between your devices, but browsers only show HTTPS, and only allow some features, on an `https://` address. Tailscale Serve gives Kaptain a trusted HTTPS address on your tailnet:

1. In the Tailscale admin console, turn on **MagicDNS** and **HTTPS Certificates**. Note the machine's full name, such as `kaptain-box.example.ts.net`. The certificate's name is published in public certificate logs, so rename the machine first if its name is private.
2. Keep Kaptain in **Localhost only** mode. Serve connects to Kaptain from this machine, which Tailscale mode refuses.
3. Publish Kaptain on the tailnet: `tailscale serve --bg 8810`.
4. Allow the name. Add it to `allowed_hosts` in `kaptain.json`. Kaptain picks it up within about 30 seconds:

```json
{
  "network_mode": "localhost",
  "allowed_hosts": ["kaptain-box.example.ts.net"]
}
```

Open `https://kaptain-box.example.ts.net/` from a device on your tailnet and pair with the access code. Until the name is allowed, Kaptain answers `421 Misdirected Request` ("Host header is not allowed"). The same applies to any machine name you type instead of the tailnet address. Tailscale renews the certificate itself.

Behind Serve, every request reaches Kaptain from this machine, so the device allowlist does not apply, rate limits are shared, and the access log shows `127.0.0.1` for everyone. Leave `trust_forwarded_for` off. Use `tailscale serve`, not Tailscale Funnel, which would expose Kaptain beyond your tailnet.

## Pairing machines

Two of your Kaptains can share models: lend a model from one computer and use it from another, over your tailnet. The lending machine must be in **Tailscale** mode, and both must be on the same tailnet.\* The borrower runs inference on the lender's models over your tailnet; the lender's models appear in the borrower's picker under the lender's name, as `node:<lender>/<model>`, and work everywhere a local model does: chat, kapsules, delegation, the summarizer and the vision tool.

**What crosses, and what does not.** The conversation and tool definitions cross, because the lender's model has to read them. Chats, files, settings and approval decisions never do. When a borrowed model asks for a tool, the tool runs on the borrower's machine, under the borrower's approval gate. The lender's own model settings (context window, output cap, thinking) apply to its models.

> [!WARNING]
> A lent **Claude or Codex CLI** is different: it runs its own tools on the lender's machine. Kaptain labels these "runs work here" and warns when you include them in a code. They are lent only when **Share my signed-in CLI harnesses (Claude, Codex)** is on, or in My Kaptail mode.

### Set up the lending machine

1. Switch Network Access to **Tailscale** and restart.
2. In **Settings › Network Access › Share models between your computers**, turn on **Let other computers use this one's models**. Kaptain asks for this machine's access code.
3. Choose who may connect: **My Tailnet** (any device Tailscale vouches for), **Custom** (only devices on your allowlist), or **My Kaptail** (only machines on the same licence; see the note below). **My Kaptail** is selected at first.
4. Under **Issue a token**, choose what it may do (**Use the models on this computer**, **Only see which models exist**, or **Use the models, and manage codes**), when it expires (24 hours, 7 days, 30 days or never) and, optionally, which models it covers. Press **Issue token**; Kaptain asks for the access code again. Copy the `kcat_…` code. It is shown once.

### Connect from the borrowing machine

In **Settings › Network Access**, under **Computers you can borrow models from**, enter the lender's tailnet address and the `kcat_…` code and press **Connect**. Kaptain answers "Connected to <name> — N model(s) now in your picker." Run one small prompt on a borrowed model to confirm.

To end access, press **Revoke** next to the code on the lending machine. It takes effect immediately.

> [!NOTE]
> **My Kaptail** proves both machines hold the same licence. In 0.0.9 that proof needs a licence key pasted on both machines, and the borrower must run `kaptain nodes verify <lender address>` in a terminal within the 10 minutes before connecting. For a connection made from Settings alone, use **My Tailnet** or **Custom**.

### From the terminal

```sh
$ kaptain nodes status
```

```output
  cluster identity   off (peers see 404)
  mode               license
  can prove licence  NO — this box has no licence key; only tailnet/custom modes can work
  verified peers     0
```

| Command | What it does |
|---|---|
| `kaptain nodes status` | This machine's sharing settings and verified peers. Needs Kaptain running. |
| `kaptain nodes verify <host>` | Runs the identity handshake with another Kaptain. |
| `kaptain nodes token <host> <kcat_…>` | Stores a code that machine issued you. |
| `kaptain nodes models <host>` | Lists the models that machine lets you run. |
| `kaptain nodes ask <host> <model> "<prompt>"` | Runs one prompt there and streams the answer. |

A code never leaves the machine that stores it: each request carries a signature bound to that request, not the code itself. Add `--json` for machine-readable output.

## Licence and devices

### How a computer gets registered

1. Create your CHYNJ account at chynj.ca, or in Kaptain's setup.
2. On the computer, sign in to that account: in Kaptain's setup, or run `kaptain device register` in a terminal and approve the code it prints at chynj.ca/account.
3. The computer registers as a device and takes one seat of your plan's device limit.
4. CHYNJ issues the computer's licence, a signed lease that Kaptain renews on its own, and Kaptain starts working.
5. If you remove a device, sign in on that computer again to register it again.

> [!NOTE]
> A licence key alone never registers a computer. Signing in is always required.

### The three things behind it

Three separate things make Kaptain usable on a machine:

| Thing | What it is | How you get it |
|---|---|---|
| **Licence** | Your plan, attached to your CHYNJ account email | Subscribe at [chynj.ca/account](https://chynj.ca/account/), or start the 3-day trial |
| **Device certificate** | Proof that this machine may use your licence | Finishing the setup wizard while signed in, or `kaptain device register` |
| **Entitlement** | A short-lived signed proof, refreshed in the background about every 4 hours | Automatic once the machine is registered or on a trial |

A licence key proves you bought a plan; the certificate proves this machine may use it; the entitlement lets Kaptain keep working through short network outages without phoning home on every request. The trial is 3 days, needs no card, and belongs to the machine: reinstalling does not restart it. Pro covers up to 5 devices. To free a seat, open [chynj.ca/account](https://chynj.ca/account/) and, under **Devices using your license**, press **Sign out** or **Remove** on a device. **Sign out** keeps the device listed under Revoked; on that computer Kaptain says "This computer was signed out of your licence on chynj.ca. Restore it there to use it again." **Restore** on its row lets that computer register again by signing in. **Remove** asks once, then takes the device off your account; Kaptain on that computer says it was removed and asks you to sign in to register it again. Each row shows the first characters of the device's fingerprint hash, which [`kaptain device status`](https://chynj.ca/kaptain/docs/#licence-status) prints in full.

Creating a CHYNJ account, on chynj.ca, in the setup wizard or with `kaptain setup`, asks you to agree to the Terms of Service and Privacy Policy, and CHYNJ records which versions you agreed to, when, and where. Signing in to an account you already have asks nothing new. CHYNJ refuses accounts, trials and licence renewals from places Canadian sanctions law does not let it serve; [chynj.ca/legal/availability](https://chynj.ca/legal/availability/) lists them. The website, these docs and the downloads stay open to everyone.

### Check where a machine stands

```sh
$ kaptain device status
```

```output
{
  "cert_id": "",
  "entitlement": {
    "message": "Your 3-day free trial has not started.",
    "ok": true,
    "status": "not_started",
    "trial": {
      "consumed": false,
      "is_active_license": false,
      "status": "not_started"
    },
    "type": "trial_not_started",
    "valid": false
  },
  "fp_hash": "9c1e4f0a7b2d6e83c5a1f9047d3b8e2a6f1c0d9b4e7a2c5f8d3b6e1a9c4f7d20",
  "ok": true,
  "registered": false
}
```

That is a machine that was never registered and never started a trial. `fp_hash` is this machine's fingerprint hash, the value the licence server knows it by: chynj.ca shows its first characters beside each device under **Devices using your license**, so you can tell which row is this computer. `kaptain license status` prints just the entitlement, and `kaptain account status` adds the signed-in account. All three only read local files. `kaptain license refresh` asks the licence server for a fresh entitlement and says why if it cannot.

### Register a machine

Use this on a machine set up from the terminal, after a skipped sign-in, after a device was removed on chynj.ca, or whenever the machine shows as unregistered. It needs an active plan, or a trial on a verified email. Registering keeps this computer's access code, so paired browsers and phones stay paired. There are two ways.

**In Settings.** Open **Settings › General › Account & License**. Under **This computer**, press **Sign in to register** and enter your CHYNJ email and password (and the 6-digit code if your account uses two-factor sign-in), or press **Approve with a code** and approve the code it shows at chynj.ca/account. The card then says **Registered**, with your plan.

**In a terminal,** on the Kaptain machine:

1. Run `kaptain device register`. It prints how a computer gets registered, then a code and the address to approve it at, opens your browser (unless you add `--no-browser`), and waits. With Kaptain running, it uses the same flow as the Settings card.
2. On any device, open [chynj.ca/account](https://chynj.ca/account/), sign in, and approve the code. Codes expire after 15 minutes; run the command again for a new one.
3. The command stores the certificate and the licence and prints `This computer is registered (plan: pro). Its access code did not change.`

```output
Approve this computer at chynj.ca/account with this code:
  Code: <XXXXXX-XXXXXX>
  URL:  <approval address>
Waiting for approval — the code expires at 14:32.
This computer keeps its access code: browsers and phones paired with it stay paired.
This computer is registered (plan: pro). Its access code did not change.
```

A computer that has no access code yet, because it never finished setup, gets one: the command prints it once after `Device registered. Save this local access code; it is shown once:` and saves it to `access-code.txt` in the data folder. A computer that was signed out on chynj.ca is not registered again: the command says "This computer was signed out of your licence on chynj.ca. Restore it on chynj.ca first, then register it." On a computer that is already registered the command prints the registration (plan, account, licence until) and asks `This computer is already registered. Register again? [y/N]` before it starts a flow; with `--json`, or when nothing can answer (piped input), it prints that state and exits 0 without starting one, unless you add `--again`. Nothing secret is typed into the command. `--nickname NAME` names the machine in the portal (the hostname by default), and `--json` prints machine-readable output.

### When Kaptain answers 402

A release build checks its entitlement on every request. When it cannot, the interface still opens, but its requests answer **402 Payment Required** with `entitlement_required`, so chats, models and most settings fail to load. **Settings › General › Account & License** keeps working so you can fix it.

| Message (in the 402, or from `kaptain license refresh`) | Cause | Fix |
|---|---|---|
| Your 3-day free trial has not started. | The machine was never registered and no trial was started, for example after skipping sign-in in `kaptain setup` | Sign in: run `kaptain device register` and approve the code at chynj.ca/account |
| Device entitlement has not been refreshed. | The machine is registered, but has not fetched its entitlement yet, for example because it has been offline since | Reconnect, then `kaptain license refresh` |
| entitlement lease expired | No successful refresh for about a day: offline too long, or the refresh is failing | Reconnect, then `kaptain license refresh`; its message says what is wrong |
| This computer was removed from your account on … Sign in to register it again. | The device was removed on chynj.ca under **Devices using your license** | Register it again: **Sign in to register** in **Settings › General › Account & License**, or `kaptain device register` ([Register a machine](https://chynj.ca/kaptain/docs/#device-register)) |
| This computer was signed out of your licence on chynj.ca. Restore it there to use it again. | The device was signed out on chynj.ca | Press **Restore** on its row at [chynj.ca/account](https://chynj.ca/account/), then register the computer again: **Sign in to register** in **Settings › General › Account & License**, or `kaptain device register` |
| device entitlement is revoked | The licence server marked this device's entitlement revoked, for example after it was signed out | Restore it on chynj.ca, or sign in on that computer to register it again ([How a computer gets registered](https://chynj.ca/kaptain/docs/#how-registered)) |
| entitlement is bound to a different device certificate | The machine was registered again part-way | `kaptain license refresh` |
| entitlement is bound to a different installation key | The device key in `kaptain.json` changed or was lost | Register again |
| trial entitlement is bound to a different installation fingerprint | A machine on a trial that was never registered changed its hostname, or its data folder moved to another machine | Restore the old hostname, or subscribe and register |
| entitlement is not valid yet | The system clock is behind | Fix the clock, then `kaptain license refresh` |
| Kaptain G1_beta_v0.0.7 is below the minimum safe version G1_beta_v0.0.8, so this computer's licence was not renewed. … | This computer runs a Kaptain release older than the oldest one the licence server still renews, so it refused the renewal. Kaptain keeps working until its current entitlement runs out, within a day. Development builds and builds without a release version are never refused | Update Kaptain: **Settings › General › Update Kaptain**, `kaptain update` in a terminal, or run the [installer](https://chynj.ca/kaptain/docs/#install) again ([Update](https://chynj.ca/kaptain/docs/#update-kaptain)). Once the entitlement has run out, Settings answers 402 as well; use the terminal or the installer. Then `kaptain license refresh` |
| License or trial expired. | The trial ended or the subscription lapsed | Subscribe or renew in the portal, then `kaptain license refresh` |
| CHYNJ cannot offer accounts, trials or licences where you are connecting from… | You are connecting from a place CHYNJ cannot serve under Canadian sanctions law, so the entitlement is not renewed | See [chynj.ca/legal/availability](https://chynj.ca/legal/availability/) |

A registered machine, on a paid plan or a trial, keeps working when you copy its data folder to new hardware: the certificate and its key travel in the folder. Only a trial that was never registered is tied to the machine's fingerprint, which includes its hostname.

**Licence troubleshooting:** the licence email went missing? Your key is always in the [account portal](https://chynj.ca/account/) under License (the email comes from `noreplycode@chynj.ca`; check spam). "No license found" means the licence is on a different email. "Device limit reached" means freeing a seat first: **Sign out** or **Remove** an old device on chynj.ca. "Invalid key" usually means stray spaces: use the portal's Copy button.

## Files and environment

### The data folder

**Linux**
`~/.local/share/kaptain/`
**macOS**
`~/Library/Application Support/Kaptain/`
**Windows**
`%LOCALAPPDATA%\Kaptain\`, which is `C:\Users\<your name>\AppData\Local\Kaptain\`. `AppData` is hidden: run `explorer $env:LOCALAPPDATA\Kaptain` in PowerShell, or paste `%LOCALAPPDATA%\Kaptain` into Explorer's address bar. This is the data, not the program, which is in `%LOCALAPPDATA%\Programs\Kaptain\` if you followed the [PATH step](https://chynj.ca/kaptain/docs/#path).

Every account on a computer has its own data folder under its own user folder. Set `KAPTAIN_DATA_DIR` to use another folder. To run a second, separate Kaptain next to the first, give it its own port as well, for example `KAPTAIN_DATA_DIR=~/kaptain-two KAPTAIN_PORT=8820 kaptain start`: with the data folder alone, `kaptain start` finds the first Kaptain on 8810 and says `already running`. `kaptain serve --data DIR` sets the data folder for one run.

| In the data folder | What it holds |
|---|---|
| `kaptain.json` | Settings and this machine's credentials. Private to your user. |
| `sessions.db` | Chats and runs |
| `models.db` | Models, cloud API keys, per-model settings and agent overrides |
| `kapsules/<name>/` | Each kapsule's definition: `kapsule.json`, its memory and its lessons. Its workspace is `.kaptain/kapsules/<name>/` in the project folder. |
| `skills/` | Your machine-wide skills |
| `mcp_servers.json` | MCP servers you connected |
| `plugins/` | Tool programs dropped in to register automatically |
| `kaptain.log`, `kaptain.pid` | The background server's log and process id, written by `kaptain start` |
| `access.jsonl` | The access log |
| `access-code.txt` | The access code, readable only by you. Written by setup (in the browser or `kaptain setup`), by every new access code, and by `kaptain device register` on a computer that had none. Delete it once your devices are paired |
| `models/embed/`, `runtimes/llama.cpp/` | The code-search model and the llama.cpp runtime, downloaded when you choose Kaptain's built-in code search or press **Install llama.cpp for me** |
| `results/` | Tool results too large for the model's window, saved whole and read back by id ([Big tool results](https://chynj.ca/kaptain/docs/#big-results)) |
| `runtimes/ollama/` | Ollama's official installer, kept after **Install Ollama for me** (Linux) |
| `run/sudo-shim/` | The helper that sends a `sudo` inside a command to Kaptain's pop-up ([Approval modes](https://chynj.ca/kaptain/docs/#approvals)). Not on Windows. |
| `cluster-peers.json`, `cluster-grants.json` | Machines you borrow from, and the connection codes you issued |
| `backups/` | Copies of `kaptain.json` saved before each settings migration |

### Outside the data folder

| Where | What |
|---|---|
| your project folder | `.kodegraph/` (the code index), and a `.planning/` folder if Kaptain 0.0.8 or earlier made one; 0.0.9 no longer does |
| `~/.local/share/kaptain/models/` | GGUF models you download, on every operating system, unless `KAPTAIN_MODELS_DIR` is set. On Windows that is `C:\Users\<your name>\.local\share\kaptain\models\`, next to the data folder rather than in it |
| `~/.cache/kaptain/` (`~/Library/Caches/kaptain/` on macOS) | Attachments and the unpacked helper Kaptain uses for Claude, in `attachments/` and `sidecar/`. On Windows these two folders are inside the data folder, `%LOCALAPPDATA%\Kaptain\`, because Windows has no separate cache folder |
| `~/llama/llama.cpp/`, `~/.local/bin/llama-server` | A llama.cpp Kaptain built from source, when no official build fits this machine or you chose **Build llama.cpp for this GPU** |
| `~/.claude.json`, `~/.codex/config.toml`, `~/.gemini/settings.json` | Only if you register Kaptain's tools with those CLIs ([MCP](https://chynj.ca/kaptain/docs/#mcp)) |
| next to the binary | `kaptain.bak`, the previous version kept by `kaptain update` |

### Back up or move a machine

1. Stop Kaptain with `kaptain stop`. Never copy the databases while it runs.
2. Copy the data folder. Copy `~/.local/share/kaptain/models/` too if you downloaded GGUF models.
3. On the new machine, install Kaptain, put the folder in place and run `kaptain start`.

A registered machine's certificate moves with the folder. A trial that was never registered stays tied to the original machine.

### Environment variables

| Variable | What it does | Default |
|---|---|---|
| `KAPTAIN_DATA_DIR` | The data folder | per operating system, above |
| `KAPTAIN_PORT` | The port Kaptain serves on | `8810` |
| `KAPTAIN_ADDR` | A full `host:port` to bind, overriding the network mode. A non-local address needs setup finished first. | unset |
| `KAPTAIN_MODEL_URL` | Where Ollama listens | `ollama_url`, else `http://127.0.0.1:11434` |
| `KAPTAIN_MODEL` | The fallback chat model for agents and the terminal | the model chosen in setup |
| `KAPTAIN_DELEGATE_MODEL` | The delegation worker; overrides **Settings › Model Handling › Delegation** at start | unset |
| `KAPTAIN_MODELS_DIR` | Where GGUF downloads go, and an extra place to look for them | `~/.local/share/kaptain/models` |
| `KAPTAIN_LLAMA_SERVER_BIN` | The `llama-server` to use | discovered |
| `KAPTAIN_GPU_LAYERS` | GPU layers for llama.cpp: `0` for CPU only, `999` for all | detected |
| `KAPTAIN_EMBED_PREPROVISION` | `0` stops every background code-search download | downloads once code search is chosen |
| `KAPTAIN_KG_REINDEX_SECONDS` | How often the code index refreshes; 0 or less turns that off | `120` |
| `KAPTAIN_VISION_MODEL` | The vision model when Settings has none | unset |
| `KAPTAIN_VISION_TIMEOUT_S` | How long one image description may take | `600` |
| `KAPTAIN_CLI_TOOL_TIMEOUT_S` | How long Claude and Codex wait for a Kaptain tool | `900` |
| `KAPTAIN_APPROVAL_TIMEOUT_S` | For Claude and Codex turns only: how long the bridge waits for your approval. Keep it equal to `approval_timeout_seconds` in `kaptain.json`, which sets the actual wait. | `300` |
| `KAPTAIN_STALL_TIMEOUT` | Cancels a turn that has been silent this long | `12m` |
| `KAPTAIN_SKILL_IMPORT_ROOTS` | Extra folders of skills to load | none |
| `KAPTAIN_CLOUD_URL`, `KAPTAIN_CLOUD_KEY`, `KAPTAIN_CLOUD_MODELS` | Adds a cloud endpoint and model ids without the UI | unset |
| `KAPTAIN_NO_ENGINE` | Any value starts Kaptain without its tools | unset |
| `KAPTAIN_TOOL_HARD_TIMEOUT_S` | The longest one tool call may run before it is cut off and the model is told why. Tools keep their own, shorter limits. | `7200` (2 hours) |
| `KAPTAIN_STOP_FORCE_GRACE_S` | After **Stop**, how long Kaptain waits for a tool to end before closing the turn anyway | `30` |
| `KAPTAIN_RUN_SWEEP_INTERVAL_S` | How often Kaptain looks for runs left open by a turn that ended abnormally | `60` |
| `KAPTAIN_RUN_SWEEP_GRACE_S` | How old such a run must be before the sweep closes it | `180` |
| `KAPTAIN_TOOL_DIGEST_MAX_CHARS` | The size of the record of tool calls each reply carries into the next turn | `2000` |

Set the same `KAPTAIN_PORT` or `KAPTAIN_ADDR` for `kaptain status` and `kaptain stop` that you used for `kaptain start`; they look for Kaptain where those variables point.

## Update and uninstall

### Update

Update from **Settings › General › Update Kaptain** (**Check for updates**, then **Update now**), or from a terminal:

```sh
$ kaptain update --check
kaptain <version> — up to date.
$ kaptain update
```

`kaptain update` downloads the published build for your platform, checks the release manifest's signature and the file's SHA-256, runs the new binary once, then swaps it in. The old binary is kept next to it as `kaptain.bak`. If any step fails, your installation is left untouched. The new version runs after a restart:

```sh
$ kaptain stop
$ kaptain start
```

| Flag | What it does |
|---|---|
| `--check` | Reports whether an update is available; installs nothing |
| `--force` | Reinstalls the published build even if the version matches |
| `--json` | Machine-readable output |

The update replaces the binary where it is, so its folder must be writable by you. Re-running the [installer](https://chynj.ca/kaptain/docs/#install-linux) also updates.

### Uninstall

`kaptain uninstall` shows what it would remove and changes nothing until you add `--yes`:

```sh
$ kaptain uninstall
```

```output

Kaptain uninstall — dry run (nothing will change)

Detected:
  data dir   /home/you/.local/share/kaptain  (176.2M)
  binary     /home/you/.local/bin/kaptain

Mode: full removal — Kaptain is stopped, then its data, cache, downloaded runtimes, binary and MCP registrations are all deleted. Nothing is left behind.

Dry run complete. Re-run with --yes to apply.
```

`kaptain uninstall --yes` stops a Kaptain started with `kaptain start` (stop a foreground `kaptain serve` first), deletes its data and cache folders, the downloaded runtimes and the binary named `kaptain`, removes the `kaptain-engine` entries it added to the Claude, Codex and Gemini CLI configs, and then checks that nothing is left (`Verifying: clean.`). Run it as yourself, not with `sudo`. Step by step:

**Linux**
```sh
$ kaptain uninstall
$ kaptain uninstall --yes
$ ls -d ~/.local/share/kaptain ~/.cache/kaptain ~/.kaptain
```
The first command previews the list; read it. The second removes everything. The third should report "No such file" for all three.
**macOS**
```sh
$ kaptain uninstall
$ kaptain uninstall --yes
$ ls -d ~/Library/Application\ Support/Kaptain ~/Library/Caches/kaptain
```
The last command should report "No such file" for both.
**Windows**
```powershell
PS> kaptain stop
PS> kaptain uninstall
PS> kaptain uninstall --yes
PS> Test-Path $env:LOCALAPPDATA\Kaptain
PS> Test-Path $env:APPDATA\Kaptain
```
`kaptain stop` matters only if Kaptain runs from a shortcut or a startup entry. Both `Test-Path` lines should print `False`.

**If `kaptain` is gone from your PATH but its files are still there**, or your installed build has no `uninstall`, download the current build and run `uninstall` from it. A downloaded copy cleans up the installed Kaptain and never deletes itself:

```sh
$ curl -L -o kaptain-new https://chynj.ca/download/kaptain/linux-x64
$ chmod +x kaptain-new
$ ./kaptain-new uninstall
$ ./kaptain-new uninstall --yes
$ rm kaptain-new
```

Use `linux-arm64` on 64-bit ARM. On Windows: `curl.exe -L -o kaptain-new.exe https://chynj.ca/download/kaptain/win`, then `.\kaptain-new.exe uninstall`, `.\kaptain-new.exe uninstall --yes` and `Remove-Item .\kaptain-new.exe`.

| Flag | What it does |
|---|---|
| `--yes` | Performs the removal |
| `--identity-only` | Removes only this machine's licence, device identity, account sign-in and access code from `kaptain.json`; keeps chats and settings. An `access-code.txt` is left in place, but its code no longer works |
| `--keep-access-code` | Saves the access code to `~/kaptain-access-code.txt` first |
| `--keep-runtimes` | Keeps the downloaded runtimes beside the data folder |
| `--json` | Machine-readable report |
| `--fingerprint` | Prints this machine's device fingerprint hash and changes nothing |

It does not remove Ollama or its models, GGUF models in `~/.local/share/kaptain/models` on macOS and Windows, a llama.cpp Kaptain built from source in `~/llama`, your project's `.kodegraph/` and `.kaptain/` folders (or a `.planning/` folder an earlier version made), or the PATH line you added. A Kaptain build inside a source tree, or the copy you are running, is listed under `LEFT ALONE` with its full path instead of deleted: running it creates the data folder again, so delete it yourself for a bare machine.

Uninstalling removes Kaptain from this machine only. It does not cancel your subscription, change your licence or reset the trial; manage those at [chynj.ca/account](https://chynj.ca/account/). A full uninstall deletes this machine's access code, so the next setup makes a new one. `--keep-access-code` saves it first; put it back only after the new setup has finished, or setup never opens.

<!-- Part: Reference -->

## Krew tools reference

Every built-in tool in Kaptain 0.0.9, in one shape: what it does, when a model uses it, what the [approval gate](https://chynj.ca/kaptain/docs/#approvals) does with it, its parameters and an example. The permission lines describe local and cloud models; Claude Code and Codex apply their own permission modes ([mapping](https://chynj.ca/kaptain/docs/#approvals)). Kaptain adds the session and approval mode to every call itself; they are not parameters.

For a local or cloud model, one tool result may fill at most 15% of the model's context window, and all of one message's results 30% (`tool_result_window_percent` and `turn_results_window_percent` in `kaptain.json`). A bigger result is saved whole, and the model gets a short notice instead (its size, shape, id and how to read it) and reads it with [`tool_result_recall`](https://chynj.ca/kaptain/docs/#tool-tool-result-recall). `file_read` and `tool_result_recall` size their own page to fit.

| Tool | Family | What it does | Permission |
|---|---|---|---|
| [`kodegraph_explore`](https://chynj.ca/kaptain/docs/#tool-kodegraph-explore) | Code search | Returns the verbatim source of the symbols that match a question, with their callers and callees, grouped by file. | never asks |
| [`kodegraph_context`](https://chynj.ca/kaptain/docs/#tool-kodegraph-context) | Code search | Returns only the code relevant to a task, within a token budget, ranked by keywords and, when an embedder is available, meaning. | never asks |
| [`kodegraph_search`](https://chynj.ca/kaptain/docs/#tool-kodegraph-search) | Code search | Finds a function, method or class by name or keyword, ranked. | never asks |
| [`kodegraph_node`](https://chynj.ca/kaptain/docs/#tool-kodegraph-node) | Code search | One symbol's file, line and signature, and its source when asked. | never asks |
| [`kodegraph_callers`](https://chynj.ca/kaptain/docs/#tool-kodegraph-callers) | Code search | The symbols that call a given symbol. | never asks |
| [`kodegraph_callees`](https://chynj.ca/kaptain/docs/#tool-kodegraph-callees) | Code search | The symbols a given symbol calls. | never asks |
| [`kodegraph_impact`](https://chynj.ca/kaptain/docs/#tool-kodegraph-impact) | Code search | Everything that calls a symbol, directly or indirectly, level by level. | never asks |
| [`kodegraph_files`](https://chynj.ca/kaptain/docs/#tool-kodegraph-files) | Code search | The indexed files with their language and number of symbols. | never asks |
| [`kodegraph_status`](https://chynj.ca/kaptain/docs/#tool-kodegraph-status) | Code search | Index statistics and freshness, and live progress while an index pass runs. | never asks |
| [`kodegraph_index`](https://chynj.ca/kaptain/docs/#tool-kodegraph-index) | Code search | Builds or refreshes the index. | never asks |
| [`file_read`](https://chynj.ca/kaptain/docs/#tool-file-read) | Files | Reads a text file one page at a time and returns numbered lines. | never inside the project |
| [`file_search`](https://chynj.ca/kaptain/docs/#tool-file-search) | Files | Finds literal text or a pattern in files, using ripgrep, and returns each match with its file and line. | never inside the project |
| [`file_write`](https://chynj.ca/kaptain/docs/#tool-file-write) | Files | Creates, overwrites or appends to a text file, and says what changed. | asks (a change) |
| [`file_edit`](https://chynj.ca/kaptain/docs/#tool-file-edit) | Files | Replaces exact text in a file. | asks (a change) |
| [`patch_apply`](https://chynj.ca/kaptain/docs/#tool-patch-apply) | Files | Applies a unified diff to the project. | asks (a change) |
| [`cli_exec`](https://chynj.ca/kaptain/docs/#tool-cli-exec) | Shell | Runs a shell command in the project folder: `sh` on Linux and macOS, Git Bash (or `cmd.exe`) on Windows. | read-only commands never; others ask |
| [`test_run`](https://chynj.ca/kaptain/docs/#tool-test-run) | Shell | Runs a test command and reports pass or fail with the end of the output. | asks (a change) |
| [`git_op`](https://chynj.ca/kaptain/docs/#tool-git-op) | Shell | Runs one git subcommand in the project. | reads never; others ask |
| [`web_search`](https://chynj.ca/kaptain/docs/#tool-web-search) | Web | Searches the web through DuckDuckGo and returns titles, addresses and snippets. | never asks |
| [`web_fetch`](https://chynj.ca/kaptain/docs/#tool-web-fetch) | Web | Fetches a page and returns its readable text. | never asks |
| [`web_fetch_raw`](https://chynj.ca/kaptain/docs/#tool-web-fetch-raw) | Web | Fetches an address and returns the body as is, such as JSON or HTML. | never asks |
| [`web_extract`](https://chynj.ca/kaptain/docs/#tool-web-extract) | Web | Fetches a page and returns its title, description, OpenGraph data, links and clean text. | never asks |
| [`skill_list`](https://chynj.ca/kaptain/docs/#tool-skill-list) | Skills | Lists the available skills by name, source and description. | never asks |
| [`skill_load`](https://chynj.ca/kaptain/docs/#tool-skill-load) | Skills | Loads one skill's full text into the conversation. | never asks |
| [`remember`](https://chynj.ca/kaptain/docs/#tool-remember) | Memory | Records one short rule the kapsule learned: a `guideline` (what worked) or a `guardrail` (what to avoid). | never asks |
| [`session_recall`](https://chynj.ca/kaptain/docs/#tool-session-recall) | Memory | Searches this conversation's earlier turns, including ones already folded into the summary, and returns the matching messages. | never asks |
| [`tool_result_recall`](https://chynj.ca/kaptain/docs/#tool-tool-result-recall) | Memory | Reads an earlier tool result by its id, a page of lines at a time, or only the lines that contain some text. | never asks |
| [`tool_schema_resolve`](https://chynj.ca/kaptain/docs/#tool-tool-schema-resolve) | Workflow | Returns the full definitions of tools the model was shown only by name. | never asks |
| [`todo`](https://chynj.ca/kaptain/docs/#tool-todo) | Workflow | The model's progress list for multi-step work. | never asks |
| [`time_now`](https://chynj.ca/kaptain/docs/#tool-time-now) | Workflow | The current date and time, with the time zone used and where it came from. | never asks |
| [`ask_user`](https://chynj.ca/kaptain/docs/#tool-ask-user) | Workflow | Asks you one to four multiple-choice questions and waits for the answers. | never asks |
| [`delegate`](https://chynj.ca/kaptain/docs/#tool-delegate) | Delegation | Hands one self-contained task to the [worker model](https://chynj.ca/kaptain/docs/#delegation). | never asks; writing `output_file` asks (a change) |
| [`delegate_batch`](https://chynj.ca/kaptain/docs/#tool-delegate-batch) | Delegation | Runs several delegate briefs in one call; each must name its `output_file`. | asks (a change) |
| [`assemble`](https://chynj.ca/kaptain/docs/#tool-assemble) | Delegation | Fills a template's `{{KEY}}` placeholders from files and writes the result. | asks (a change) |
| [`delegate_status`](https://chynj.ca/kaptain/docs/#tool-delegate-status) | Delegation | Reports the worker model, its size class and the limits of one brief. | never asks |
| [`vision_analyze`](https://chynj.ca/kaptain/docs/#tool-vision-analyze) | Vision | Describes an image with the [vision model](https://chynj.ca/kaptain/docs/#vision): a web address, a project file or a data URL. | never asks |
| [`agent_cards`](https://chynj.ca/kaptain/docs/#tool-agent-cards) | Agents | Splits work into cards that workers run. | never asks |
| `kapsule_create` | Agents | Creates a kapsule from a name, role, task, tools and model ([Edit access](https://chynj.ca/kaptain/docs/#kapsule-edit-access)). | asks (a change) |
| `kapsule_edit` | Agents | Changes a kapsule's fields, or shows it when given only its name; a kapsule never edits itself. | asks (a change) |
| [`agent_<name>`](https://chynj.ca/kaptain/docs/#tool-agent-name) | Agents | Runs another kapsule on a self-contained task, with that kapsule's own model, instructions, tools and permissions. | never asks |

Tools from connected MCP servers are listed under their own names, and every call to them asks in Ask mode unless a kapsule pre-approves the server. `tool_schema_resolve` is not a Krew tool: Kaptain adds it to a turn when some tools are only listed by name ([How tools reach the model](https://chynj.ca/kaptain/docs/#tool-block)). Four more tools exist only when Kaptain is an MCP server for a CLI: `kaptain_models`, `kaptain_chat`, `agent_list` and `invoke_agent` ([MCP](https://chynj.ca/kaptain/docs/#mcp-out)).

When tools are on, a local or cloud model gets a few tools in full and looks the rest up with [`tool_schema_resolve`](https://chynj.ca/kaptain/docs/#tool-tool-schema-resolve) ([How tools reach the model](https://chynj.ca/kaptain/docs/#tool-block)). Claude Code and Codex get their tools from `kaptain mcp` instead.

### Code search tools

#### kodegraph_explore

Returns the verbatim source of the symbols that match a question, with their callers and callees, grouped by file. The main way models explore code.

- **When a model uses it:** to understand code, or before editing it.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `query` | string | yes | A question or symbol names |
| `limit` | integer | no | Most symbols to start from; default 6, at most 12 |

```json
{"query": "greet"}
```

Returns `files`, each with `sections`: the code, its kind, line and relation (match, caller or callee).

#### kodegraph_context

Returns only the code relevant to a task, within a token budget, ranked by keywords and, when an embedder is available, meaning.

- **When a model uses it:** instead of reading whole files when a model needs context.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `query` | string | yes | The task or topic |
| `budget_tokens` | integer | no | Token budget, up to 8000; default 2000 |

```json
{"query": "how is the greeting built", "budget_tokens": 300}
```

Returns `chunks` of code with their files, or a note to try `kodegraph_search` when nothing matched.

#### kodegraph_search

Finds a function, method or class by name or keyword, ranked.

- **When a model uses it:** to locate a definition without reading files. For literal text, models use `file_search`.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `query` | string | yes | A symbol name or keyword |
| `kind` | string | no | `function`, `method` or `class` |
| `limit` | integer | no | Most results; default 20 |

```json
{"query": "greet"}
```

```output
{"count":1,"ok":true,"query":"greet","results":[{"file":"main.go","kind":"function","line":5,"name":"greet","parent":""}]}
```

#### kodegraph_node

One symbol's file, line and signature, and its source when asked.

- **When a model uses it:** to fetch one function's source without reading the whole file.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `symbol` | string | yes | The symbol's name |
| `code` | boolean | no | Include the source; default false |

```json
{"symbol": "greet", "code": true}
```

Returns `matches`, each with file, line, kind and, when asked, `code`.

#### kodegraph_callers

The symbols that call a given symbol.

- **When a model uses it:** before changing a function, to see who depends on it.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `symbol` | string | yes | The symbol's name |
| `limit` | integer | no | Most results; default 20 |

```json
{"symbol": "greet"}
```

Returns `callers`, each with its name, qualified name, kind, file, line, the line of the call (`at_line`), the relation, and how sure the match is (`resolution`, `confidence`), plus `count`, `exact` and `possible`.

#### kodegraph_callees

The symbols a given symbol calls.

- **When a model uses it:** to trace what a function does downstream.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `symbol` | string | yes | The symbol's name |
| `limit` | integer | no | Most results; default 20 |

```json
{"symbol": "main"}
```

Returns `callees`, each with name, file and line.

#### kodegraph_impact

Everything that calls a symbol, directly or indirectly, level by level.

- **When a model uses it:** to judge the reach of a change before a refactor.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `symbol` | string | yes | The symbol's name |
| `depth` | integer | no | Levels to follow; default 3, at most 6 |
| `offset` | integer | no | Skip this many, to page on with `next_offset` |

```json
{"symbol": "greet"}
```

Returns `levels`, each symbol written as `name (file:line)`, with `impacted`, `impacted_nodes`, `exact` and `possible`, and `next_offset` when one answer cannot hold them all.

#### kodegraph_files

The indexed files with their language and number of symbols.

- **When a model uses it:** to get oriented in an unfamiliar project.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `limit` | integer | no | Most files; default 50 |

```json
{}
```

```output
{"count":1,"files":[{"lang":"go","path":"main.go","symbols":2}],"ok":true}
```

#### kodegraph_status

Index statistics and freshness, and live progress while an index pass runs.

- **When a model uses it:** to check the index exists and is current.
- **Permission:** Never asks.

No parameters.

```json
{}
```

Returns `index_status` (`ready`, `building` or `not_built`), `root`, `index_state`, `stale`, `files`, `symbols`, `call_edges`, `vectors` and `store`, and `progress` while a pass runs. Which embedder is in use is not part of it: see **Settings › Model Handling › KodeGraph Embedder**. Every KodeGraph answer also carries `index_state`.

#### kodegraph_index

Builds or refreshes the index. Unchanged files are skipped, and the pass runs in the background unless asked to wait.

- **When a model uses it:** in a new project, or after large changes.
- **Permission:** Never asks. A home folder or a tree of more than 100,000 files is refused unless `confirm` is true.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `confirm` | boolean | no | Index a home folder or a very large tree on purpose |
| `wait` | boolean | no | Wait for the pass to finish; default false |
| `scan` | string | no | `auto` (a quick check first) or `hash` (read every file) |

```json
{"wait": true}
```

```output
{"call_edges":1,"changed_files":1,"deleted_files":0,"files":1,"indexed_at":"2026-10-15T11:48:38-07:00","ok":true,"root":"/home/you/project","store":"sqlite+fts5","symbols":2,"vector_warm":"not_needed","vectors":{"done":0,"total":2}}
```

### File tools

#### file_read

Reads a text file one page at a time and returns numbered lines. Without a `limit`, a page is sized to the model's context window: about 380 lines at a 32K window and about 1,560 at 128K, never fewer than 120. Through `kaptain mcp` that is a 128K window unless `mcp_result_window_tokens` says otherwise, and where no window is known a page is 250 lines. A local or cloud model is told its page size. One call returns at most 2,000 lines or 48,000 characters, and a line longer than 2,000 characters is cut with a note. A page that is not the whole file says so and gives the `offset` to continue from. Binary files are refused; an image is pointed at `vision_analyze`.

- **When a model uses it:** to see the exact text before editing it.
- **Permission:** Never asks inside the project. Outside it: asks in Ask mode, runs in Auto-approve and Full access, refused in Read-only, and runs without asking when a [trusted scope](https://chynj.ca/kaptain/docs/#allowed-paths) covers it.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `path` | string | yes | Relative to the project, or absolute |
| `offset` | integer | no | First line, from 1; default 1 |
| `limit` | integer | no | Lines to return, at most 2000; without it, the page size above |

`start_line` and `end_line` still work in place of `offset` and `limit`.

```json
{"path": "main.go", "offset": 1, "limit": 5}
```

```output
{"content":"1\tpackage main\n2\t\n3\timport \"fmt\"\n4\t\n5\tfunc greet(name string) string { return \"hello \" + name }","file_bytes":131,"hint":"showing lines 1–5 of 7 (you asked for 5 lines) — NOT the whole file: use offset=6 to continue","next_offset":6,"ok":true,"path":"main.go","shown_lines":[1,5],"total_lines":7,"truncated_by":"limit"}
```

#### file_search

Finds literal text or a pattern in files, using ripgrep (or a built-in search when ripgrep is not installed), and returns each match with its file and line.

- **When a model uses it:** to find the exact place to edit.
- **Permission:** Never asks inside the project. Outside it: asks in Ask mode, runs in Auto-approve and Full access, refused in Read-only, and runs without asking when a [trusted scope](https://chynj.ca/kaptain/docs/#allowed-paths) covers it.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `query` | string | yes | Text or a regular expression |
| `path` | string | no | A folder to search; default the project |
| `glob` | string | no | A file-name pattern such as `*.go` |
| `is_regex` | boolean | no | Treat the query as a regular expression |
| `context_lines` | integer | no | Lines around each match, up to 20 |

```json
{"query": "greet", "context_lines": 1}
```

Returns `count` and `matches` as `path:line:` text. A search stops at 20,000 matches (`file_search_max_matches`); a long list is saved and read by id.

#### file_write

Creates, overwrites or appends to a text file, and returns the diff.

- **When a model uses it:** for new files or full rewrites.
- **Permission:** A change. Asks in Ask mode, refused in Read-only, runs in Auto-approve and Full access. Outside the project it is refused in every mode unless the folder is one a kapsule may change. A kapsule writes only in its workspace and the [folders you listed for it](https://chynj.ca/kaptain/docs/#kapsule-edit-access) (external paths and `rw` trusted scopes), under its approval mode; anywhere else, the project folder included, is refused (`path_not_allowed`), and its own definition never.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `path` | string | yes | Relative to the project |
| `content` | string | yes | The full content, or the text to append |
| `mode` | string | no | `overwrite` (default), `append` or `create` |

```json
{"path": "notes.md", "content": "# Notes\n"}
```

The model gets a line saying what changed and the diff, cut at 20 lines with an id that fetches the rest through `tool_result_recall`; the full diff stays on the card. Writing exactly what the file already holds says nothing was written.

#### file_edit

Replaces exact text in a file. The text must match exactly and be unique unless `replace_all` is set. `edits` makes several replacements in one call, all or nothing, under one approval. A model may name the file inside each edit instead of once at the top; edits naming two different files are refused, one file per call. If the file changed on disk since the model read it, an edit whose text still matches exactly is applied to the current file and the result says the file had changed; a loose or missing match is refused with a request to re-read.

- **When a model uses it:** for targeted changes after reading the file.
- **Permission:** A change. Asks in Ask mode, refused in Read-only, runs in Auto-approve and Full access. Outside the project it is refused in every mode unless the folder is one a kapsule may change. A kapsule writes only in its workspace and the [folders you listed for it](https://chynj.ca/kaptain/docs/#kapsule-edit-access) (external paths and `rw` trusted scopes), under its approval mode; anywhere else, the project folder included, is refused (`path_not_allowed`), and its own definition never.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `path` | string | yes | Relative to the project |
| `old_string` | string | see below | The exact text to replace |
| `new_string` | string | see below | The replacement |
| `replace_all` | boolean | no | Replace every occurrence |
| `edits` | array | see below | `[{old_string, new_string, replace_all}]` for several edits; each may also carry `path` |

```json
{"path": "main.go", "old_string": "hello ", "new_string": "hi "}
```

The model gets one line saying what changed, such as "Applied to main.go: lines 2–8, +1 −1" (the changed lines with 3 lines of context around them), and the diff, cut at 20 lines with an id that fetches the rest through `tool_result_recall`. An edit that changes nothing says the file is unchanged. Give either `old_string` with `new_string`, or `edits`.

#### patch_apply

Applies a unified diff to the project.

- **When a model uses it:** for a change across several files expressed as one diff.
- **Permission:** A change. Asks in Ask mode, refused in Read-only, runs in Auto-approve and Full access. Outside the project it is refused in every mode unless the folder is one a kapsule may change. A kapsule writes only in its workspace and the [folders you listed for it](https://chynj.ca/kaptain/docs/#kapsule-edit-access) (external paths and `rw` trusted scopes), under its approval mode; anywhere else, the project folder included, is refused (`path_not_allowed`), and its own definition never.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `patch` | string | yes | The unified diff |

```json
{"patch": "--- a/main.go\n+++ b/main.go\n@@ …"}
```

Returns `ok`, `applied`, the `diff` and the tool output.

### Shell tools

#### cli_exec

Runs a shell command in the project folder: `sh` on Linux and macOS, Git Bash (or `cmd.exe`) on Windows. See also [Long commands and background jobs](https://chynj.ca/kaptain/docs/#jobs).

For a local or cloud model in Kaptain, a command still running at its time limit is not stopped: it continues in the background as a job, the model gets the output so far and a `job_id`, and a strip above the chat box shows it with a **Stop** button. `background: true` starts a server or watcher that way from the start. A job ends when it finishes, when you or the model stop it, when its chat is deleted or when Kaptain stops; a command that outran its limit is also stopped after `shell_job_max_minutes` in `kaptain.json` (default 60). Through `kaptain mcp`, a command is stopped at its limit.

- **When a model uses it:** to build, inspect the system, or run tools that have no dedicated Krew tool.
- **Permission:** Read-only commands never ask: `ls`, `cat`, `head`, `grep`, `rg`, `find`, `wc`, `diff`, `git status`, `git log`, `git diff` and similar, alone or piped, without redirection, substitution or background jobs. Everything else is a change: it asks in Ask mode, is refused in Read-only, and runs in Auto-approve and Full access. Every `sudo`, also one inside a program the command starts, shows a pop-up where you allow it and type your password, whichever model runs it; with **Settings › Sudo requests** off, sudo commands are not run, and Read-only runs none. There is no `sudo` on Windows. `shell_allow_project_tests` adds `pytest`, `go build`, `go vet`, `go test` and `npm test` to the read-only list. Reading or stopping a job never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `command` | string | yes, unless `job_id` | The command |
| `timeout` | integer | no | Seconds; default 30, at most 300 |
| `working_dir` | string | no | A folder inside the project; for a kapsule, its workspace by default or a folder it may change ([Edit access](https://chynj.ca/kaptain/docs/#kapsule-edit-access)) |
| `background` | boolean | no | Start the command as a background job and return at once |
| `job_id` | string | no | Act on a background job: without `wait` or `signal`, return its new output |
| `wait` | integer | no | With `job_id`: seconds to wait for it to finish, at most 300 |
| `signal` | string | no | With `job_id`: `TERM` stops it |

```json
{"command": "ls -la"}
```

```output
{"auto_run_reason":"read-only allowlist","command":"ls -la","exit_code":0,"gated":false,"ok":true,"read_only":true,"risk":"safe","stderr":"","stdout":"total 16\n…"}
```

A command that became a job returns `job_id`, `state` ("running"), `running_for` and the output so far. Reading a job returns its `state`, new output and, once it ended, `exit_code` and the `reason`.

#### test_run

Runs a test command and reports pass or fail with the end of the output.

- **When a model uses it:** to check a change.
- **Permission:** Always a change: asks in Ask mode, even for a safe command; refused in Read-only.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `command` | string | yes | The test command, such as `go test ./...` |
| `timeout` | integer | no | Seconds; default 300, at most 1800 |

```json
{"command": "go test ./..."}
```

Returns `ok`, `passed`, `exit_code` and the output.

#### git_op

Runs one git subcommand in the project.

- **When a model uses it:** to check status or diffs, or to commit when you ask.
- **Permission:** Reading commands never ask: `status`, `diff`, `log`, `show`, `rev-parse`, `ls-files`, `blame`, `shortlog`, `describe`, and listing `branch` or `remote`. Everything else, and `config`, is a change.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `op` | string | yes | The subcommand, such as `status` |
| `args` | string | no | Further arguments |

```json
{"op": "status"}
```

Returns `ok`, `exit_code` and the output.

### Web tools

#### web_search

Searches the web through DuckDuckGo and returns titles, addresses and snippets.

- **When a model uses it:** for anything recent or outside the model's training.
- **Permission:** Never asks. A kapsule's `host:` trusted scopes do not limit searching; they limit the tools that fetch an address.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `query` | string | yes | The search |
| `max_results` | integer | no | Default 5, at most 20 |

```json
{"query": "go 1.25 release notes"}
```

Returns `engine`, `count` and `results`, each with title, url and snippet.

#### web_fetch

Fetches a page and returns its readable text. Page text is marked as untrusted content. A page body is read up to 8 MB (`web_fetch_max_mb`), and a long text is saved and read by id.

- **When a model uses it:** to read a page found by search.
- **Permission:** Never asks. If a kapsule lists any `host:` trusted scope, it may fetch only those hosts.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `url` | string | yes | An http or https address |

```json
{"url": "https://go.dev/doc/"}
```

Returns `status`, `title` and `text`.

#### web_fetch_raw

Fetches an address and returns the body as is, such as JSON or HTML. The body is marked as untrusted content; a long body is saved and read by id.

- **When a model uses it:** for APIs and JSON endpoints.
- **Permission:** Never asks. If a kapsule lists any `host:` trusted scope, it may fetch only those hosts.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `url` | string | yes | An http or https address |

```json
{"url": "https://api.github.com/repos/golang/go"}
```

Returns `status` and `body`.

#### web_extract

Fetches a page and returns its title, description, OpenGraph data, links and clean text.

- **When a model uses it:** to summarize a page with its metadata.
- **Permission:** Never asks. If a kapsule lists any `host:` trusted scope, it may fetch only those hosts.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `url` | string | yes | An http or https address |
| `max_chars` | integer | no | Cut the text at this many characters; by default the whole text |

```json
{"url": "https://example.com"}
```

Returns `title`, `description`, `opengraph`, `links` and `text`.

### Skill tools

#### skill_list

Lists the available skills by name, source and description.

- **When a model uses it:** at the start of a task, to find a relevant runbook.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `filter` | string | no | A keyword |

```json
{}
```

```output
{"count":1,"skills":[{"description":"Draft release notes from a git log range.","name":"release-notes","source":"global"}]}
```

#### skill_load

Loads one skill's full text into the conversation.

- **When a model uses it:** when a listed skill fits the task.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `name` | string | yes | The skill's name |

```json
{"name": "release-notes"}
```

Returns `name`, `source` and `content`, or the available names when not found.

### Memory tools

#### remember

Records one short rule the kapsule learned: a `guideline` (what worked) or a `guardrail` (what to avoid). It is kept only if the run finishes cleanly, then given to later runs. Up to 64 lessons of 240 characters each.

- **When a model uses it:** inside a kapsule run, when a reusable rule emerges. Outside a kapsule it is unavailable.
- **Permission:** Never asks; it writes only the kapsule's own lesson store.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `text` | string | yes | The rule in one sentence, at most 240 characters |
| `kind` | string | no | `guideline` (default) or `guardrail` |

```json
{"text": "Always call time_now before dating a digest"}
```

Returns `ok` and a note that the lesson is pending until the run finishes cleanly.

#### session_recall

Searches this conversation's earlier turns, including ones already folded into the summary, and returns the matching messages. Each message is cut at 2,000 characters. It works in Kaptain's own chats; through `kaptain mcp` it has no conversation to search and says so.

- **When a model uses it:** when a detail from earlier is no longer in view.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `query` | string | yes | What to look for |
| `limit` | integer | no | Most messages; default 6 |

```json
{"query": "deploy target"}
```

Returns `found`, `count` and `messages`.

#### tool_result_recall

Fetches an earlier tool result by its id, from this turn or an earlier one: a page of lines, one item of a list, or only the lines that contain some text. Every result carries its id in square brackets, such as `[12345678-r03-c01]`, and the model sees it on the result and in the record each reply keeps of its tool calls. A result too big for the model is saved whole, and this tool reads it: a JSON result one field per line, a list result by item. Through `kaptain mcp` it reads the results that were too big to send.

- **When a model uses it:** to finish reading a result that did not fit, or to look at an earlier turn's result again instead of running the tool again.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `id` | string | yes | The result's id |
| `offset` | integer | no | First line, from 1; default 1 |
| `limit` | integer | no | Lines; default 200, at most 1000 |
| `search` | string | no | Return only the lines that contain this text, up to 60 (`query` also works) |
| `item` | integer | no | For a list result: the item to return, from 1 |
| `char_offset` | integer | no | Continue inside a long line or item |

```json
{"id": "12345678-r03-c01", "offset": 201}
```

Returns `found`, `tool`, `total_lines`, `shown_lines` and the numbered `content`, at most 24,000 characters per call, with `next_offset` while lines are left.

### Workflow tools

#### todo

The model's progress list for multi-step work. Finished items drop out of the prompt.

- **When a model uses it:** on any task with three or more steps.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `todos` | array | no | `[{id, title, status}]`; status is `pending`, `in_progress`, `completed` or `cancelled`. Omit to read the list. |
| `merge` | boolean | no | Update only the listed ids instead of replacing the list |

```json
{"todos": [{"id": "1", "title": "read main.go", "status": "in_progress"}]}
```

Returns the `action`, the `todos` and counts by status.

#### time_now

The current date and time, with the time zone used and where it came from.

- **When a model uses it:** before anything where today or latest matters.
- **Permission:** Never asks.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `timezone` | string | no | An IANA zone; default the kapsule's zone, else this machine's |

```json
{"timezone": "America/Toronto"}
```

```output
{"date":"2026-10-15","iso":"2026-10-15T14:51:35-04:00","ok":true,"time":"14:51:35","timezone":"America/Toronto","timezone_abbrev":"EDT","timezone_source":"requested","utc":"2026-10-15T18:51:35Z","weekday":"Thursday",…}
```

#### ask_user

Asks you one to four multiple-choice questions and waits for the answers.

- **When a model uses it:** at a real fork the model cannot settle alone: a missing requirement, an unclear target, or a choice between safe and destructive.
- **Permission:** Never asks for permission; it is a question.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `questions` | array | yes | 1 to 4 items of `{question, header, multi_select, options: [{label, description}]}`, with 2 to 4 options each |

```json
{"questions": [{"header": "Target", "question": "Deploy to staging or prod?", "options": [{"label": "staging"}, {"label": "prod"}]}]}
```

Returns `answered` and the `answers`. Unanswered, the model is told to choose the most reasonable option itself.

#### tool_schema_resolve

Returns the full definitions of tools the model was shown only by name, under "Other tools available", so it can call them. Kaptain adds it for local and cloud models whenever some tools are listed by name only ([how tools reach a model](https://chynj.ca/kaptain/docs/#tools-reference)). It answers only for tools the model may use. A model may also call a listed tool directly: right arguments run it, wrong ones bring back its definition and what was wrong.

- **When a model uses it:** before the first call to a tool it was shown only by name.
- **Permission:** Never asks; it runs nothing.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `names` | array | yes | Tool names from the list |

```json
{"names": ["git_op", "web_fetch"]}
```

Returns `schemas` and `unknown`, the names that are not tools the model can use here.

### Delegation tools

#### delegate

Hands one self-contained task to the [worker model](https://chynj.ca/kaptain/docs/#delegation). Without `tools`, the result passes a quality check. With `output_file`, the result goes to that file and only stats and an excerpt come back. With `tools`, the worker gets its own small toolbelt; it can never delegate again or ask you.

- **When a model uses it:** for bulk mechanical work: reading many files, extraction, first drafts.
- **Permission:** Never asks for the call itself. Writing `output_file` is a change, as with `file_write`: it asks in Ask mode and is refused in Read-only, before any model runs. A worker given `tools` asks for its own changes the same way. Offered only when **Delegate** is on.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `task` | string | yes | A complete, standalone brief; numbered steps work best |
| `context` | string | no | Small inline context |
| `context_files` | array | no | Project files to put in the brief |
| `output_file` | string | no | Where to write the result |
| `tools` | array | no | The worker's tools, such as `["file_read", "file_search"]` |

```json
{"task": "1. Read README.md 2. List every command-line flag", "context_files": ["README.md"], "output_file": "notes/flags.md"}
```

With `output_file`, returns `written`, the `quality` result and an `excerpt`; the file is written even when the quality check fails, with a `warning`. Without it, returns the `response` and the `quality` result. With `tools`, it returns the worker's `answer` and, with `output_file`, `output_written`: true only if the file changed during the run, with a `warning` when it did not. A worker that is a Claude or Codex CLI on another machine adds `runs_on`, and its changes take place on that machine.

#### delegate_batch

Runs several delegate briefs in one call; each must name its `output_file`.

- **When a model uses it:** for independent mechanical tasks at once.
- **Permission:** Writing its output files is a change: asks in Ask mode, refused in Read-only. Offered only when **Delegate** is on.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `items` | array | yes | `[{task, output_file, context, context_files}]` |

```json
{"items": [{"task": "Summarize a.go", "output_file": "out/a.md", "context_files": ["a.go"]}]}
```

Returns `succeeded`, `total` and `items`, one result per item.

#### assemble

Fills a template's `{{KEY}}` placeholders from files and writes the result. No model is called.

- **When a model uses it:** after `delegate_batch`, to stitch the pieces together.
- **Permission:** Writing its output file is a change: asks in Ask mode, refused in Read-only. Offered only when **Delegate** is on.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `template_file` | string | yes | The template |
| `output_file` | string | yes | Where to write the result |
| `replacements` | object | yes | Each KEY and the file that fills it |

```json
{"template_file": "tpl/report.md", "output_file": "report.md", "replacements": {"A": "out/a.md"}}
```

Returns `ok` and the file written.

#### delegate_status

Reports the worker model, its size class and the limits of one brief.

- **When a model uses it:** before sizing a delegate brief.
- **Permission:** Never asks. Offered only when **Delegate** is on.

No parameters.

```json
{}
```

```output
{"model":"qwen3.5:4b","ok":true,"profile":"qwen3.5:4b (unknown size, tier small) — granularity: one component, one page section, or one small file per call; per call ≤ ~4372 prompt tokens, output budget 3000, ctx 8192","root":"/home/you/project","surface":"krew (native)"}
```

### The vision tool

#### vision_analyze

Describes an image with the [vision model](https://chynj.ca/kaptain/docs/#vision): a web address, a project file or a data URL. Images larger than 2,000 pixels or 5 MB are scaled down; one that cannot be brought under 5 MB is refused.

- **When a model uses it:** on screenshots, diagrams and photos the chat model cannot see itself.
- **Permission:** Never asks. A local file must be inside the project or a chat attachment; any other path is refused.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `url` | string | yes | The image |
| `prompt` | string | no | What to look for |
| `max_tokens` | integer | no | Answer budget; default from Settings (1,000) |

```json
{"url": "docs/screenshot.png", "prompt": "What error is shown?"}
```

Returns the `analysis` and the model that produced it.

### Agent tools

#### agent_cards

Splits work into cards that workers run. Cards without parents run in parallel; a card with parents starts when they finish and receives their results. Cards are matched with the kapsule's proven workers.

- **When a model uses it:** in a kapsule with **Can bring in workers** on, when a job splits cleanly.
- **Permission:** The call never asks. Workers never get more tools than the kapsule, and run unattended: by default they cannot make changes and report what they could not do.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `action` | string | yes | `propose`, `add_card`, `ready`, `complete`, `library` or `library_delete` |
| `cards` | array | for propose | `[{title, body, role, tools, persona, parents}]` |
| `title, body, role, persona, tools` | string | for add_card | One card; `tools` is a comma list, or `none` |
| `card_id, success, result, evidence` | various | for complete | Which card, whether it verifiably succeeded, and the evidence |
| `id` | string | for library_delete | The library worker to delete |
| `limit` | integer | no | library: most rows; default 50 |

```json
{"action": "library"}
```

```output
{"agents":[],"ok":true}
```

#### agent_<name>

Runs another kapsule on a self-contained task, with that kapsule's own model, instructions, tools and permissions. It cannot see your conversation.

- **When a model uses it:** when a kapsule is allowed to call another ([agents calling agents](https://chynj.ca/kaptain/docs/#agents-talking)).
- **Permission:** No prompt; the calling kapsule's delegation settings decide, three levels deep at most.

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `task` | string | yes | A complete, standalone task |

```json
{"task": "Find three sources on X"}
```

Returns the other kapsule's result.

## CLI reference

Every `kaptain` command in 0.0.9. Running `kaptain` with no command, or `kaptain --help`, prints the main list; `kaptain <command> --help` prints that command's line, or its own usage for `update`, `nodes`, `channels` and `kodegraph`; run `kaptain skill` with no arguments for its usage. Those five commands work but are not in the main list yet.

| Command | What it does |
|---|---|
| [`kaptain start`](https://chynj.ca/kaptain/docs/#cli-start) | Starts Kaptain in the background in its own session, waits up to 30 seconds for the interface, prints where it is and opens your browser. |
| [`kaptain stop`](https://chynj.ca/kaptain/docs/#cli-stop) | Stops the running Kaptain and the model servers it started. |
| [`kaptain status`](https://chynj.ca/kaptain/docs/#cli-status) | Says whether Kaptain is running and where, and where its access code is saved. |
| [`kaptain access-code rotate`](https://chynj.ca/kaptain/docs/#cli-access-code) | Makes a new access code for this computer; the old one stops at once. |
| [`kaptain restart`](https://chynj.ca/kaptain/docs/#cli-restart) | Restarts the running Kaptain onto this binary; `--if-idle` waits for no turn to be running. |
| [`kaptain install-state`](https://chynj.ca/kaptain/docs/#cli-install-state) | One line of JSON for installers: version, data folder, whether it is set up, the device, and what is running. |
| [`kaptain serve`](https://chynj.ca/kaptain/docs/#cli-serve) | Runs Kaptain in the foreground, logging to the terminal, until you press Ctrl+C. |
| [`kaptain setup`](https://chynj.ca/kaptain/docs/#cli-setup) | The setup wizard in the terminal. |
| [`kaptain version`](https://chynj.ca/kaptain/docs/#cli-version) | Prints the version and whether the Claude helper is built in. |
| [`kaptain sidecar check`](https://chynj.ca/kaptain/docs/#cli-sidecar) | Unpacks the built-in Claude helper and checks that it runs on this machine. |
| [`kaptain update`](https://chynj.ca/kaptain/docs/#cli-update) | Downloads, verifies and installs the published build; restart to run it. |
| [`kaptain uninstall`](https://chynj.ca/kaptain/docs/#cli-uninstall) | Shows what would be removed; `--yes` removes it. |
| [`kaptain migrate`](https://chynj.ca/kaptain/docs/#cli-migrate) | Brings `kaptain.json` up to the current settings format and prints the report. |
| [`kaptain doctor`](https://chynj.ca/kaptain/docs/#cli-doctor) | Checks the GPU, llama-server, Ollama, the CLIs, GGUF files and the shell. |
| [`kaptain models`](https://chynj.ca/kaptain/docs/#cli-models) | Lists every model Kaptain can reach: CLIs, cloud models, GGUF files, Ollama models. |
| [`kaptain chat`](https://chynj.ca/kaptain/docs/#cli-chat) | A chat in the terminal with any model, in the current folder. |
| [`kaptain delegate "<task>"`](https://chynj.ca/kaptain/docs/#cli-delegate) | A simple terminal flow: one model plans two to four subtasks, runs each, then combines the results. |
| [`kaptain spawn`](https://chynj.ca/kaptain/docs/#cli-spawn) | `spawn ollama` starts Ollama if it is installed and not running. |
| [`kaptain usage`](https://chynj.ca/kaptain/docs/#cli-usage-ref) | Token totals from the Claude Code and Codex session records on this machine. |
| [`kaptain agent`](https://chynj.ca/kaptain/docs/#cli-agent-ref) | Lists and drives kapsule agents. |
| [`kaptain skill`](https://chynj.ca/kaptain/docs/#cli-skill) | Lists skills, or installs them from a folder, `.zip`, git URL or `owner/repo`. |
| [`kaptain mcp`](https://chynj.ca/kaptain/docs/#cli-mcp) | Runs Kaptain's toolbelt as an MCP server named `kaptain-engine` over stdio. |
| [`kaptain mcp`](https://chynj.ca/kaptain/docs/#cli-mcp-servers) | Manages the MCP servers you connect to Kaptain. |
| [`kaptain mcp`](https://chynj.ca/kaptain/docs/#cli-mcp-register) | Adds Kaptain's tools to your own CLI's configuration, removes them, or checks. |
| [`kaptain mcp health`](https://chynj.ca/kaptain/docs/#cli-mcp-health) | Self-tests of this binary's MCP server. |
| [`kaptain kodegraph`](https://chynj.ca/kaptain/docs/#cli-kodegraph) | The code graph from a terminal; `kaptain kg` for short. |
| [`kaptain remote`](https://chynj.ca/kaptain/docs/#cli-remote-ref) | Shows or changes remote access over your tailnet, with readiness checks. |
| [`kaptain nodes`](https://chynj.ca/kaptain/docs/#cli-nodes-ref) | Sharing models between your Kaptains from a terminal. |
| [`kaptain device`](https://chynj.ca/kaptain/docs/#cli-device) | `register` binds this machine to your account through an approval in the account portal and keeps its access code. |
| [`kaptain license`](https://chynj.ca/kaptain/docs/#cli-license) | `status` shows the entitlement from local files. |
| [`kaptain account`](https://chynj.ca/kaptain/docs/#cli-account) | `status` shows the signed-in account and this device. |
| [`kaptain billing open`](https://chynj.ca/kaptain/docs/#cli-billing) | Opens billing in the account portal. |
| [`kaptain channels`](https://chynj.ca/kaptain/docs/#cli-channels) | Connects Kaptain to Telegram, Signal, Discord or Slack and manages who may talk to it. |
| [`kaptain engine`](https://chynj.ca/kaptain/docs/#cli-engine) | Runs Kaptain's tool engine on its own, for development. |

Every command runs against the data folder in `KAPTAIN_DATA_DIR`, or the default for your system, and the port in `KAPTAIN_PORT` or `8810`. Use the same values for `start`, `status` and `stop`.

### Run Kaptain

#### kaptain start

```text
kaptain start
```

Starts Kaptain in the background in its own session, waits up to 30 seconds for the interface, prints where it is and opens your browser. Each start begins a fresh `kaptain.log`. Prints `kaptain already running (pid N)` and the address when its pid file names a live process or anything already listens on its port.

```output
kaptain started (pid 3150395)
  UI:    http://127.0.0.1:8810
  bind:  127.0.0.1:8810
  logs:  /home/you/.local/share/kaptain/kaptain.log
  stop:  kaptain stop
```

Details and output: [Start Kaptain](https://chynj.ca/kaptain/docs/#start).

#### kaptain stop

```text
kaptain stop
```

Stops the running Kaptain and the model servers it started. It finds Kaptain by its pid file. Without one, it stops whatever program is listening on Kaptain's port, even one that is not Kaptain, so do not run another program on 8810.

```output
kaptain stopped (pid 3150395)
```

#### kaptain status

```text
kaptain status
```

Says whether Kaptain is running and where.

```output
kaptain: running (pid 3150395) → http://127.0.0.1:8810
access code: saved in /home/you/.local/share/kaptain/access-code.txt
```

The second line says where the access code is: `access-code.txt` while that file exists, then `the api_token in …/kaptain.json`, or `none yet — run kaptain setup` before setup. When Kaptain refuses the code (see below), it says `access code: REFUSED —` and the reason.

#### kaptain access-code rotate

```text
kaptain access-code rotate
```

Makes a new access code for this computer, prints it once, saves it to `kaptain.json` and `access-code.txt`, and ends every browser session. A running Kaptain uses it from its next request; no restart. It is also the way back when Kaptain refuses a code it did not make. Output and details: [Get a new access code](https://chynj.ca/kaptain/docs/#access-code-new).

#### kaptain restart

```text
kaptain restart [--if-idle] [--wait SECONDS]
```

Restarts the running Kaptain onto this binary, for example after [`kaptain update`](https://chynj.ca/kaptain/docs/#update-kaptain). The installer runs it with `--if-idle` after an update.

| Flag | Meaning |
|---|---|
| `--if-idle` | Only when no turn is running. A busy Kaptain is left as it is, with exit code 3 and the line below. |
| `--wait SECONDS` | Wait that long for the restarted Kaptain to answer, then print where it runs |

```output
Kaptain (pid 4121449, <version>) is restarting onto <version>.
```

When a turn is running and you gave `--if-idle`, it says "Kaptain is busy (1 turn(s) running) — the new version starts at its next restart: `kaptain restart`." When nothing runs: "Kaptain is not running — start it with `kaptain start`."

#### kaptain install-state

```text
kaptain install-state --json
```

What an installer needs to know about this machine, as one line of JSON. Reads only.

```output
{"version":"<version>","data_dir":"/home/you/.local/share/kaptain","config":"present","set_up":true,"set_up_at":"2026-10-28","device":"none","running":{"pid":4121449,"url":"http://127.0.0.1:8810","version":"<version>"}}
```

#### kaptain serve

```text
kaptain serve [--root DIR] [--data DIR]
```

Runs Kaptain in the foreground, logging to the terminal, until you press Ctrl+C. Use it under a service manager or to watch the log. Writes no pid file.

| Flag | Meaning |
|---|---|
| `--root DIR` | The project folder for this run, when none is set in Settings |
| `--data DIR` | The data folder for this run, like `KAPTAIN_DATA_DIR` |

#### kaptain setup

```text
kaptain setup [--force]
```

The setup wizard in the terminal. Stop Kaptain first. Creating an account here first asks you to agree to the Terms of Service and Privacy Policy (`[y/N]`); without a yes, no account is created and setup stops. On a machine that is already set up it changes nothing and says so.

| Flag | Meaning |
|---|---|
| `--force` | Goes through the wizard again on a machine that is already set up, starting from the choices on record. The access code, device and licence stay. |

Details and output: [Set up from the terminal](https://chynj.ca/kaptain/docs/#setup-terminal).

#### kaptain version

```text
kaptain version [--json]
```

Prints the version and whether the Claude helper is built in. `--json` adds whether this binary carries CHYNJ's signing keys, with their fingerprints, and the helper's size. `kaptain --version` and `-v` work too.

| Flag | Meaning |
|---|---|
| `--json` | Machine-readable output |

```output
kaptain <version>
claude sidecar: embedded (linux-amd64, <size> MB)
```

#### kaptain sidecar check

```text
kaptain sidecar check [--json] [--timeout 90s]
```

Kaptain runs Claude through a small helper built into the binary, unpacked to your cache folder the first time a Claude turn runs. This command unpacks it the same way and runs its offline self-check, so you can tell before a chat whether Claude turns can start on this machine. Exit code 0 means it ran and answered; 1 names the stage that failed, in the system's own words.

| Flag | Meaning |
|---|---|
| `--json` | The result as one JSON object |
| `--timeout` | How long the helper may take to start and answer; default 90s |

```output
claude sidecar check — linux-amd64
  embedded    yes (<bytes> bytes)
  extracted   <cache folder>/… (<mode>)
  answered    <platform>/<arch>, <runtime> (<ms> ms)
OK — the embedded Claude sidecar runs on this machine.
```

A build without the helper fails at the first stage:

```output
claude sidecar check — linux-amd64
  embedded    no
kaptain sidecar check FAILED at embed: this build carries no embedded Claude sidecar for linux-amd64 — a plain `go build` has none; build.sh and the candidate build embed it
```

#### kaptain update

```text
kaptain update [--check] [--force] [--json]
```

Downloads, verifies and installs the published build; restart to run it.

| Flag | Meaning |
|---|---|
| `--check` | Report only; install nothing |
| `--force` | Reinstall even if the version matches |
| `--json` | Machine-readable output |

Details and output: [Update](https://chynj.ca/kaptain/docs/#update-kaptain).

#### kaptain uninstall

```text
kaptain uninstall [--yes]
```

Shows what would be removed; `--yes` removes it.

| Flag | Meaning |
|---|---|
| `--yes` | Perform the removal |
| `--identity-only` | Remove only licence and device identity |
| `--keep-access-code` | Save the access code to `~/kaptain-access-code.txt` first |
| `--keep-runtimes` | Keep downloaded runtimes |
| `--fingerprint` | Print this machine's fingerprint hash and change nothing |
| `--json` | Machine-readable report |

Details and output: [Uninstall](https://chynj.ca/kaptain/docs/#uninstall).

#### kaptain migrate

```text
kaptain migrate
```

Brings `kaptain.json` up to the current settings format and prints the report. Most commands do this by themselves before running (not `version`, `help`, `install-state` or `sidecar check`); while Kaptain is running they leave it for Kaptain's next start. A backup goes to `backups/` first.

```output
{"changed":false,"from_schema":1,"to_schema":1,"app_version":"<version>"}
```

#### kaptain doctor

```text
kaptain doctor [--json]
```

Checks the GPU, llama-server, Ollama, the CLIs, GGUF files and the shell. Reads only.

| Flag | Meaning |
|---|---|
| `--json` | Machine-readable output |

Details and output: [See your models from the terminal](https://chynj.ca/kaptain/docs/#models-cli).

### Models and chat

#### kaptain models

```text
kaptain models
```

Lists every model Kaptain can reach: CLIs, cloud models, GGUF files, Ollama models.

Details and output: [See your models from the terminal](https://chynj.ca/kaptain/docs/#models-cli).

#### kaptain chat

```text
kaptain chat [model] [--tools]
```

A chat in the terminal with any model, in the current folder. Without a model it uses `KAPTAIN_MODEL`, the model chosen in Kaptain, the delegation worker, then a model that can chat on this machine (GGUF or Ollama), then an installed CLI or a cloud model that can chat. Type your message at the `›` prompt; Ctrl+D quits.

| Flag | Meaning |
|---|---|
| `--tools` | Gives the model Krew tools. In the terminal they run without asking, like a trusted command-line tool, so use it only in a folder you trust. |

```output
Kaptain's log: /home/you/.local/share/kaptain/kaptain.log
loading model… ready
kaptain chat — qwen3:8b · tools   (Ctrl-D to quit)

›
```

#### kaptain delegate "<task>"

```text
kaptain delegate "<task>"
```

A simple terminal flow: one model plans two to four subtasks, runs each, then combines the results. It uses `KAPTAIN_MODEL`, the model chosen in Kaptain, the delegation worker, or an Ollama model on this machine that can chat, in that order, through Ollama (or the address in `KAPTAIN_MODEL_URL`); a model on another runtime is passed over. With none it stops with `no chat-capable model for kaptain delegate: … — pick a model in Settings`.

#### kaptain spawn

```text
kaptain spawn ollama | <model.gguf> [port]
```

`spawn ollama` starts Ollama if it is installed and not running. `spawn <model.gguf>` starts a llama-server for that file, on port 8080 unless you give one.

```output
ollama is serving
```

#### kaptain usage

```text
kaptain usage [--json | --watch]
```

Token totals from the Claude Code and Codex session records on this machine.

| Flag | Meaning |
|---|---|
| `--json` | Every session as JSON |
| `--watch` | Stream updates |

Details and output: [Token usage from the terminal](https://chynj.ca/kaptain/docs/#cli-usage).

### Agents and skills

#### kaptain agent

```text
kaptain agent <list | run | chat | history | enable | disable | set-model>
```

Lists and drives kapsule agents.

Details and output: [Kapsules from the terminal](https://chynj.ca/kaptain/docs/#cli-agent).

#### kaptain skill

```text
kaptain skill <list | add>
```

Lists skills, or installs them from a folder, `.zip`, git URL or `owner/repo`. `kaptain skills` works too.

| Flag | Meaning |
|---|---|
| `list --harness <cli>` | Also show that CLI's own skills; `<cli>` is `claude` or `codex` |
| `add … --replace` | Overwrite a skill with the same name |

Details and output: [Add a skill](https://chynj.ca/kaptain/docs/#skill-add).

### Tools and MCP

#### kaptain mcp

```text
kaptain mcp
```

Runs Kaptain's toolbelt as an MCP server named `kaptain-engine` over stdio. This is what CLIs start; you rarely run it yourself.

Details and output: [Kaptain as an MCP server](https://chynj.ca/kaptain/docs/#mcp-out).

#### kaptain mcp

```text
kaptain mcp <add | add-json | list | enable | disable | remove>
```

Manages the MCP servers you connect to Kaptain.

Details and output: [Connect a server](https://chynj.ca/kaptain/docs/#mcp-add).

#### kaptain mcp

```text
kaptain mcp <register | unregister | install-status> <claude | codex | gemini>
```

Adds Kaptain's tools to your own CLI's configuration, removes them, or checks. Prints JSON.

Details and output: [Kaptain as an MCP server](https://chynj.ca/kaptain/docs/#mcp-out).

#### kaptain mcp health

```text
kaptain mcp health · kaptain mcp smoke [--delegate]
```

Self-tests of this binary's MCP server. `health` exits non-zero when unhealthy.

| Flag | Meaning |
|---|---|
| `--delegate` | Also test the delegation path |

Details and output: [Kaptain as an MCP server](https://chynj.ca/kaptain/docs/#mcp-out).

#### kaptain kodegraph

```text
kaptain kodegraph <index | status | search | explore | node | callers | callees | impact | context | ensure-embedder>
```

The code graph from a terminal; `kaptain kg` for short. Prints JSON. It works on the project folder chosen in Settings, or the folder you give with `--root`, and names the folder and where it came from on its first line. `index` waits for the pass and its vectors.

| Flag | Meaning |
|---|---|
| `--root DIR` | The folder to index or query; default the project folder from Settings |
| `--no-vectors` | index: do not wait for the vectors |
| `--confirm` | index: index a home folder or a very large tree on purpose |
| `--kind K` | search: `function`, `method` or `class` |
| `--budget N` | context: token budget; default 2000 |

Details and output: [God's Eye and KodeGraph](https://chynj.ca/kaptain/docs/#kodegraph).

### Network, devices and licence

#### kaptain remote

```text
kaptain remote [on | off] [--json]
```

Shows or changes remote access over your tailnet, with readiness checks.

Details and output: [kaptain remote](https://chynj.ca/kaptain/docs/#cli-remote).

#### kaptain nodes

```text
kaptain nodes <status | verify | token | models | ask> [--json]
```

Sharing models between your Kaptains from a terminal.

Details and output: [Pairing from the terminal](https://chynj.ca/kaptain/docs/#cli-nodes).

#### kaptain device

```text
kaptain device <register | status>
```

`register` binds this machine to your account through an approval in the account portal and, on a computer that has an access code, keeps it (a computer with none gets one, printed once); on a registered computer it shows the registration and asks before starting again. `status` shows the local certificate and entitlement. `kaptain device` with nothing after it prints the usage and the registration statement, ending "A licence key alone never registers a computer. Signing in is always required." 

| Flag | Meaning |
|---|---|
| `--nickname NAME` | register: the name shown in the portal; default the hostname |
| `--no-browser` | register: do not open a browser |
| `--json` | Machine-readable output |
| `--again` | register: register a computer that is already registered, without asking |

Details and output: [Register a machine](https://chynj.ca/kaptain/docs/#device-register).

#### kaptain license

```text
kaptain license <status | refresh> [--json]
```

`status` shows the entitlement from local files. `refresh` asks the licence server for a new one and says why if it cannot.

| Flag | Meaning |
|---|---|
| `--json` | Machine-readable output |

Details and output: [Check where a machine stands](https://chynj.ca/kaptain/docs/#licence-status).

#### kaptain account

```text
kaptain account <status | open> [--json]
```

`status` shows the signed-in account and this device. `open` opens the account portal.

| Flag | Meaning |
|---|---|
| `--json` | Machine-readable output |

Details and output: [Check where a machine stands](https://chynj.ca/kaptain/docs/#licence-status).

#### kaptain billing open

```text
kaptain billing open
```

Opens billing in the account portal. Payment details stay with the payment provider.

#### kaptain channels

```text
kaptain channels <list | setup | pending | approved | approve | revoke | groups | allow-group | deny-group>
```

Connects Kaptain to Telegram, Signal, Discord or Slack and manages who may talk to it.

| Flag | Meaning |
|---|---|
| `--account ID` | Which connection, when you have more than one |

Details and output: [Channels](https://chynj.ca/kaptain/docs/#channels).

### Advanced

#### kaptain engine

```text
kaptain engine <start | status | version>
```

Runs Kaptain's tool engine on its own, for development. `kaptain serve` already runs it inside the same process, so you do not need this to use Kaptain.

## Troubleshooting

Find the message or symptom, then the fix. When in doubt, `kaptain status`, `kaptain doctor` and the log (`kaptain.log` in the [data folder](https://chynj.ca/kaptain/docs/#files)) say most of what is wrong.

### Installing and starting

| Symptom | Cause | Fix |
|---|---|---|
| `command not found: kaptain` | `~/.local/bin` is not on your PATH | Do the [PATH step](https://chynj.ca/kaptain/docs/#path), or run `~/.local/bin/kaptain start`. `type -a kaptain` shows every copy. |
| macOS: "cannot be opened because the developer cannot be verified" | The binary was downloaded in a browser and is not yet notarized | `xattr -d com.apple.quarantine <file>`, or **System Settings › Privacy & Security › Open Anyway** ([macOS](https://chynj.ca/kaptain/docs/#install-macos)) |
| Windows: "Windows protected your PC" | The build is not yet signed | **More info**, then **Run anyway** |
| `kaptain start` says `kaptain already running (pid N)`, but nothing works | Another program is using port 8810; `kaptain start` reports whatever listens there | Stop that program, or run Kaptain elsewhere: `KAPTAIN_PORT=8820 kaptain start`, and use the same variable for `status` and `stop` |
| `kaptain: serve: listen tcp 127.0.0.1:8810: bind: address already in use` | The same, from `kaptain serve`: another program holds the port | As above |
| No GPU: `kaptain doctor` says `GPU: cpu (CPU)`, and the llama.cpp install says "It runs on the CPU (no GPU detected)." | This machine has no GPU Kaptain can use | Nothing is broken: local models run on the CPU, more slowly. Pick a smaller model (the wizard marks which fit), or use a CLI or cloud model. If a GPU is present but unusable, **Fix GPU access** appears under **Settings › Network Access › Connection**. |
| `kaptain: the access code (api_token) in …/kaptain.json is too short …` (or `is empty`, or `has characters a code Kaptain makes never has`) — `Kaptain will not serve with it` | `api_token` was edited by hand after setup; Kaptain serves only with a code it made | `kaptain access-code rotate`, then `kaptain start` ([Get a new access code](https://chynj.ca/kaptain/docs/#access-code-new)) |
| `process started … but it is not serving` | The server stopped while starting | Read `kaptain.log`. A line `refusing to bind non-loopback address … complete setup on localhost first` means a network mode or `KAPTAIN_ADDR` was set before setup finished: finish setup on this machine first. |
| The browser did not open | No browser opener on this machine, such as a server | Open the `UI:` address `kaptain start` printed |
| `kaptain status` says stopped while Kaptain runs | It started with a different `KAPTAIN_PORT` or `KAPTAIN_ADDR` | Use the same variables for `status` and `stop` |
| Windows: `kaptain stop` cannot find Kaptain | Windows has no port lookup, so `stop` uses the pid file | Stop it from the Task Manager, then use `kaptain start` and `kaptain stop` from then on |
| `kaptain update` fails: `cannot write the directory` | The binary is in a folder you do not own, such as `/usr/local/bin` | Reinstall with the [installer](https://chynj.ca/kaptain/docs/#install-linux) into `~/.local/bin` |
| `kaptain uninstall` ends with `left …` | The binary is in a folder only `sudo` can change | Delete that file with `sudo rm`, as you installed it |

### Setup and access

| Symptom | Cause | Fix |
|---|---|---|
| Finish setup fails: verify your email | A trial needs a verified email | Open the verification email, then press **Finish setup** again |
| Finish setup fails: trial already used | This machine already had its trial | Subscribe at [chynj.ca/account](https://chynj.ca/account/) and sign in on this machine again; a licence key alone does not register it |
| Finish setup fails: device limit reached | Your licence has all its devices | Free a seat at [chynj.ca/account](https://chynj.ca/account/): **Sign out** or **Remove** an old device under **Devices using your license** |
| Create account stays off with "Can't confirm the current Terms right now; try again shortly." | Kaptain could not read the current Terms from CHYNJ, so it cannot ask you to agree to them | Check the internet connection and press **Try again**, or create the account at [chynj.ca/account](https://chynj.ca/account/) and sign in |
| "The Terms of Service were updated … so no account was created yet." | The Terms changed while the form was open, or this build is too old to send the current version | Review the Terms shown, tick the box again and retry; if it keeps happening, `kaptain update` or create the account at [chynj.ca/account](https://chynj.ca/account/) and sign in |
| "CHYNJ cannot offer accounts, trials or licences where you are connecting from, because Canadian sanctions law does not allow it." | You are connecting from a place CHYNJ cannot serve | See [chynj.ca/legal/availability](https://chynj.ca/legal/availability/) |
| A banner "Kaptain is running — this computer's licence needs attention", and views say "Waiting on this computer's licence" | Requests answer `402 Payment Required` with `entitlement_required`: "Kaptain needs a current signed device entitlement. Open Account & License to reconnect, subscribe, or restore this device." | Press **Open Account & Licence** in the banner; the reason and the fix are in [When Kaptain answers 402](https://chynj.ca/kaptain/docs/#licence-402) |
| `{"error":"unauthorized","action":"pair","hint":"enter this device's Kaptain access code"}` (401) | The request carried no access code and no paired session, or an old one | In a browser, pair with the [access code](https://chynj.ca/kaptain/docs/#access-code). A script sends `Authorization: Bearer chynj_…` |
| "A licence key alone never registers this computer — sign in to your CHYNJ account" (`key_needs_signin`) | A licence key was typed on a computer with no CHYNJ account signed in | Press **Sign in to your CHYNJ account**; the key is kept and used once you have signed in. In a terminal, answer `y` to `Sign in now and keep this key?`, or run `kaptain device register` |
| **Pair this browser with Kaptain** appears | This browser has no session yet, or the access code changed | Enter the [access code](https://chynj.ca/kaptain/docs/#access-code) |
| `access_code_refused` (401), or the pairing screen says "This computer's access code is not one Kaptain made" | The code in `kaptain.json` was edited by hand and Kaptain refuses it | On the computer where Kaptain runs: `kaptain access-code rotate` ([Get a new access code](https://chynj.ca/kaptain/docs/#access-code-new)) |
| "That code didn't match — check and try again." | A typo, or an old code | Copy the code again. `kaptain status` prints where it is saved. To replace it: [Get a new access code](https://chynj.ca/kaptain/docs/#access-code-new) |
| `Setup is locked after onboarding` | Setup was finished, so its pages need the access code | Open `/?force_setup=1` in a browser already paired with this Kaptain |
| `Client is not allowed to reach Kaptain.` (403) | The address you came from is not one Kaptain admits in its current mode, such as a device outside your tailnet | Open Kaptain from this machine, or from a device on your tailnet in Tailscale mode. To go back to local only: `kaptain remote off`, then restart. |
| Kaptain in Tailscale mode does not open at `127.0.0.1` | It listens on the tailnet address only | Open `http://100.x.y.z:8810` |
| Other devices cannot reach Kaptain after a restart in Tailscale mode | Tailscale was down when Kaptain started, so it listens on this machine only | Start Tailscale, then restart Kaptain |
| `This device is not on the allowed-devices list for this Kaptain instance.` (403) | The device lock is on and this device is not allowed, or Kaptain cannot reach Tailscale to check | Allow the device under **Settings › Network Access** from this machine or an allowed device, and make sure Tailscale is running |
| `Host header is not allowed.` (421) | You used a machine name or HTTPS name Kaptain does not know | Add it to `allowed_hosts` ([HTTPS over Tailscale](https://chynj.ca/kaptain/docs/#https)), or use the `100.x.y.z` address |
| A phone cannot load Kaptain at all | Kaptain is in Localhost only mode, or the phone is not on your tailnet | Switch to Tailscale and restart; check `tailscale status` lists the phone |
| A burst of unauth requests in the access log | A browser tab that was never paired is polling | Pair it, or close it |

### Models

| Symptom | Cause | Fix |
|---|---|---|
| `ollama: NOT reachable` in `kaptain doctor` | Ollama is not installed or not running | [Install Ollama](https://chynj.ca/kaptain/docs/#ollama), or run `ollama serve` |
| `llama-server binary not found` | No `llama-server` for GGUF models | **Install llama.cpp for me** in the setup wizard or **Install llama.cpp now** under **Settings › Model Handling › KodeGraph Embedder** ([GGUF](https://chynj.ca/kaptain/docs/#gguf)), or set the path of your own in **Settings › Runtimes › llama.cpp Runtime** |
| `llama-server needs system libraries this machine does not have: libgomp.so.1` | A minimal Linux install lacks a library the downloaded llama.cpp needs | Press **Install libgomp1 for me** (or the package named), or run the command shown, then **Retry** |
| The llama.cpp install says `DEGRADED: this build runs on the CPU only` | No GPU build of llama.cpp ran on this machine; llama.cpp publishes no CUDA build for Linux | In **Settings › Runtimes › llama.cpp Runtime**, press the **Install …** build it offers or **Build llama.cpp for this GPU**, or set the path of a GPU build of `llama-server` there |
| `not a valid GGUF … begins with "<!do"` | A web page was saved instead of the model | Delete the file and use the direct download link (`…/resolve/main/<file>.gguf`) |
| `URL returned an HTML page` when adding a GGUF | A model page address was pasted | Use the direct download link |
| A Claude or Codex model is missing from the picker | The CLI is not on Kaptain's PATH | Check `which claude`; add its folder in **Settings › Runtimes › Toolchain Paths** |
| `gemini-cli support is disabled in this build` | The Gemini CLI is not a model in 0.0.9 | Pick another model |
| "This Claude engine is too old for the model (…) — … — update Kaptain, or pick an older Claude model in Settings", then the turn fails | The Claude helper built into this Kaptain does not know the Claude model you chose | `kaptain update` and restart, or choose an older Claude model under **Model** in the ⚙ for `claude-cli` |
| `cloud model … selected but no cloud base URL is configured` | The cloud model's settings are incomplete | Add it again under **＋ Add a model… › Cloud API** |
| `no vision model available` | No model that can see images is chosen or installed | Choose one under **Settings › Model Handling › Vision tool** |
| An image description times out | A slow vision model on a small GPU | Set `KAPTAIN_VISION_TIMEOUT_S` higher, or pick a faster vision model |
| The chat's context card says `summarised without a model (none can chat) — pick a summary model in Settings` | No model here can write the summary, so older messages were folded as plain text | Choose a model under **Settings › Model Handling › Context & Compaction** or **Delegation** |
| A small local model loses track or runs out of room | Its context window is the 8,192-token default | Raise **Context window** in the [⚙ model settings](https://chynj.ca/kaptain/docs/#model-settings), as memory allows |
| `no worker model chosen — pick one in Settings ▸ Delegation` | No worker is chosen; there is no default | Choose one under **Settings › Model Handling › Delegation** and press **Save** |
| Delegation does nothing | **Delegate** is off, or the worker is not installed | Turn on **Tools** and **Delegate**; choose a worker you have |

### Turns that stop or end early

A turn that stops says why, in its row or under the answer ([Run status](https://chynj.ca/kaptain/docs/#run-status)). The name in brackets is the limit that ended it.

| The chat says | Cause | Fix |
|---|---|---|
| **STOPPED** `stopped by the user: Stop was pressed` | You, or another of your devices, pressed Stop | Send the message again |
| **STOPPED** `client disconnected: …` or `Kaptain shut down: …` | The browser went away, or Kaptain stopped, while the turn ran | Send it again; a scheduled run waits for its next slot |
| **ERROR** `stall guard: no model output or tool progress for 12m0s (stall_timeout)` | The model or a tool went silent for 12 minutes, for example a model still loading on a slow machine | Check the model with `kaptain doctor`; raise `stall_timeout_seconds` in [`kaptain.json`](https://chynj.ca/kaptain/docs/#settings-json) for a slow machine |
| **ERROR** `agent turn timeout: the agent run reached 2h0m0s (agent_turn_timeout_seconds)` | A kapsule run took longer than its limit (2 hours unless `agent_turn_timeout_seconds` sets another) | Raise `agent_turn_timeout_seconds`, or give the kapsule a smaller job |
| A note `tool-round budget reached (50 rounds) — answering with what has been gathered`, then an answer from what it had | The model kept calling tools and never said it was done | Ask a narrower question; raise `max_tool_rounds` only for long jobs |
| A note `context window nearly full (…) — answering with what has been gathered` | The model's window filled with history and tool results | Raise **Context window** in the [⚙ model settings](https://chynj.ca/kaptain/docs/#model-settings), or start a new chat |
| **Incomplete** — `1 change failed and is not in place: …` | A file change or command the model made failed | Read the named change in the turn's tool calls, then ask again |
| **Not verified** — `the review could not judge the answer …` | Kaptain could not check the answer against what the run did | Read the tool calls yourself before you rely on it |

### Tools, kapsules and MCP

| Symptom | Cause | Fix |
|---|---|---|
| A tool says `User denied the operation` though you did not | The model is in **Read-only**, or `kaptain-engine` runs outside Kaptain, where changes are refused | Change **Tool approval**, or use the CLI as a model inside Kaptain ([MCP](https://chynj.ca/kaptain/docs/#mcp-out)) |
| `This run is unattended — no one is available to approve it` | A scheduled run on **Ask** reached a risky step | Set the kapsule's **Permissions** to Auto-approve or Full access if it should act alone ([Kapsule settings](https://chynj.ca/kaptain/docs/#kapsule-settings)) |
| `refused: path_not_allowed — … is outside every folder this kapsule may change` | The kapsule may change only its workspace and the folders you listed for it | Add the folder under **Settings › Edit access › Folders this kapsule may change**, or `path:/that/folder rw` to its [trusted scopes](https://chynj.ca/kaptain/docs/#allowed-paths); writes there follow its approval mode ([What a kapsule may write](https://chynj.ca/kaptain/docs/#kapsule-writes)) |
| `sandbox mode runs nothing privileged` | The model is in **Read-only** and the command used `sudo` | Change its **Tool approval** if it should be asked for sudo |
| A command keeps running after the answer | It outran its time limit or started a server, and became a [background job](https://chynj.ca/kaptain/docs/#jobs) | Press **Stop** in the strip above the message box, or ask the model to stop it |
| `refused: definition_read_only — … this kapsule can never change its own definition` | The write was into the kapsule's own `kapsule.json` or definition folder, which no kapsule changes, even inside a folder you granted | Change the kapsule from its **Settings**, or ask Kaptain chat ([Edit access](https://chynj.ca/kaptain/docs/#kapsule-edit-access)) |
| A scheduled run did not happen | Kaptain was not running when it was due (missed runs are skipped), the kapsule has no standing task, or it is disabled | Check **Jobs**; add a task; enable the kapsule |
| A `kapsule.json` edit does not show up | Hand edits are read at start | Restart Kaptain |
| An MCP server is refused when added | Its command is not installed | Install the server's runtime, or give the full path to the program |
| An MCP server's key ended up in `mcp_servers.json` | `${VAR}` was not quoted, so the shell replaced it | Remove and add the server again with `'KEY=${VAR}'` in single quotes |
| Windows: model commands lack common tools | No Git Bash, so commands run in `cmd.exe` | **Install portable Git Bash** in **Settings › Runtimes › Agent Shell (Windows)** |
| `sudo requests are turned off in Settings ▸ Sudo requests, so this command was not run` | The **Sudo requests** switch is off | Turn it on under **Settings › Model Handling › Sudo requests**; every sudo then shows a pop-up for you to answer |
| `timed out after 30s and was stopped` | The command ran through `kaptain mcp` (Claude Code or Codex), where commands stop at their time limit, or the chat already runs 8 background commands | Ask for a longer `timeout` (up to 300 seconds), or stop a background command first |
| A background command ends with `limit for background commands` | A command that outran its time limit ran longer than `shell_job_max_minutes` (default 60) | Raise `shell_job_max_minutes` in `kaptain.json`, or start the command with `background: true`, which has no limit |

## Glossary

| Term | Meaning |
|---|---|
| **Access code** | `chynj_…`. Signs a person's browser or app into one Kaptain. Shown once at setup. |
| **Trusted scopes** | A kapsule's named targets: folders it may change (`rw`, under its approval mode) or read without asking (`ro`), MCP servers it may use without asking, and the web hosts it is limited to. They never widen a permission mode. |
| **Approval mode** | Ask, Read-only, Auto-approve in workspace or Full access: what tools may do without asking. |
| **BlackBox** | The record of every turn: context sent, tool calls, reply and tokens. |
| **Brain Logs** | Kaptain's live activity log in the workbench. |
| **Channel** | Your own bot on Telegram, Signal, Discord or Slack, run from your machine. |
| **CLI harness** | Claude Code or Codex driven by Kaptain as a model (`claude-cli`, `codex-cli`). |
| **Compaction** | Folding older messages of a long chat into a summary, so it fits the model's window. |
| **Connection code** | `kcat_…`. Lets another of your Kaptains use this one's models, and nothing else. |
| **Data folder** | Where Kaptain keeps its settings, chats and models database. |
| **Delegation** | Handing bounded work from the chat model to the worker model. |
| **Device certificate** | Proof that a machine may use your licence. |
| **Deview** | The file explorer and editor in the workbench. |
| **Entitlement** | A short-lived signed proof of your licence, refreshed in the background. |
| **GGUF** | The file format of models run by llama.cpp. |
| **Job** | A command that keeps running in the background after its tool call returned, shown in the strip above the message box. |
| **God's Eye** | The graph view of your project's code. |
| **Kapsule** | An agent defined as a folder: model, persona, tools, permissions, memory and schedule. |
| **KodeGraph** | Kaptain's index of your project's code, used by the code-search tools. |
| **Krew** | Kaptain's toolbelt, and the workbench view that manages tools, MCP servers and skills. |
| **Lesson** | A one-sentence rule a kapsule keeps with the `remember` tool after a clean run. |
| **MCP** | Model Context Protocol, the open standard for connecting tools to models. |
| **Node** | Another of your Kaptains whose models you borrow; its models show as `node:<machine>/<model>`. |
| **Project folder** | The folder Kaptain and its tools work in. |
| **Run memory** | Whether a scheduled kapsule replays its own past runs. Off by default. |
| **Skill** | A Markdown document a model loads when relevant. |
| **Summarizer** | The model that writes compaction summaries. |
| **Tailnet** | Your private Tailscale network. |
| **Tool resolver** | How tools reach a local or cloud model: a few in full, the rest by name, looked up with `tool_schema_resolve` when needed. Always on. |
| **Worker** | Two uses: the **worker model** runs delegated briefs; a kapsule's **workers** are agents it creates for one job. |
