Documentation

SafeClaw is small on purpose: every capability should be visible.

SafeClaw runs as a local CLI assistant and optional WhatsApp webhook. It talks to OpenAI-compatible model providers, stores sessions locally, and routes tool calls through explicit permission checks.

Overview

The assistant loop accepts a task, sends the conversation and available tools to the configured model, executes approved tool calls, appends results to the session, and returns a final answer. Tool behavior is constrained by the active permission profile and approval mode.

safeclaw run "inspect my workspace and summarize the README"
safeclaw chat --session personal
safeclaw doctor --strict

CLI commands

Command	Purpose
`run`	Run one task in a named session.
`chat`	Start an interactive task loop.
`tools`	List available tool capabilities.
`doctor`	Check local setup, config, WhatsApp, and service readiness.
`sessions`	List saved sessions.
`status`	Show session status.
`session-config`	Set per-session model and permission profile metadata.
`memory`	Show saved memory for a session.
`memory-search`	Search local memory notes.
`memory-edit`	Edit a memory note by ID.
`memory-forget`	Delete memory by ID or matching text.
`export`	Export a session and its memory.
`import`	Import a session export.
`whatsapp`	Run the Twilio-compatible WhatsApp webhook.
`service-*`	Install, start, stop, inspect, or uninstall the macOS background service.

Permissions

Set the default profile in .env with SAFECLAW_PERMISSION_PROFILE. Override it per command with --permission-profile or per session with session-config.

SAFECLAW_PERMISSION_PROFILE=readonly
SAFECLAW_APPROVAL_MODE=ask
ALLOW_SHELL=false

safeclaw run "search for TODOs" --permission-profile readonly
safeclaw session-config personal --permission-profile workspace-write

Approval modes are ask, deny, and auto. WhatsApp and other non-interactive contexts block approval-required actions instead of waiting forever for terminal input.

Memory and sessions

Session history and memory are local files. Memory supports create, list, search, edit, delete, export, import, and automatic session compaction for long-running conversations.

safeclaw memory --session default
safeclaw memory-search "whatsapp" --session default
safeclaw memory-edit 2 "Use readonly by default"
safeclaw memory-forget 2
safeclaw export --session default --output safeclaw-session.json

WhatsApp support is designed for remote access with deliberate boundaries. Configure Twilio credentials, allowed senders, and the public webhook URL ending in /whatsapp. Use service mode when you want SafeClaw to stay reachable while you walk away from the computer.

TWILIO_ACCOUNT_SID=...
TWILIO_AUTH_TOKEN=...
TWILIO_WHATSAPP_FROM=whatsapp:+14155238886
SAFECLAW_ALLOWED_SENDERS=whatsapp:+15551234567

safeclaw whatsapp --port 8080

Project structure

Path	Responsibility
`safeclaw/cli.py`	Typer command definitions and terminal UX.
`safeclaw/agent.py`	Agent loop, tool-call execution, and session integration.
`safeclaw/tools.py`	Workspace tools, permission gates, approvals, backups, shell, network, and messaging tools.
`safeclaw/sessions.py`	Local session history, memory handler, compaction, export, and import.
`safeclaw/whatsapp.py`	Twilio webhook, allowlist checks, WhatsApp commands, and remote task handling.
`safeclaw/doctor.py`	Setup diagnostics and actionable fixes.
`install.sh`	Fast installer with opt-in global launcher.
`guided-install.sh`	Step-by-step terminal installer for non-devs.
`mac-setup/`	Double-click macOS installer and WhatsApp walkthrough.
`tests/`	Mocked tests, installer checks, memory tests, and opt-in live tests.

Support

SafeClaw is early and community-driven. Support helps cover hosting, testing, domain costs, and development time for the installer, WhatsApp flow, local model support, and safety model.

Buy the team a coffee