hub / github.com/Dicklesworthstone/slb

github.com/Dicklesworthstone/slb @v0.3.1

Chat with this repo

repository ↗ · DeepWiki ↗ · release v0.3.1 ↗ · + Follow

2,809 symbols 16,081 edges 205 files 1,116 documented · 40% ● updated 16d agov0.3.1 · 2026-04-25★ 72

Browse by type

⨍ Functions 2,558◇ Types & classes 251

What it actually does AI analysis from the code graph — generated when you open this

loading…

README

Simultaneous Launch Button (slb)

A cross-platform CLI that implements a two-person rule for running potentially destructive commands from AI coding agents.

When an agent wants to run something risky (e.g., rm -rf, git push --force, kubectl delete, DROP TABLE), slb requires peer review and explicit approval before execution.

Why This Exists

Coding agents can get tunnel vision, hallucinate, or misunderstand context. A second reviewer (ideally with a different model/tooling) catches mistakes before they become irreversible.

slb is built for multi-agent workflows where many agent terminals run in parallel and a single bad command could destroy work, data, or infrastructure.

Key Features

Risk-Based Classification: Commands are automatically classified by risk level
Client-Side Execution: Commands run in YOUR shell environment (inheriting AWS credentials, kubeconfig, virtualenvs, etc.)
Command Hash Binding: Approvals bind to the exact command via SHA-256 hash
SQLite Source of Truth: Project state lives in .slb/state.db
Agent Mail Integration: Notify reviewers and track audit trails via MCP Agent Mail
TUI Dashboard: Interactive terminal UI for human reviewers

Risk Tiers

Tier	Approvals	Auto-approve	Examples
CRITICAL	2+	Never	`rm -rf /`, `DROP DATABASE`, `terraform destroy`, `git push --force`
DANGEROUS	1	Never	`rm -rf ./build`, `git reset --hard`, `kubectl delete`, `DROP TABLE`
CAUTION	0	After 30s	`rm file.txt`, `git branch -d`, `npm uninstall`
SAFE	0	Immediately	`rm *.log`, `git stash`, `kubectl delete pod`

Quick Start

Installation

Recommended: Homebrew (macOS/Linux)

brew install dicklesworthstone/tap/slb

This method provides: - Automatic updates via brew upgrade - Dependency management - Easy uninstall via brew uninstall

Windows: Scoop

scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket
scoop install dicklesworthstone/slb

Alternative: Direct Download

Download the latest release for your platform: - Linux x86_64 - macOS Intel - macOS ARM - Windows

Alternative: Install Script

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/slb/main/scripts/install.sh?$(date +%s)" | bash

Build from Source

git clone https://github.com/Dicklesworthstone/slb.git
cd slb && make build

Go Install

go install github.com/Dicklesworthstone/slb/cmd/slb@latest

Initialize a Project

cd /path/to/your/project
slb init

This creates a .slb/ directory with: - state.db - SQLite database for requests, reviews, and sessions - config.toml - Project-specific configuration - pending/ - JSON files for pending requests (for watching/interop)

Basic Workflow

# 1. Start a session (as an AI agent)
slb session start --agent "GreenLake" --program "claude-code" --model "opus"
# Returns: session_id and session_key

# 2. Run a dangerous command (blocks until approved)
slb run "rm -rf ./build" --reason "Clean build artifacts before fresh compile" --session-id <id>

# 3. Another agent reviews and approves
slb pending                    # See what's waiting for review
slb review <request-id>        # View full details
slb approve <request-id> --session-id <reviewer-id> --comment "Looks safe"

# 4. Original command executes automatically after approval

Commands Reference

Session Management

slb session start --agent <name> --program <prog> --model <model>
slb session end --session-id <id>
slb session resume --agent <name>              # Resume after crash
slb session list                               # Show active sessions
slb session heartbeat --session-id <id>        # Keep session alive

Request & Run

# Primary command (atomic: check, request, wait, execute)
slb run "<command>" --reason "..." [--session-id <id>]

# Plumbing commands
slb request "<command>" --reason "..."         # Create request only
slb status <request-id> [--wait]               # Check status
slb pending [--all-projects]                   # List pending requests
slb cancel <request-id>                        # Cancel own request

Review & Approve

slb review <request-id>                        # Show full details
slb approve <request-id> --session-id <id>     # Approve request
slb reject <request-id> --session-id <id> --reason "..."

Execution

slb execute <request-id>                       # Execute approved request
slb emergency-execute "<cmd>" --reason "..."   # Human override (logged)
slb rollback <request-id>                      # Rollback if captured

Pattern Management

slb patterns list [--tier critical|dangerous|caution|safe]
slb patterns test "<command>"                  # Check what tier a command would be
slb patterns add --tier dangerous "<pattern>"  # Agents can add patterns

Daemon & TUI

slb daemon start [--foreground]                # Start background daemon
slb daemon stop                                # Stop daemon
slb daemon status                              # Check daemon status
slb tui                                        # Launch interactive TUI
slb watch --session-id <id> --json             # Stream events for agents

Configuration

Configuration is hierarchical (lowest to highest priority): 1. Built-in defaults 2. User config (~/.slb/config.toml) 3. Project config (.slb/config.toml) 4. Environment variables (SLB_*) 5. Command-line flags

Example Configuration

[general]
min_approvals = 2
request_timeout = 1800              # 30 minutes
approval_ttl_minutes = 30
timeout_action = "escalate"         # or "auto_reject", "auto_approve_warn"

[rate_limits]
max_pending_per_session = 5
max_requests_per_minute = 10

[notifications]
desktop_enabled = true
desktop_delay_seconds = 60

[daemon]
tcp_addr = ""                       # For Docker/remote agents
tcp_require_auth = true

Default Patterns

CRITICAL (2+ approvals)

Pattern	Description
`rm -rf /...`	Recursive delete on system paths
`DROP DATABASE/SCHEMA`	SQL database destruction
`TRUNCATE TABLE`	SQL data destruction
`terraform destroy`	Infrastructure destruction
`kubectl delete node/namespace/pv/pvc`	Kubernetes critical resources
`git push --force`	Force push (not with-lease)
`aws terminate-instances`	Cloud resource destruction
`dd ... of=/dev/`	Direct disk writes

DANGEROUS (1 approval)

Pattern	Description
`rm -rf`	Recursive force delete
`git reset --hard`	Discard all changes
`git clean -fd`	Remove untracked files
`kubectl delete`	Delete Kubernetes resources
`terraform destroy -target`	Targeted destroy
`DROP TABLE`	SQL table destruction
`chmod -R`, `chown -R`	Recursive permission changes

CAUTION (auto-approved after 30s)

Pattern	Description
`rm <file>`	Single file deletion
`git stash drop`	Discard stashed changes
`git branch -d`	Delete local branch
`npm/pip uninstall`	Package removal

SAFE (skip review)

Pattern	Description
`rm .log`, `rm .tmp`, `rm *.bak`	Temporary file cleanup
`git stash`	Stash changes (not drop)
`kubectl delete pod`	Pod deletion (pods are ephemeral)
`npm cache clean`	Cache cleanup

IDE Integration

Claude Code Hooks

Add to your AGENTS.md:

## SLB Integration

Before running any destructive command, use slb:

\`\`\`bash
# Instead of running directly:
rm -rf ./build

# Use slb:
slb run "rm -rf ./build" --reason "Clean build before fresh compile"
\`\`\`

All DANGEROUS and CRITICAL commands must go through slb review.

Generate Claude Code hooks:

slb integrations claude-hooks > ~/.claude/hooks.json

Cursor Rules

Generate Cursor rules:

slb integrations cursor-rules > .cursorrules

Shell Completions

# zsh (~/.zshrc)
eval "$(slb completion zsh)"

# bash (~/.bashrc)
eval "$(slb completion bash)"

# fish (~/.config/fish/config.fish)
slb completion fish | source

Architecture

.slb/
├── state.db          # SQLite database (source of truth)
├── config.toml       # Project configuration
├── pending/          # JSON snapshots for watching
│   └── req-<uuid>.json
├── sessions/         # Session files
└── logs/             # Execution logs
    └── req-<uuid>.log

Key Design Decision: Client-side execution. The daemon is a NOTARY (verifies approvals) not an executor. Commands execute in the calling process's shell environment to inherit: - AWS_PROFILE, AWS_ACCESS_KEY_ID - KUBECONFIG - Activated virtualenvs - SSH_AUTH_SOCK - Database connection strings

Troubleshooting

"Daemon not running" warning

This is expected - slb works without the daemon (file-based polling). Start the daemon for real-time updates:

slb daemon start

"Active session already exists"

Resume your existing session instead of starting a new one:

slb session resume --agent "YourAgent" --create-if-missing

Approval expired

Approvals have a TTL (30min default, 10min for CRITICAL). Re-request if expired:

slb run "<command>" --reason "..."  # Creates new request

Command hash mismatch

The command was modified after approval. This is a security feature - re-request approval for the modified command.

Safety Note

slb adds friction and peer review for dangerous actions. It does NOT replace: - Least-privilege credentials - Environment safeguards - Proper access controls - Backup strategies

Use slb as defense in depth, not your only protection.

Claude Code Hook Integration

To integrate with Claude Code, slb provides a PreToolUse hook that intercepts Bash commands before execution.

Quick Setup

# Install hook (generates script and updates Claude Code settings)
slb hook install

# Check installation status
slb hook status

# Test classification without executing
slb hook test "rm -rf ./build"

How It Works

Hook Script: A Python script at ~/.slb/hooks/slb_guard.py intercepts Bash tool calls
Pattern Matching: Commands are classified using embedded patterns (same as the daemon)
Daemon Communication: For approval checks, the hook connects to the SLB daemon via Unix socket
Fail-Closed: If SLB is unavailable, dangerous commands are blocked by default

Hook Commands

slb hook generate                 # Generate hook script only
slb hook install [--global]       # Install to Claude Code settings
slb hook uninstall                # Remove hook from settings
slb hook status                   # Show installation status
slb hook test "<command>"         # Test command classification

The hook returns one of three actions to Claude Code: - allow - Command proceeds without intervention - ask - User is prompted (CAUTION tier) - block - Command is blocked with message to use slb request

Pattern Matching Engine

The pattern matching engine is the core of slb's command classification system.

Classification Algorithm

Normalization: Commands are parsed using shell-aware tokenization
Strips wrapper prefixes: sudo, doas, env, time, nohup, etc.
Extracts inner commands from bash -c 'command' patterns
Resolves paths: ./foo → /absolute/path/foo
Compound Command Handling: Commands with ;, &&, ||, | are split and each segment is classified independently. The highest risk segment determines the overall tier. echo "done" && rm -rf /etc → CRITICAL (rm -rf /etc wins) ls && git status → SAFE (no dangerous patterns)
Shell-Aware Splitting: Separators inside quotes are preserved: psql -c "DELETE FROM users; DROP TABLE x;" → Single segment (SQL) echo "foo" && rm -rf /tmp → Two segments
Pattern Precedence: Patterns are checked in order: SAFE → CRITICAL → DANGEROUS → CAUTION
First match wins within each tier
SAFE patterns skip review entirely
Fail-Safe Parse Handling: If command parsing fails (unbalanced quotes, complex escapes), the tier is upgraded by one level:
SAFE → CAUTION
CAUTION → DANGEROUS
DANGEROUS → CRITICAL

Fallback Detection

For commands that wrap SQL (e.g., psql -c "...", mysql -e "..."), pattern matching may not catch embedded statements. The engine includes fallback detection:

DELETE FROM ... (no WHERE clause)  →  CRITICAL
DELETE FROM ... WHERE ...          →  DANGEROUS

Runtime Pattern Management

Agents can add patterns at runtime:

slb patterns add --tier dangerous "docker system prune"
slb patterns list --tier critical
slb patterns test "kubectl delete deployment nginx"

Pattern changes are persisted to SQLite and take effect immediately.

Request Lifecycle

Requests follow a well-defined state machine with strict transition rules.

State Diagram

```

Extension points exported contracts — how you extend this code

RequestNotifier (Interface)

RequestNotifier defines notification hooks for request lifecycle. [4 implementers]

internal/integrations/agentmail.go

CommandExecutor (Interface)

CommandExecutor abstracts command execution for testing. Production code can use RealExecutor, while tests can use MockE [3 …

internal/testutil/executor.go

WebhookNotifier (Interface)

WebhookNotifier handles webhook notifications. [1 implementers]

internal/daemon/notifications.go

Option (FuncType)

Option configures the Writer.

internal/output/output.go

SessionOption (FuncType)

SessionOption customizes a test session.

internal/testutil/fixtures.go

ClientOption (FuncType)

ClientOption configures a Client.

internal/daemon/client.go

RequestOption (FuncType)

RequestOption customizes a test request.

internal/testutil/fixtures.go

DesktopNotifier (Interface)

(no doc) [1 implementers]

internal/daemon/notifications.go

Core symbols most depended-on inside this repo

Error

called by 595

internal/core/ratelimit.go

Contains

called by 451

tests/e2e/harness/logging.go

Run

called by 422

internal/testutil/executor.go

internal/testutil/integration.go

Render

called by 196

internal/tui/components/table.go

MakeSession

called by 147

internal/testutil/fixtures.go

WriteFile

called by 146

internal/testutil/integration.go

Shape

Function 2,106

Method 452

Struct 216

TypeAlias 26

FuncType 5

Interface 4

Languages

Go100%

Modules by API surface

internal/tui/patterns/removal_test.go70 symbols

internal/tui/history/browser_test.go67 symbols

internal/tui/components/components_test.go66 symbols

internal/daemon/client_test.go64 symbols

internal/tui/request/request_test.go62 symbols

internal/tui/dashboard/dashboard_test.go59 symbols

internal/cli/watch_test.go48 symbols

internal/tui/tui_test.go46 symbols

internal/daemon/client.go39 symbols

internal/core/review_test.go34 symbols

internal/cli/run_test.go33 symbols

internal/tui/dashboard/model.go32 symbols

Datastores touched

dbDatabase · 1 repos

For agents

$ claude mcp add slb \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

github.com/Dicklesworthstone/slb @v0.3.1

Simultaneous Launch Button (slb)

Why This Exists

Key Features

Risk Tiers

Quick Start

Installation

Recommended: Homebrew (macOS/Linux)

Windows: Scoop

Alternative: Direct Download

Alternative: Install Script

Build from Source

Go Install

Initialize a Project

Basic Workflow

Commands Reference

Session Management

Request & Run

Review & Approve

Execution

Pattern Management

Daemon & TUI

Configuration

Example Configuration

Default Patterns

CRITICAL (2+ approvals)

DANGEROUS (1 approval)

CAUTION (auto-approved after 30s)

SAFE (skip review)

IDE Integration

Claude Code Hooks

Cursor Rules

Shell Completions

Architecture

Troubleshooting

"Daemon not running" warning

"Active session already exists"

Approval expired

Command hash mismatch

Safety Note

Claude Code Hook Integration

Quick Setup

How It Works

Hook Commands

Pattern Matching Engine

Classification Algorithm

Fallback Detection

Runtime Pattern Management

Request Lifecycle

State Diagram

Extension points exported contracts — how you extend this code

Core symbols most depended-on inside this repo

Shape

Languages

Modules by API surface

Datastores touched

For agents

Ask about this repo answers extend the page