Document · User guide · 18 min read

Kaptain User Guide

Use this after setup. It explains the main operating surfaces without exposing unnecessary implementation detail.

Doing one specific task? the How-To library — numbered steps, verified on a real install. This page is the deeper reference.

What Kaptain does

Kaptain is a local-first AI control plane. It helps users chat with a main supervisor, build team agents, route work to suitable models, run tools through controlled paths, review approvals, inspect logs and traces, schedule recurring jobs, and manage project work from a browser or trusted device.

The important rule is simple: Kaptain coordinates the workflow. Models reason. Tools execute through the allowed execution path. The user stays in control through model selection, approvals, logs, and visible traces.

The workbench

The interface is an activity bar on the left, a context sidebar next to it, and one view at a time in the middle. There are eight entries:

There is one chat with the main model, and one direct-chat thread per kapsule inside the Kapsules view. Kapsule threads keep their own history, so a question you ask an agent does not land in the main conversation.

Kapsules

A Kaptain agent is a standing persona with its own model, memory, tools, and direct-chat thread. In the Kapsules view you can change an agent's model, turn it on or off, edit its persona and task, give it a schedule so it runs on its own, set its approval mode ("Full access" is the only setting that runs a CLI-harness kapsule unattended) and its run memory (off by default; "Reset run memory" recovers a poisoned thread). Its tool allowlist is edited right in the kapsule's Tools panel — pick from the grouped catalogue and save; an empty selection means the full catalog, and enforcement happens at chat time. Everything also lives in the kapsule's kapsule.json, so a kapsule ships as a reviewable file.

Use agents when separate responsibility makes the work clearer: one agent for monitoring, one for research, one for project maintenance, or one for a specific recurring workflow.

Do not create agents only because it sounds more advanced. More agents should mean clearer ownership, not more noise.

Model routing

Kaptain supports model-agnostic operation across configured routes such as CLI providers, local models, and compatible cloud endpoints. The active brain model is the primary reasoning route. The model picker's ⚙ exposes a per-model Thinking toggle and, where the provider reports levels, a reasoning-effort control — the row is hidden for models that don't support it.

Settings › Model Handling › Vision tool picks which model processes images when a turn needs to look at one: a local model that declares vision, a GGUF with its projector file, a cloud model, a Claude or Codex CLI (which then looks with its own tools), or a paired machine's model; the same card sets the thinking policy and the two answer budgets. A vision GGUF from Hugging Face is one download.

Use premium models where depth matters: difficult planning, ambiguous debugging, final synthesis, security review, and production-impacting judgment. Use lighter or local routes where the task is bounded and reviewable.

Delegation

Delegation moves a bounded subtask to a second model while the main route stays on the conversation. Two places control it:

• Krew → Native Tools holds the tools themselves: delegate (one brief), delegate_batch (several at once), and delegate_status (which model would run it, and what that model is capable of). Each has its own on/off switch.
• Settings → Model Handling → Delegation picks the worker model that runs the briefs. Any runtime works here: Ollama, a local GGUF, a cloud endpoint, or a CLI harness. The change applies live, with no restart.

Settings groups Delegation under Model Handling. The worker model is a different job from the summarizer in the same group: the worker executes delegated briefs, the summarizer writes the rolling conversation summary. The summarizer falls back to the delegate worker when you have not chosen one separately.

Good delegation candidates include search summaries, rough classification, evidence packaging, repetitive extraction, and early-stage compression. Poor candidates include final production decisions, high-risk security reasoning, and changes that require deep cross-file judgment.

Approvals and execution

Tools can affect files, shells, tasks, and external services. Kaptain keeps execution behind visible policies and approval boundaries. Read approval prompts carefully, deny unclear actions, and keep automatic workflows off until you understand the behavior of the current project and model route.

Observability

The BlackBox view has two sections. Session turns expands each turn to the exact context that was sent, every tool call's request and response, and the reply. Model usage shows provider-reported token counts for CLI, local, and cloud runs. Gods Eye, under Views, shows project structure and code relationships. Brain Logs shows runtime log events. These views improve inspection; they are not a perfect reconstruction of every internal model decision.

Remote access

By default Kaptain accepts same-machine access only. For phone or second-device access, use Tailscale and this device's access code (chynj_…), which the browser asks for on the pairing screen. Do not port-forward Kaptain to the public internet.

Two Kaptains can pair: Settings › Network Access issues a connection code (a Kaptain Cluster Access Token) that the other machine enters. Paired machines share their models, their image processing and their model settings; the borrowed models appear in the picker under that machine's name and work everywhere a local model does.

To put a trusted HTTPS URL in front of it, read Enable HTTPS over Tailscale.

For conceptual guidance, read Secured Interaction. For installation steps, read the Setup Guide.