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.

Chat surfaces

Kaptain Chat is the primary supervisor conversation. Team Chat is the shared room for working with named agents. MemberChat is a focused conversation with one agent. These surfaces help users see where a request belongs instead of forcing every task into one undifferentiated chat thread.

Agents

A Kaptain agent can have a name, behavior, workspace, model settings, tools, memory, tasks, schedules, and logs. 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 is exposed through Kaptain's Krew Tools system. Enable and configure the delegate_task Krew Tool in Krew Tools settings, then choose the model route it should use. Once enabled, suitable subtasks can move away from the primary model while the main route remains available for final reasoning.

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

BlackBox Traces expose request-level facts such as model calls, tool calls, token counts, context sent to models, errors, and response previews. God's Eye View helps users understand project structure and selected code/file relationships. These views improve inspection; they should not be described as 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 the current Kaptain access token. Do not port-forward Kaptain to the public internet.

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