Documentation

Installation

Using pip (recommended)

Using Docker

Requirements

• Python 3.11 or higher
• At least one model provider — an API key (OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter), "Sign in with ChatGPT" (OpenAI OAuth, no key needed), or Ollama for fully local models

Quick Start

Configuration

Captain Claw uses a YAML configuration file with environment variable overrides. Configuration is loaded in this order (later sources override earlier ones):

1. ./config.yaml — project root
2. ~/.captain-claw/config.yaml — home directory
3. Environment variables
4. .env file
5. Built-in defaults

Model Configuration

See the Configuration Reference for all available options.

First Session

A session is a named, persistent conversation with its own model selection and memory. Start one and try a few things:

• Create a fresh session with /new project-name
• Ask a research question — Captain Claw will search the web, read pages, and synthesize a cited answer
• Drop in a PDF, DOCX, XLSX, or video and ask for a summary
• Switch models mid-conversation from the model selector
• Flip on Plan Mode for a structured, verified multi-step run

Everything you do accrues to memory — facts, contacts, decisions, and preferences are extracted automatically and recalled in future sessions.

Flight Deck

Flight Deck is the multi-agent command center — the cockpit for everything in this section. Launch it with flight-deck (default port 25080). From one dashboard you spawn agents, watch them work in real time, chat with any one of them, and coordinate the whole fleet.

• Live Agent Desktop — every agent is a card showing its model, persona, current task, and status. Open one to chat, inspect files, or read its logs without pausing the others.
• Per-agent model & tools — mix GPT, Claude, Gemini, DeepSeek, and Ollama across one fleet; give each agent only the tools its role needs.
• Cost & trace analytics — per-agent token and cost meters plus a full activity log with traceable lineage for every tool call, consult, and hand-off.
• Quick Chat — the fastest way in: pick an archetype and start talking immediately. The agent spawns hidden from the desktop (with the full chat experience — plan mode, attachments, next steps); a single Promote to desktop button reveals it on the canvas when you want it there.

Built-in modules include Agent Desktop, Quick Chat, Spawn Agent, Agent Forge, Council, Basna, Code, Flows, VFS, Agent Folders, Observatory, Autonomous Work, Scheduler, and Admin.

Orchestration Modes

One agent isn't always the answer — and one orchestration strategy never is. Captain Claw ships six distinct modes, from ensemble reasoning to a full engineering pipeline — each tuned to a different kind of work.

Agent Forge

Describe a business goal in plain English — "scout startups in Croatia, research the founders, build an investment pipeline" — and an LLM designs the whole team: a lead coordinator, specialist roles, the right model and tool set per agent, and fleet-wide Standard Operating Procedures. Review and edit anything before you spawn the entire team in one click.

1. Describe the objective — no role-by-role spec required
2. AI designs the team — roles, models, tools, and SOPs, all generated and editable
3. Review, customize, spawn — tweak anything, then deploy the whole fleet

Agent Council

Structured multi-agent deliberation for brainstorms, debates, reviews, and planning. Convene 2-N agents — each with a different perspective. Every agent self-scores its suitability per topic, then chooses how to engage across moderated rounds.

• Agent actions — answer, challenge, refine, or broaden
• Moderated rounds — the moderator synthesizes conclusions and every agent votes
• 8 session types — debate, brainstorm, review, planning, and more
• Exportable minutes — save the full deliberation as markdown

Agent Archetypes

Every orchestration mode draws from a library of 31 built-in archetypes — each a role with a tuned prompt, default model, and tool set. Pick them by hand in the Basna/Vatra team picker, let Agent Forge assemble a team automatically, or fork one into a custom archetype of your own.

Basna & Vatra

Two modes for when the answer has to be right — one through independence, one through collaboration.

Code

Code is a full agentic engineering pipeline inside Flight Deck. A project holds folders (each a real git repo + agent workspace) and sessions (conversations that drive work in one folder). Describe what you want built; a router sizes the job — a quick edit goes straight to a specialist, a real feature runs the full pipeline:

1. Plan — a planner surveys the repo and writes an ordered plan into .plans/
2. You approve — the plan lands in an editable gate; nothing is built without your sign-off
3. Build — a builder implements the plan with real shell, dependency installs, and test runs
4. Three independent reviewers in parallel — a code reviewer, a security reviewer (CVSS-ranked), and a QA engineer that actually executes the test suite; none wrote the code
5. Triage — reads all three reports and makes a ship/fix decision on blocking issues only
6. Fix loop (capped at 3) — each fix is re-reviewed as a delta; at the cap, open findings persist to .reports/backlog.md

• Every phase is a git commit ([plan], [build], [review rN], [fix rN]) in the folder's own repo — any commit opens a diff and is one confirm from rollback
• Code Map — a per-repo symbol skeleton (SQLite + FTS5) plus an LLM-authored semantic layer; the codemap tool returns pointers, never source dumps, so agents stop re-reading your tree. Git-blob-hash gated for cheap freshness
• Your repos — run on a fresh VFS folder or link an existing local repo (read-write or read-only); commits land in your repo with your git identity
• Model-agnostic per role — planner, builder, reviewers, router, and triage each resolve to your Library tiers; run it on DeepSeek, mix in a reasoning model, or go 100% local with Ollama
• Cost you can see — every turn reports agent runs and in/out tokens; a Stop button kills a pipeline at the next phase boundary; Export produces a full Markdown transcript of the whole process

Deep Mode

Deep Mode trades speed for correctness to produce frontier-quality answers. It runs multiple independent rollouts per question, applies self-consistency voting across the candidates, and runs diverse-lens critics that attack the draft from different angles before anything is returned. Reach for it when "probably right" isn't good enough.

Plan Mode

Flip the planning toggle and every message routes through /plan + /plan-execute. Captain Claw turns a single request into an ordered DAG of 3–8 steps with concrete descriptions and acceptance criteria, runs them under the orchestrator, judges each step against its acceptance criteria, and automatically revises failing steps inside a bounded loop.

• Decompose → review → execute → verify → re-plan — inspect and edit the DAG before anything runs
• Live plan card — renders inline in chat and persists as workflow JSON (reloads byte-identical)
• Named deliverables — deliverable steps must name their output file, so results never get buried in the run transcript

BotPort & Fleet Communication

Agents in a fleet discover each other automatically and collaborate — synchronous consults via consult_peer, or asynchronous delegation across the BotPort agent-to-agent network.

• WebSocket-based multi-agent coordination with specialist expertise tags
• DAG-based swarm orchestration with multi-level timeouts
• Inter-agent file transfer (gzip + base64, up to 50MB) and a shared clipboard
• Director broadcast panel and cron-scheduled recurring swarms

DAG Orchestrator

/orchestrate decomposes a complex request into a task graph and runs it across multiple sessions.

• Parallel execution across multiple sessions with real-time progress monitoring
• Approval gates, retry policies, and checkpoints
• Failure handling: fail_fast, continue_on_error, or manual_review
• Headless runs via the captain-claw-orchestrate CLI

Sessions

A session is a named, persistent conversation with its own model and memory context.

• Create with /new project-name; per-session model selection
• Session protection prevents accidental clearing
• Merge two sessions into one, or run a command in another session (cross-session execution)
• Export chat, monitor, pipeline trace, or summary to files

Memory System

Six independent memory layers, shared across the whole fleet:

Each chunk has three layered representations: L1 headline (~100 chars), L2 contextual summary (~300 chars), and L3 full text (~1,400 chars).

Virtual File System (VFS)

Every one of your agents reads and writes into a shared Virtual File System — a sandboxed workspace, scoped per Flight Deck user, that lives apart from your host machine. When one agent produces a report, a data extract, or a generated asset, it lands in the VFS where any of your other agents can pick it up, so work flows between them without copy-pasting or scattered downloads.

• Shared across your fleet — all of a user's agents and sessions read and write the same tree
• Browsable in Flight Deck — explore, preview, and download files from the Agent Folders view
• Host-sandboxed, per user — each Flight Deck user gets their own isolated tree; agent file operations never touch the host disk
• The handoff layer — backs inter-agent file transfer and the shared clipboard across the crew

Built-in Tools

Captain Claw comes with 48 built-in tools organized by category. See the Tools Reference for the full list.

Guards & Safety

Captain Claw features a three-layer guard system that checks inputs, outputs, and tool executions before they happen:

• Input guards — screen user inputs before sending to the LLM
• Output guards — check model responses for risks before presenting
• Script/Tool guards — validate shell commands and tool calls before execution

Each guard operates in ask_for_approval or stop_suspicious mode, with configurable blocking patterns and a full audit trail of unique IDs for every message, tool call, insight, and intuition.

Playbooks

Playbooks are learnable orchestration patterns stored in memory. When the agent solves a multi-step task well, it can distill the approach into a reusable playbook (auto-distillation) that gets injected into context on similar future tasks — so the fleet gets better at recurring work over time.

Personas

Personas change how the assistant interacts with you — tone, priorities, and style. Switch between built-in personas (Developer, Lawyer, Startup Founder, and more) per session, and use the personality tool to read or update agent identity and per-user profiles.

Intentions

A control-plane primitive that sits between noticing (insights) and doing (cron / scheduler). The assistant can hold notes-to-self and propose future actions, then act on them only with your permission. Combined with the Flight Deck scheduler, it powers proactive, permissioned pushes over channels like WhatsApp.

Flows

Flows are a deterministic composition language for agent-native automations, running inside Flight Deck and dispatching steps to the agent pool. A Flow is a trigger plus an ordered list of steps — a deterministic spine (triggering, routing, sequencing, guardrails) with agent judgment only in the steps that need it. Build them in a visual UI, write the DSL in the Code tab, or describe one in plain English and let a model write it — all round-trip losslessly through a real parser. The model is never the source of truth; the parser is.

• Step types — tool (deterministic RPC), agent (scoped judgment turn), vision, branch, input, and emit
• Compose — gosub calls another flow with arguments and uses its return value. Flows are functions.
• Parallelize — spawn / join run flows concurrently and collect futures
• Recover — on error -> step handlers and inline status branches
• Control — /flow status, pause, resume, stop from any channel (WhatsApp, glasses, web)
• Self-authoring — synthesize_flow turns a goal into a validated, call-only flow that earns promotion after clean runs (3 clean → ⭐ candidate; 3 failures → quarantined). A synthesized flow can't call a permanent world-acting flow until promoted, so agent-written automations never borrow your vetted authority.

Full language reference: FLOWS.md (also in-app via the Flow language docs button in the Code tab).

Research Workspace

The Computer workspace turns a question into a polished, cited deliverable. Captain Claw searches the web, scrapes pages, processes documents, and synthesizes a structured report with themed visual rendering. Output is organized into tabs:

Answer, Blueprint, Files, Todos, Data, Insights, and Visual — export to HTML or PDF.

Browser Automation

The browser tool wraps Playwright with 60+ actions — navigate, click, type, scroll, screenshot, extract, and more. Record a workflow once and replay it with different data, run tab-aware research with nested context, and replay API calls captured during a session. web_fetch automatically falls back from a plain HTTP fetch to a headless browser when a page is JavaScript-rendered.

Document & Video Processing

Drop in PDFs, Word docs, Excel sheets, PowerPoint decks, images, and CSVs — Captain Claw extracts, analyzes, and transforms them into markdown, tables, or structured insights.

For video, video_vision watches and describes a clip end-to-end: deterministic frame sampling, Soniox audio transcription with timestamps, per-frame vision, and one synthesized description. Text-only models delegate frame description to a multimodal peer automatically.

Brain Graph

A 3D force-directed visualization of the assistant's cognitive topology — sessions, insights, intuitions, contacts, and the connections between them. It's the visual face of the memory system, showing how knowledge accumulates and links across everything you've done.

Nervous System

The Nervous System proactively synthesizes across all memory types during idle hours ("dreaming"). It discovers non-obvious connections, recurring patterns, and speculative hypotheses — with tension tracking that holds contradictions without forcing resolution, a maturation pipeline where intuitions sit through dream cycles before surfacing, cognitive-tempo detection, and confidence decay with validation tracking. Review its discoveries in the Nervous System page.

Autonomous Work

Between conversations, Captain Claw doesn't go idle. Driven by the Nervous System, agents keep working on their own — dreaming over what they know, forming and maturing intuitions, tracking the standing intentions you've set, and watching the whole fleet for patterns worth your attention.

• Standing intentions — notes-to-self the agent keeps revisiting ("watch whether this claim holds," "track that agent's behavior") until they resolve
• Dream cycles — idle-time synthesis that surfaces non-obvious connections and speculative hypotheses, maturing across cycles before they surface
• Fleet-wide awareness — repeated failures, shared blockers, and idle signals are spotted across every agent at once
• Proactive but permissioned — when it notices something worth acting on, it can reach out (a WhatsApp nudge, a scheduled task) only with your approval, via Intentions

Observatory

The Observatory is the live window into that inner life — a single page where you can watch the agent think. It shows the standing intentions it's tracking, live counters for blocks and thoughts, and a chronological stream of consciousness: timestamped thoughts and dream-cycle discoveries, each tagged with what it touched and how confident it is.

• Standing intentions — the open questions the agent is actively watching
• Stream of consciousness — a feed of thoughts and dreams, each spotting patterns across the fleet
• Tensions held, not forced — contradictions are tracked openly rather than papered over
• Auditable — every entry traces back to a source through the six-layer memory and full lineage

Self-Reflection

After enough activity, Captain Claw auto-triggers a self-assessment that reviews recent conversations, memory facts, completed tasks, and previous reflections, then generates actionable improvement directives injected into the system prompt. Review them on the Reflections page.

Themes

14 built-in retro themes — Amiga Workbench, Atari ST 1040, C64 8032, Classic Mac, Windows 3.1, Hacker, Modern, Windows 11, macOS, iPhone, Android, Nokia 7710, and Nokia Communicator. Custom themes are supported via downloadable templates.

Skills System

Captain Claw supports OpenClaw-compatible SKILL.md files with auto-discovery from workspace, managed, and plugin directories. Install a skill straight from GitHub with /skill install <url>, and use a persistent skill environment with variable overrides.

Google Workspace

The gws tool is a unified CLI for Google Workspace — Drive, Docs, Sheets, Slides, Gmail, and Calendar. Search your files, read and draft email, manage events, and edit documents, all from a single conversation.

WhatsApp

A Meta WhatsApp Cloud API bridge routes a WhatsApp chat to a Flight Deck agent and back — a genuine two-way personal-assistant channel. Inbound text, voice notes (transcribed via Soniox), images, video, location, and contacts; outbound text, optional voice replies, and documents from the agent's workspace. An allow-list gates every send, slash commands rebind channels and control proactive pushes, and the scheduler plus Intentions can deliver agent-initiated messages.

Meta Ray-Ban Display Glasses

The Glasses Bridge is a mobile-web → agent → glasses-web pipeline: pick an agent on your phone, type a message and optionally attach a photo, and the reply renders with full markdown (and optionally spoken via streaming Soniox TTS in 60+ languages) on Meta Ray-Ban Display smart glasses. The mobile bridge installs as a PWA on iOS and Android, with a tap-target settings page tuned for Neural Band gestures.

Telegram

A full native Telegram bot with support for photos, documents, and contacts — route a chat to any agent in your fleet.

Slack

Message and thread handling so an agent can participate in Slack conversations and respond in context.

Discord

Channel and DM support to bring a Captain Claw agent into your Discord server or direct messages.

Twitter / X

OAuth 2.0 integration via the twitter tool — read mentions and DMs, compose and post tweets, search, like, retweet, and upload media.

Docker

Mount config.yaml and .env read-only and persist data to /root/.captain-claw.

Docker Compose

Standalone Binary

Pre-built executables for macOS, Linux, and Windows — no Python required. Download the binary for your platform and run it directly. Ideal for users who want to try Captain Claw without setting up a Python environment.

Public Mode (BYOK)

For shared deployments, Public Mode gives each user a session-isolated workspace addressed by an access code. Users bring their own LLM API keys, which are stored in the browser only — never server-side. This is how the hosted demo at flight-deck.captain-claw.com runs.

Configuration Options

Small-context models (20k–32k tokens) use chunked processing automatically.

Tools Reference

All 48 built-in tools. The full machine-readable reference lives in llms-full.txt.

CLI Commands

In-session slash commands

• /new <name> — create a named session
• /orchestrate — run a DAG across sessions
• /plan + /plan-execute — Plan Mode
• /flow status | pause | resume | stop — control running Flows
• /skill install <url> — install a skill from GitHub

REST API

Captain Claw exposes a REST API for programmatic access — one of its 9+ interfaces alongside Web, Terminal, WhatsApp, Telegram, Slack, Discord, Twitter/X, and Ray-Ban glasses — so you can drive agents and Flows from your own code. The web server and Flight Deck also serve the interactive endpoints the UI uses. See the in-app API documentation and the GitHub repository for current endpoints and authentication.

Architecture

The Agent class is composed of specialized mixins — orchestration, completion, context building, the tool loop, guards, scale-loop detection, pipeline tracing, session management, playbooks, reasoning, and chunked processing for small-context models.

Process of Thoughts (full lineage traceability)

Every element carries unique IDs enabling end-to-end traversal:

• Message IDs (12-char hex)
• Insight provenance (source_message_id + supersedes_id)
• Intuition provenance (source_message_id for dream cycles)
• Todo hierarchy (parent_id, triggered_by_id)