crabwise

README

Crabwise / The local control plane for your AI agents

Observe, govern, and audit what Claude Code, Codex CLI, and OpenClaw do on your machine.

Quick Start · Releases · Docs (coming soon)

Crabwise is a local-first daemon plus CLI for monitoring, audit, and policy enforcement around AI agents. It watches agent activity, can proxy provider traffic for enforcement, stores a hash-chained audit trail in SQLite, and keeps the control plane on your machine instead of sending it to a hosted service.

Built for solo developers, builders, and OpenClaw users. Current support is focused on Claude Code, Codex CLI, and OpenClaw-aware workflows.

Write Commandments that agents cannot break.

Crabwise Features

• See what your agents are doing in real time
• Enforce local policies before risky actions or provider calls go through
• Get Desktop or Discord notifications when an agent is blocked
• Keep audit history and operational visibility on your own machine
• Route local agents through a single control point with crabwise wrap
• Inject service-level agents like OpenClaw with crabwise service inject --agent openclaw
• Inspect status, activity, policies, and history from fast terminal UIs

Quick Start

Quick try (no install):

npx crabwise@latest version --plain

Daily use:

npm i -g crabwise

Fallback (install script):

curl -sSfL https://raw.githubusercontent.com/crabwise-ai/crabwise/main/install.sh | bash

Commands below are shown as crabwise. If not globally installed, prefix with npx crabwise@latest.

Initialize the config, commandments, tool registry, proxy mappings, and local CA:

crabwise init

Trust the Crabwise CA so local clients can use the proxy:

crabwise cert trust
# run the printed OS trust command
# or use: crabwise cert trust --run

Start the daemon in the foreground and leave it running:

crabwise start

Launch an agent through Crabwise:

crabwise wrap -- codex
# or
crabwise wrap -- claude
# or
crabwise wrap -- openclaw gateway

For service-managed OpenClaw, inject Crabwise into the service instead:

sudo crabwise service inject --agent openclaw --restart

If your OpenClaw Gateway runs as a user service, use --scope user and do not use sudo.

In another terminal:

crabwise status
crabwise agents
crabwise watch
crabwise audit

Stop the daemon from another terminal when you are done:

crabwise stop

How Requests Flow

Crabwise sits between the wrapped agent and the model provider. Requests and responses flow through the local proxy, policies are evaluated locally, and audit history stays on your machine.

Main Features

Local-first audit trail

Crabwise records normalized agent and proxy events in a local SQLite database with hash chaining, so you can inspect activity and verify integrity without depending on a remote service.

Policy enforcement

Crabwise can evaluate requests before they reach the model provider and evaluate supported tool-use payloads before they reach the agent. Policies are defined in YAML and support both warn and block outcomes.

Fast terminal workflows

The CLI is built for day-to-day use:

• crabwise status for daemon and proxy health
• crabwise agents for discovered agent sessions
• crabwise watch for live activity
• crabwise audit for historical events
• crabwise commandments list for active policies

Works with builders

Use crabwise wrap -- <command> to route a local agent, script, or tool runner through Crabwise without permanently changing your shell environment.

OpenClaw support

OpenClaw support is disabled by default. Enable it in ~/.config/crabwise/config.yaml, then start Crabwise so it can connect to the local OpenClaw Gateway and correlate activity with OpenClaw sessions.

adapters:
  openclaw:
    enabled: true

If your gateway requires authentication, export the token from adapters.openclaw.api_token_env before starting Crabwise. By default that environment variable is OPENCLAW_API_TOKEN.

Current enforcement is focused on provider-side governance through the Crabwise proxy. Use crabwise wrap -- openclaw gateway for a locally launched gateway, or crabwise service inject --agent openclaw for a service-managed gateway.

Notes

• The proxy uses a local CA certificate to inspect HTTPS traffic.
• Crabwise is usable now, but still a pragmatic v1 focused on Claude Code, Codex CLI, wrapped local agents, and OpenClaw-aware workflows.
• A dedicated documentation site will cover the full command reference, flags, configuration, and deeper operational details.

Development

make build
make test

License

Licensed under AGPL-3.0. See LICENSE.