Document · User guide · 18 min read

Kaptain User Guide

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

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 seven entries:

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

Agents

A Kaptain agent is a standing persona with its own model, memory, tools, and direct-chat thread. In the Agents view you can change an agent's model, turn it on or off, edit its persona and task, and give it a schedule so it runs on its own. Its tool allowlist comes from the agent's kapsule.json, not from the interface.

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. Per-model thinking/reasoning controls should be exposed where the underlying provider supports them.

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 → 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 Context & Compaction. 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.

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.