krabb

Documentation

Everything you need to set up and use krabb.

On this page

Installation

Install krabb from PyPI. Requires Python 3.10 or later.

pip install krabb

Or with pipx for isolated installation:

pipx install krabb

Quick Start

Initialize krabb, then open the dashboard:

# Register the hook and start the daemon
krabb init

# Check that everything is running
krabb status

# Open the dashboard in your browser
krabb dashboard

That's it. krabb is now logging every tool call Claude Code makes.

CLI Commands

krabb init

Install the hook into Claude Code settings and start the background daemon. This registers a PreToolUse hook that sends tool call data to krabb.

krabb status

Show the current daemon status, port configuration, and today's event stats.

krabb logs

Print recent events to the terminal. Supports filtering by tool type.

--toolFilter by tool (e.g. WebFetch, Bash)
--limitNumber of events to show (default: 20)
krabb dashboard

Open the web dashboard in your default browser. The dashboard runs at localhost:4242.

krabb blocklist

Manage the domain blocklist from the terminal.

add <pattern>Add a domain pattern
remove <pattern>Remove a domain pattern
listShow all blocked patterns
krabb hook

Run the hook server in the foreground. Useful for debugging. Normally started automatically by `krabb init`.

krabb uninstall

Remove the hook from Claude Code settings and stop the daemon.

Dashboard

The dashboard runs at localhost:4242 and has four tabs:

  • Overview — Stats cards (events today, blocked count, top domain, active sessions), activity feed, and tool breakdown chart.
  • Events — Searchable, filterable event table. Filter by tool type or decision (allow/deny). Group by tool, session, or domain. Click any event to see the full JSON payload.
  • Rules — Manage domain blocklist patterns and protected file patterns. Changes apply immediately.
  • Settings — Configure the default decision (allow/deny), toggle Bash and Read/Write logging, export or clear events.

Domain Blocklist

krabb checks every WebFetch and WebSearch URL against your blocklist. Three pattern types are supported:

Exact match

evil-site.com

Blocks the exact domain.

Wildcard

*.phishing.net

Blocks any subdomain. *.phishing.net matches foo.phishing.net, bar.phishing.net, etc.

Regex

/tracking\.[\w]+\.com/

Surrounded with /slashes/. Full Python regex support.

Add patterns via the CLI or the dashboard Rules tab:

krabb blocklist add evil-site.com
krabb blocklist add "*.phishing.net"
krabb blocklist add "/tracking\.\w+\.com/"
krabb blocklist list

File Protection

krabb checks Write and Edit tool calls against protected file patterns. Matching files are blocked from modification.

Glob

*.env

Matches any file ending in .env in any directory.

Directory prefix

src/config/

Matches any file under the src/config/ directory.

Exact path

credentials.json

Matches the exact file name.

Manage protected files from the dashboard Rules tab or via the API.

Configuration

krabb stores its database and configuration at ~/.krabb/krabb.db (SQLite). Configuration options can be changed from the dashboard Settings tab:

  • default_decision — Whether to allow or deny unmatched tool calls (default: allow)
  • log_bash — Log Bash tool calls (default: on)
  • log_readwrite — Log Read/Write tool calls (default: off)
  • hook_port — Port for the hook server (default: 4243)
  • dashboard_port — Port for the dashboard (default: 4242)

Hook Integration

krabb uses Claude Code's PreToolUse hook system. When you run krabb init, it adds a hook entry to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "curl -s -m 5 -X POST -H 'Content-Type: application/json' -d @- http://127.0.0.1:4243"
      }
    ]
  }
}

Before each tool call, Claude Code sends the tool name and input as JSON to krabb's hook server. krabb logs the event, checks it against blocklist and file protection rules, and returns allow or deny.

If the hook server is unreachable (e.g. krabb is not running), the tool call is allowed by default so your workflow is never blocked.

Found an issue? Open an issue on GitHub.