captain-claw 0.1.0

A powerful console-based AI agent

Captain Claw

An open-source AI agent that runs locally, supports multiple LLM providers, and gets work done — coding, research, automation, document processing, orchestration — through persistent sessions with built-in safety guards.

Feature Snapshot

Capability	What it does
Multi-model routing	Mix GPT, Claude, Gemini, and Ollama in one CLI
Per-session model selection	Keep one session on Claude, another on GPT, another on Ollama
Persistent multi-session workflows	Resume any session exactly where you left off
Built-in safety guards	Input, output, and script/tool checks before anything runs
21 built-in tools	Shell, files, web fetch/get/search, docs, email, TTS, Google Drive/Calendar/Gmail, todo, contacts, scripts, APIs, deep memory
Skills system	OpenClaw-compatible skills with auto-discovery and GitHub install
Orchestrator / DAG mode	Decompose complex tasks into parallel multi-session execution
Memory / RAG	Hybrid vector + text retrieval across workspace and sessions
Web UI	Chat, monitor pane, instruction editor, command palette
Remote integrations	Telegram, Slack, Discord with secure pairing
Cross-session to-do memory	Persistent task list shared across sessions with auto-capture
Cross-session script memory	Persistent script/file tracking with auto-capture from write tool
Cross-session API memory	Persistent API endpoint tracking with auto-capture from web_fetch
Cron scheduling	Interval, daily, and weekly tasks inside the runtime
OpenAI-compatible API	POST /v1/chat/completions proxy with agent pool

Quick Start

1. Clone and install

git clone https://github.com/kstevica/captain-claw
cd captain-claw
python -m venv venv
source venv/bin/activate
pip install -e .

Requires Python 3.11 or higher.

2. Set an API key

export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export GOOGLE_API_KEY="your-google-key"
export GEMINI_API_KEY="your-gemini-key"

Use only the keys you need. For Ollama, no key is required — just set provider: ollama in config.yaml.

3. Launch

captain-claw

First run starts interactive onboarding automatically. The web UI redirects to /onboarding on first launch too. To re-run it later: captain-claw --onboarding.

4. Try it

> Investigate failing integration tests and propose a fix.

/models                          # see available models
/session model claude-sonnet     # switch this session to Claude

/new release-notes               # create a second session
/session model chatgpt-fast      # use GPT for this one

> Draft release notes from the previous session updates.

/session run #1 summarize current blockers   # run a prompt in session #1

Each session keeps its own model, context, and history.

5. Open the Web UI

The web UI starts by default at http://127.0.0.1:23080. Use Ctrl+K for the command palette, Ctrl+B for the sidebar, and edit instruction files live in the Instructions tab.

To use the terminal UI instead, pass --tui:

captain-claw --tui

How It Works

Sessions

Sessions are first-class. Create named sessions for separate projects, switch instantly, and persist everything.

/new incident-hotfix
/session model claude-sonnet
/session protect on                            # prevent accidental /clear
/session procreate #1 #2 "merged context"      # merge two sessions
/session run #2 summarize current blockers     # run prompt in another session
/session export all                            # export chat + monitor history

Tools

Captain Claw ships with 21 built-in tools. The agent picks the right tool for each task automatically.

Tool	What it does
shell	Execute terminal commands
read / write / glob	File operations and pattern matching
web_fetch	Fetch and extract readable text from web pages (always text mode)
web_get	Fetch raw HTML source for scraping and DOM inspection
web_search	Search the web via Brave Search API
pdf_extract	Extract PDF content to markdown
docx_extract	Extract Word documents to markdown
xlsx_extract	Extract Excel sheets to markdown tables
pptx_extract	Extract PowerPoint slides to markdown
pocket_tts	Generate speech audio (MP3) locally
send_mail	Send email via SMTP, Mailgun, or SendGrid
google_drive	List, search, read, upload, and manage Google Drive files
google_calendar	Create, list, update, and delete Google Calendar events
google_mail	Read-only Gmail access — search, read messages and threads
todo	Persistent cross-session to-do list with auto-capture
contacts	Persistent cross-session address book with auto-capture
scripts	Persistent cross-session script/file memory with auto-capture
apis	Persistent cross-session API memory with auto-capture
typesense	Index, search, and manage documents in deep memory (Typesense)

See USAGE.md for full parameters and configuration.

Guards

Three built-in guard types protect against risky operations:

guards:
  input:
    enabled: true
    level: "ask_for_approval"     # or "stop_suspicious"
  output:
    enabled: true
    level: "stop_suspicious"
  script_tool:
    enabled: true
    level: "ask_for_approval"

Guards run before LLM requests (input), after model responses (output), and before any command or tool execution (script_tool). See USAGE.md for details.

Configuration at a Glance

Captain Claw is YAML-driven with environment variable overrides.

model:
  provider: "openai"
  model: "gpt-4o-mini"
  allowed:
    - id: "claude-sonnet"
      provider: "anthropic"
      model: "claude-sonnet-4-20250514"

tools:
  enabled: ["shell", "read", "write", "glob", "web_fetch", "web_search",
            "pdf_extract", "docx_extract", "xlsx_extract", "pptx_extract",
            "pocket_tts", "send_mail", "google_drive", "google_calendar",
            "google_mail", "todo", "contacts", "scripts", "apis"]

web:
  enabled: true
  port: 23080

Load precedence: ./config.yaml > ~/.captain-claw/config.yaml > environment variables > .env file > defaults.

For the full configuration reference (23 sections, every field), see USAGE.md.

Advanced Features

Each of these is documented in detail in USAGE.md.

• Orchestrator / DAG mode — /orchestrate decomposes a complex request into a task DAG and runs tasks in parallel across separate sessions with real-time progress monitoring. Also available headless via captain-claw-orchestrate.

• Skills system — OpenClaw-compatible SKILL.md files. Auto-discovered from workspace, managed, and plugin directories. Install from GitHub with /skill install <url>.

• Memory / RAG — Hybrid vector + text retrieval. Indexes workspace files and session messages. Configurable embedding providers (OpenAI, Ollama, local hash fallback).

• Cross-session to-do memory — Persistent task list shared across sessions. Auto-capture from natural language, context injection to nudge the agent, and full /todo command support across CLI, Web UI, Telegram, Slack, and Discord.

• Cross-session address book — Persistent contact memory that tracks people across sessions. Auto-captures from conversation and email, auto-computes importance from mention frequency, and injects relevant contact context on demand.

• Cross-session script memory — Persistent tracking of scripts and files the agent creates. Auto-captures from the write tool when executable extensions are detected. Stores path + metadata (no file content in DB). On-demand context injection when script names appear in conversation.

• Cross-session API memory — Persistent tracking of external APIs the agent interacts with. Auto-captures from web_fetch and web_get when API-like URLs are detected. Stores credentials, endpoints, and accumulated context. On-demand context injection when API names or URLs appear in conversation.

• Cron scheduling — Pseudo-cron within the runtime. Schedule prompts, scripts, or tools at intervals, daily, or weekly. Guards remain active for every cron execution.

• Execution queue — Five queue modes (steer, followup, collect, interrupt, queue) control how follow-up messages are handled during agent execution.

• Remote integrations — Connect Telegram, Slack, or Discord bots. Unknown users get a pairing token; the operator approves locally with /approve user.

• OpenAI-compatible API — POST /v1/chat/completions endpoint proxied through the Captain Claw agent pool. Streaming supported.

• Google Drive + OAuth — Connect your Google account for Drive file operations (list, search, read, upload, create, update) and Vertex AI model access.

• Google Calendar — Create, list, update, and delete calendar events. Uses the same Google OAuth connection as Drive.

• Google Mail (Gmail) — Read-only Gmail access — search, read messages, browse threads and labels. No send/modify/delete scope required.

• Deep Memory (Typesense) — Long-term searchable archive backed by Typesense. Indexes processed items from the scale loop, web fetches, and manual input. Hybrid keyword + vector search. Separate from the SQLite-backed semantic memory.

• Send mail — SMTP, Mailgun, or SendGrid. Supports attachments up to 25 MB.

• Document extraction — PDF, DOCX, XLSX, PPTX converted to markdown for agent consumption.

• Context compaction — Auto-compacts long sessions at configurable thresholds. Manual compaction with /compact.

• Session export — Export chat, monitor, pipeline trace, or pipeline summary to files.

Development

pip install -e ".[dev]"
pytest
ruff check captain_claw/

Architecture

Path	Role
captain_claw/agent.py	Main orchestration logic
captain_claw/llm/	Provider abstraction (OpenAI, Anthropic, Gemini, Ollama)
captain_claw/tools/	Tool registry and 21 tool implementations
captain_claw/session/	SQLite-backed session persistence
captain_claw/skills.py	Skill discovery, loading, and invocation
captain_claw/session_orchestrator.py	Parallel multi-session DAG orchestrator
captain_claw/semantic_memory.py	Hybrid vector + text retrieval (RAG)
captain_claw/deep_memory.py	Typesense-backed long-term archive
captain_claw/google_oauth_manager.py	Google OAuth token management
captain_claw/cli.py	Terminal UI
captain_claw/web/	Web server (WebSocket + REST + static)
captain_claw/orchestrator_cli.py	Headless orchestrator CLI
captain_claw/config.py	Configuration and env overrides
instructions/	Externalized prompt and instruction templates

FAQ

Is Captain Claw only for coding? No. It handles coding, ops automation, web research, document processing, email, and multi-session orchestration.

Can I use local models only? Yes. Set provider to ollama and run fully local.

Can I run different models at the same time? Yes. Model selection is per session. Different sessions can use different providers and models simultaneously.

Do I need guards enabled? No. Guards are off by default. Enable them when you want stricter safety behavior.

Is there a web interface? Yes — it's the default. Run captain-claw and open http://127.0.0.1:23080. Same agent, sessions, tools, and guardrails as the terminal. Use --tui for the terminal UI.

Where is the full reference? See USAGE.md for comprehensive documentation of every command, tool, config option, and feature.

Get Started

git clone https://github.com/kstevica/captain-claw
cd captain-claw
python -m venv venv && source venv/bin/activate
pip install -e .
captain-claw

If Captain Claw is useful to you, give the repo a star to help others find it.

Found a bug or have a feature idea? Open an issue. Contributions welcome.

License

MIT