claude-spectator

claude-spectator

A Claude Code plugin that provides OS-level read-only sandboxing for safe, auto-approved command execution.

Problem

Claude Code requires user approval for most Bash commands. Maintaining a large allowlist of individual read-only commands is brittle and hard to scale. A single missed pattern can block legitimate workflows or permit dangerous operations.

Solution

Instead of allowlists, claude-spectator wraps commands in an OS-level read-only sandbox enforced by the kernel. Any command prefixed with sandbox-run is guaranteed to:

• Read project files — filesystem visibility for inspection
• Block credential access — sensitive paths (~/.ssh, ~/.aws, etc.) denied at kernel level
• Write nothing — all writes blocked at the syscall level (EPERM)
• Access no network — all network operations blocked

This allows Claude Code to safely auto-approve sandboxed commands without user intervention.

How It Works

Claude Code ─── sandbox-run <cmd> ───▶ OS Sandbox ───▶ Command
                                         │
                                    Kernel enforces:
                                    ✓ file reads
                                    ✗ credential reads
                                    ✗ file writes
                                    ✗ network access

macOS: Uses sandbox-exec with a custom Sandbox Profile Language (Seatbelt, kernel-enforced).

Linux: Uses bubblewrap with namespace isolation (read-only bind mounts, no network namespace).

Installation

Inside a Claude Code session, first add the marketplace:

/plugin marketplace add jimmyken793/claude-spectator

Then install the plugin:

/plugin install claude-spectator@jimmyken793

Or install from a local clone:

/plugin marketplace add /path/to/claude-spectator
/plugin install claude-spectator@jimmyken793

The permission hook automatically rewrites sandbox-run commands to use the plugin's own binary, so no PATH setup is required.

The setup hook validates platform dependencies (sandbox-exec on macOS, bwrap on Linux) and optionally symlinks sandbox-run into ~/.local/bin/ for direct shell use.

Usage

Prefix any read-only command with sandbox-run:

# Git inspection
sandbox-run git status
sandbox-run git log --oneline -20
sandbox-run git diff HEAD~3

# File exploration
sandbox-run find . -name '*.py' -type f
sandbox-run du -sh node_modules/
sandbox-run wc -l src/**/*.ts

# Code analysis
sandbox-run python3 -c "import ast; print(ast.dump(ast.parse(open('main.py').read())))"
sandbox-run grep -r 'TODO' src/

Commands that attempt writes or network access will fail:

sandbox-run touch /tmp/file          # EPERM - write blocked
sandbox-run git commit -m "test"     # EPERM - can't write .git/
sandbox-run curl https://example.com # Network denied
sandbox-run npm install              # EPERM - can't write node_modules/

Auto-Approval

The permission hook intercepts all Bash permission requests:

• Commands starting with sandbox-run are auto-approved (the sandbox guarantees safety)
• All other commands follow the normal permission flow

Credential Protection

Sandboxed commands are blocked from reading known credential paths, preventing accidental exposure of secrets through command output.

Default blocked paths:

Path	Contents
~/.ssh/	SSH keys, known_hosts
~/.aws/	AWS credentials, config
~/.gnupg/	GPG private keys
~/.config/gcloud/	Google Cloud credentials
~/.azure/	Azure credentials
~/.kube/	Kubernetes configs with tokens
~/.docker/	Docker auth config
~/.netrc	Plaintext credentials
~/.npmrc	npm auth tokens
~/.git-credentials	Git credential store
~/.config/gh/	GitHub CLI tokens
~/.local/share/keyrings/	GNOME keyring

Adding custom paths:

Set SPECTATOR_EXTRA_DENY with colon-separated paths (relative to $HOME or absolute):

export SPECTATOR_EXTRA_DENY=".config/stripe:.vault-token:/etc/shadow"

Disabling credential blocking:

Set SPECTATOR_NO_CRED_BLOCK=1 to disable the default credential path blocking entirely:

export SPECTATOR_NO_CRED_BLOCK=1

Project Structure