{"id":34752579,"url":"https://github.com/dicklesworthstone/slb","last_synced_at":"2026-04-01T16:58:18.445Z","repository":{"id":328549349,"uuid":"1115948980","full_name":"Dicklesworthstone/slb","owner":"Dicklesworthstone","description":"Two-person rule CLI for AI coding agents: peer review and approval required before running potentially destructive commands","archived":false,"fork":false,"pushed_at":"2026-03-22T01:34:04.000Z","size":1546,"stargazers_count":64,"open_issues_count":0,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-22T17:06:56.726Z","etag":null,"topics":["ai-agents","cli","developer-tools","go","safety"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dicklesworthstone.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-13T22:04:16.000Z","updated_at":"2026-03-22T01:34:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Dicklesworthstone/slb","commit_stats":null,"previous_names":["dicklesworthstone/simultaneous_launch_button","dicklesworthstone/slb"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Dicklesworthstone/slb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fslb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fslb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fslb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fslb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dicklesworthstone","download_url":"https://codeload.github.com/Dicklesworthstone/slb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fslb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31013617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T02:58:54.984Z","status":"ssl_error","status_checked_at":"2026-03-27T02:58:46.993Z","response_time":164,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","cli","developer-tools","go","safety"],"created_at":"2025-12-25T05:26:27.350Z","updated_at":"2026-03-27T03:01:10.291Z","avatar_url":"https://github.com/Dicklesworthstone.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simultaneous Launch Button (slb)\n\n[![Go Version](https://img.shields.io/badge/go-1.21+-blue.svg)](https://golang.org)\n[![License](https://img.shields.io/badge/License-MIT%2BOpenAI%2FAnthropic%20Rider-blue.svg)](LICENSE)\n[![Build Status](https://github.com/Dicklesworthstone/slb/workflows/CI/badge.svg)](https://github.com/Dicklesworthstone/slb/actions)\n\nA cross-platform CLI that implements a **two-person rule** for running potentially destructive commands from AI coding agents.\n\nWhen 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.\n\n## Why This Exists\n\nCoding agents can get tunnel vision, hallucinate, or misunderstand context. A second reviewer (ideally with a different model/tooling) catches mistakes before they become irreversible.\n\n`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.\n\n## Key Features\n\n- **Risk-Based Classification**: Commands are automatically classified by risk level\n- **Client-Side Execution**: Commands run in YOUR shell environment (inheriting AWS credentials, kubeconfig, virtualenvs, etc.)\n- **Command Hash Binding**: Approvals bind to the exact command via SHA-256 hash\n- **SQLite Source of Truth**: Project state lives in `.slb/state.db`\n- **Agent Mail Integration**: Notify reviewers and track audit trails via MCP Agent Mail\n- **TUI Dashboard**: Interactive terminal UI for human reviewers\n\n## Risk Tiers\n\n| Tier | Approvals | Auto-approve | Examples |\n|------|-----------|--------------|----------|\n| **CRITICAL** | 2+ | Never | `rm -rf /`, `DROP DATABASE`, `terraform destroy`, `git push --force` |\n| **DANGEROUS** | 1 | Never | `rm -rf ./build`, `git reset --hard`, `kubectl delete`, `DROP TABLE` |\n| **CAUTION** | 0 | After 30s | `rm file.txt`, `git branch -d`, `npm uninstall` |\n| **SAFE** | 0 | Immediately | `rm *.log`, `git stash`, `kubectl delete pod` |\n\n## Quick Start\n\n### Installation\n\n#### Recommended: Homebrew (macOS/Linux)\n\n```bash\nbrew install dicklesworthstone/tap/slb\n```\n\nThis method provides:\n- Automatic updates via `brew upgrade`\n- Dependency management\n- Easy uninstall via `brew uninstall`\n\n#### Windows: Scoop\n\n```powershell\nscoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket\nscoop install dicklesworthstone/slb\n```\n\n#### Alternative: Direct Download\n\nDownload the latest release for your platform:\n- [Linux x86_64](https://github.com/Dicklesworthstone/slb/releases/latest/download/slb-linux-amd64)\n- [macOS Intel](https://github.com/Dicklesworthstone/slb/releases/latest/download/slb-darwin-amd64)\n- [macOS ARM](https://github.com/Dicklesworthstone/slb/releases/latest/download/slb-darwin-arm64)\n- [Windows](https://github.com/Dicklesworthstone/slb/releases/latest/download/slb-windows-amd64.exe)\n\n#### Alternative: Install Script\n\n```bash\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/slb/main/scripts/install.sh?$(date +%s)\" | bash\n```\n\n#### Build from Source\n\n```bash\ngit clone https://github.com/Dicklesworthstone/slb.git\ncd slb \u0026\u0026 make build\n```\n\n#### Go Install\n\n```bash\ngo install github.com/Dicklesworthstone/slb/cmd/slb@latest\n```\n\n### Initialize a Project\n\n```bash\ncd /path/to/your/project\nslb init\n```\n\nThis creates a `.slb/` directory with:\n- `state.db` - SQLite database for requests, reviews, and sessions\n- `config.toml` - Project-specific configuration\n- `pending/` - JSON files for pending requests (for watching/interop)\n\n### Basic Workflow\n\n```bash\n# 1. Start a session (as an AI agent)\nslb session start --agent \"GreenLake\" --program \"claude-code\" --model \"opus\"\n# Returns: session_id and session_key\n\n# 2. Run a dangerous command (blocks until approved)\nslb run \"rm -rf ./build\" --reason \"Clean build artifacts before fresh compile\" --session-id \u003cid\u003e\n\n# 3. Another agent reviews and approves\nslb pending                    # See what's waiting for review\nslb review \u003crequest-id\u003e        # View full details\nslb approve \u003crequest-id\u003e --session-id \u003creviewer-id\u003e --comment \"Looks safe\"\n\n# 4. Original command executes automatically after approval\n```\n\n## Commands Reference\n\n### Session Management\n\n```bash\nslb session start --agent \u003cname\u003e --program \u003cprog\u003e --model \u003cmodel\u003e\nslb session end --session-id \u003cid\u003e\nslb session resume --agent \u003cname\u003e              # Resume after crash\nslb session list                               # Show active sessions\nslb session heartbeat --session-id \u003cid\u003e        # Keep session alive\n```\n\n### Request \u0026 Run\n\n```bash\n# Primary command (atomic: check, request, wait, execute)\nslb run \"\u003ccommand\u003e\" --reason \"...\" [--session-id \u003cid\u003e]\n\n# Plumbing commands\nslb request \"\u003ccommand\u003e\" --reason \"...\"         # Create request only\nslb status \u003crequest-id\u003e [--wait]               # Check status\nslb pending [--all-projects]                   # List pending requests\nslb cancel \u003crequest-id\u003e                        # Cancel own request\n```\n\n### Review \u0026 Approve\n\n```bash\nslb review \u003crequest-id\u003e                        # Show full details\nslb approve \u003crequest-id\u003e --session-id \u003cid\u003e     # Approve request\nslb reject \u003crequest-id\u003e --session-id \u003cid\u003e --reason \"...\"\n```\n\n### Execution\n\n```bash\nslb execute \u003crequest-id\u003e                       # Execute approved request\nslb emergency-execute \"\u003ccmd\u003e\" --reason \"...\"   # Human override (logged)\nslb rollback \u003crequest-id\u003e                      # Rollback if captured\n```\n\n### Pattern Management\n\n```bash\nslb patterns list [--tier critical|dangerous|caution|safe]\nslb patterns test \"\u003ccommand\u003e\"                  # Check what tier a command would be\nslb patterns add --tier dangerous \"\u003cpattern\u003e\"  # Agents can add patterns\n```\n\n### Daemon \u0026 TUI\n\n```bash\nslb daemon start [--foreground]                # Start background daemon\nslb daemon stop                                # Stop daemon\nslb daemon status                              # Check daemon status\nslb tui                                        # Launch interactive TUI\nslb watch --session-id \u003cid\u003e --json             # Stream events for agents\n```\n\n## Configuration\n\nConfiguration is hierarchical (lowest to highest priority):\n1. Built-in defaults\n2. User config (`~/.slb/config.toml`)\n3. Project config (`.slb/config.toml`)\n4. Environment variables (`SLB_*`)\n5. Command-line flags\n\n### Example Configuration\n\n```toml\n[general]\nmin_approvals = 2\nrequest_timeout = 1800              # 30 minutes\napproval_ttl_minutes = 30\ntimeout_action = \"escalate\"         # or \"auto_reject\", \"auto_approve_warn\"\n\n[rate_limits]\nmax_pending_per_session = 5\nmax_requests_per_minute = 10\n\n[notifications]\ndesktop_enabled = true\ndesktop_delay_seconds = 60\n\n[daemon]\ntcp_addr = \"\"                       # For Docker/remote agents\ntcp_require_auth = true\n```\n\n## Default Patterns\n\n### CRITICAL (2+ approvals)\n\n| Pattern | Description |\n|---------|-------------|\n| `rm -rf /...` | Recursive delete on system paths |\n| `DROP DATABASE/SCHEMA` | SQL database destruction |\n| `TRUNCATE TABLE` | SQL data destruction |\n| `terraform destroy` | Infrastructure destruction |\n| `kubectl delete node/namespace/pv/pvc` | Kubernetes critical resources |\n| `git push --force` | Force push (not with-lease) |\n| `aws terminate-instances` | Cloud resource destruction |\n| `dd ... of=/dev/` | Direct disk writes |\n\n### DANGEROUS (1 approval)\n\n| Pattern | Description |\n|---------|-------------|\n| `rm -rf` | Recursive force delete |\n| `git reset --hard` | Discard all changes |\n| `git clean -fd` | Remove untracked files |\n| `kubectl delete` | Delete Kubernetes resources |\n| `terraform destroy -target` | Targeted destroy |\n| `DROP TABLE` | SQL table destruction |\n| `chmod -R`, `chown -R` | Recursive permission changes |\n\n### CAUTION (auto-approved after 30s)\n\n| Pattern | Description |\n|---------|-------------|\n| `rm \u003cfile\u003e` | Single file deletion |\n| `git stash drop` | Discard stashed changes |\n| `git branch -d` | Delete local branch |\n| `npm/pip uninstall` | Package removal |\n\n### SAFE (skip review)\n\n| Pattern | Description |\n|---------|-------------|\n| `rm *.log`, `rm *.tmp`, `rm *.bak` | Temporary file cleanup |\n| `git stash` | Stash changes (not drop) |\n| `kubectl delete pod` | Pod deletion (pods are ephemeral) |\n| `npm cache clean` | Cache cleanup |\n\n## IDE Integration\n\n### Claude Code Hooks\n\nAdd to your `AGENTS.md`:\n\n```markdown\n## SLB Integration\n\nBefore running any destructive command, use slb:\n\n\\`\\`\\`bash\n# Instead of running directly:\nrm -rf ./build\n\n# Use slb:\nslb run \"rm -rf ./build\" --reason \"Clean build before fresh compile\"\n\\`\\`\\`\n\nAll DANGEROUS and CRITICAL commands must go through slb review.\n```\n\nGenerate Claude Code hooks:\n\n```bash\nslb integrations claude-hooks \u003e ~/.claude/hooks.json\n```\n\n### Cursor Rules\n\nGenerate Cursor rules:\n\n```bash\nslb integrations cursor-rules \u003e .cursorrules\n```\n\n## Shell Completions\n\n```bash\n# zsh (~/.zshrc)\neval \"$(slb completion zsh)\"\n\n# bash (~/.bashrc)\neval \"$(slb completion bash)\"\n\n# fish (~/.config/fish/config.fish)\nslb completion fish | source\n```\n\n## Architecture\n\n```\n.slb/\n├── state.db          # SQLite database (source of truth)\n├── config.toml       # Project configuration\n├── pending/          # JSON snapshots for watching\n│   └── req-\u003cuuid\u003e.json\n├── sessions/         # Session files\n└── logs/             # Execution logs\n    └── req-\u003cuuid\u003e.log\n```\n\n**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:\n- AWS_PROFILE, AWS_ACCESS_KEY_ID\n- KUBECONFIG\n- Activated virtualenvs\n- SSH_AUTH_SOCK\n- Database connection strings\n\n## Troubleshooting\n\n### \"Daemon not running\" warning\n\nThis is expected - slb works without the daemon (file-based polling). Start the daemon for real-time updates:\n\n```bash\nslb daemon start\n```\n\n### \"Active session already exists\"\n\nResume your existing session instead of starting a new one:\n\n```bash\nslb session resume --agent \"YourAgent\" --create-if-missing\n```\n\n### Approval expired\n\nApprovals have a TTL (30min default, 10min for CRITICAL). Re-request if expired:\n\n```bash\nslb run \"\u003ccommand\u003e\" --reason \"...\"  # Creates new request\n```\n\n### Command hash mismatch\n\nThe command was modified after approval. This is a security feature - re-request approval for the modified command.\n\n## Safety Note\n\n`slb` adds friction and peer review for dangerous actions. It does NOT replace:\n- Least-privilege credentials\n- Environment safeguards\n- Proper access controls\n- Backup strategies\n\nUse slb as **defense in depth**, not your only protection.\n\n## Claude Code Hook Integration\n\nTo integrate with Claude Code, `slb` provides a PreToolUse hook that intercepts Bash commands before execution.\n\n### Quick Setup\n\n```bash\n# Install hook (generates script and updates Claude Code settings)\nslb hook install\n\n# Check installation status\nslb hook status\n\n# Test classification without executing\nslb hook test \"rm -rf ./build\"\n```\n\n### How It Works\n\n1. **Hook Script**: A Python script at `~/.slb/hooks/slb_guard.py` intercepts Bash tool calls\n2. **Pattern Matching**: Commands are classified using embedded patterns (same as the daemon)\n3. **Daemon Communication**: For approval checks, the hook connects to the SLB daemon via Unix socket\n4. **Fail-Closed**: If SLB is unavailable, dangerous commands are blocked by default\n\n### Hook Commands\n\n```bash\nslb hook generate                 # Generate hook script only\nslb hook install [--global]       # Install to Claude Code settings\nslb hook uninstall                # Remove hook from settings\nslb hook status                   # Show installation status\nslb hook test \"\u003ccommand\u003e\"         # Test command classification\n```\n\nThe hook returns one of three actions to Claude Code:\n- `allow` - Command proceeds without intervention\n- `ask` - User is prompted (CAUTION tier)\n- `block` - Command is blocked with message to use `slb request`\n\n## Pattern Matching Engine\n\nThe pattern matching engine is the core of `slb`'s command classification system.\n\n### Classification Algorithm\n\n1. **Normalization**: Commands are parsed using shell-aware tokenization\n   - Strips wrapper prefixes: `sudo`, `doas`, `env`, `time`, `nohup`, etc.\n   - Extracts inner commands from `bash -c 'command'` patterns\n   - Resolves paths: `./foo` → `/absolute/path/foo`\n\n2. **Compound Command Handling**: Commands with `;`, `\u0026\u0026`, `||`, `|` are split and each segment is classified independently. The **highest risk segment determines the overall tier**.\n   ```\n   echo \"done\" \u0026\u0026 rm -rf /etc    →  CRITICAL (rm -rf /etc wins)\n   ls \u0026\u0026 git status              →  SAFE (no dangerous patterns)\n   ```\n\n3. **Shell-Aware Splitting**: Separators inside quotes are preserved:\n   ```\n   psql -c \"DELETE FROM users; DROP TABLE x;\"  →  Single segment (SQL)\n   echo \"foo\" \u0026\u0026 rm -rf /tmp                   →  Two segments\n   ```\n\n4. **Pattern Precedence**: Patterns are checked in order: SAFE → CRITICAL → DANGEROUS → CAUTION\n   - First match wins within each tier\n   - SAFE patterns skip review entirely\n\n5. **Fail-Safe Parse Handling**: If command parsing fails (unbalanced quotes, complex escapes), the tier is **upgraded by one level**:\n   - SAFE → CAUTION\n   - CAUTION → DANGEROUS\n   - DANGEROUS → CRITICAL\n\n### Fallback Detection\n\nFor commands that wrap SQL (e.g., `psql -c \"...\"`, `mysql -e \"...\"`), pattern matching may not catch embedded statements. The engine includes fallback detection:\n\n```\nDELETE FROM ... (no WHERE clause)  →  CRITICAL\nDELETE FROM ... WHERE ...          →  DANGEROUS\n```\n\n### Runtime Pattern Management\n\nAgents can add patterns at runtime:\n\n```bash\nslb patterns add --tier dangerous \"docker system prune\"\nslb patterns list --tier critical\nslb patterns test \"kubectl delete deployment nginx\"\n```\n\nPattern changes are persisted to SQLite and take effect immediately.\n\n## Request Lifecycle\n\nRequests follow a well-defined state machine with strict transition rules.\n\n### State Diagram\n\n```\n                    ┌─────────────┐\n                    │   PENDING   │\n                    └──────┬──────┘\n           ┌───────────────┼───────────────┐───────────────┐\n           ▼               ▼               ▼               ▼\n     ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐\n     │ APPROVED │    │ REJECTED │    │ CANCELLED│    │ TIMEOUT  │\n     └────┬─────┘    └──────────┘    └──────────┘    └────┬─────┘\n          │              (terminal)      (terminal)       │\n          ▼                                               ▼\n     ┌──────────┐                                   ┌──────────┐\n     │EXECUTING │                                   │ESCALATED │\n     └────┬─────┘                                   └────┬─────┘\n          │                                              │\n   ┌──────┴──────┬──────────┐                 ┌─────────┴─────────┐\n   ▼             ▼          ▼                 ▼                   ▼\n┌────────┐  ┌─────────┐  ┌────────┐      ┌──────────┐       ┌──────────┐\n│EXECUTED│  │EXEC_FAIL│  │TIMED_OUT│     │ APPROVED │       │ REJECTED │\n└────────┘  └─────────┘  └────────┘      └──────────┘       └──────────┘\n(terminal)   (terminal)   (terminal)\n```\n\n### Terminal States\n\nOnce a request reaches a terminal state, no further transitions are allowed:\n- **EXECUTED**: Command completed successfully\n- **EXECUTION_FAILED**: Command returned non-zero exit code\n- **TIMED_OUT**: Command exceeded execution timeout\n- **CANCELLED**: Request was cancelled by the requester\n- **REJECTED**: Request was rejected by a reviewer\n\n### Approval TTL\n\nApprovals have a time-to-live to prevent stale approvals:\n- **Standard requests**: 30 minutes (configurable)\n- **CRITICAL requests**: 10 minutes (stricter by default)\n\nIf an approval expires before execution, the request must be re-approved.\n\n## Execution Verification\n\nBefore any command executes, five security gates must pass:\n\n### Gate 1: Status Check\nRequest must be in APPROVED state.\n\n### Gate 2: Approval Expiry\nApproval TTL must not have elapsed.\n\n### Gate 3: Command Hash\nSHA-256 hash of the command must match. This ensures the exact approved command is executed, with no modifications allowed after approval.\n\n### Gate 4: Tier Consistency\nRisk tier must still match (patterns may have changed since approval).\n\n### Gate 5: First-Executor-Wins\nOnly one executor can claim the request. Atomic database transition prevents race conditions when multiple agents try to execute.\n\n## Dry Run \u0026 Rollback\n\n### Dry Run Pre-flight\n\nFor supported commands, `slb` can run a dry-run variant before the real execution:\n\n```bash\n# Supported dry-run variants:\nterraform plan          # instead of terraform apply\nkubectl diff            # instead of kubectl apply\ngit diff                # show what would change\n```\n\nEnable in config:\n```toml\n[general]\nenable_dry_run = true\n```\n\n### Rollback State Capture\n\nBefore executing, `slb` can capture state for potential rollback:\n\n```toml\n[general]\nenable_rollback_capture = true\nmax_rollback_size_mb = 100\n```\n\nCaptured state includes:\n- **Filesystem**: Tar archive of affected paths\n- **Git**: HEAD commit, branch, dirty state, untracked files\n- **Kubernetes**: YAML manifests of affected resources\n\nRollback:\n```bash\nslb rollback \u003crequest-id\u003e           # Restore captured state\nslb rollback \u003crequest-id\u003e --force   # Force overwrite\n```\n\n## Daemon Architecture\n\nThe daemon provides real-time notifications and execution verification.\n\n### IPC Communication\n\nPrimary communication uses Unix domain sockets:\n```\n/tmp/slb-\u003chash\u003e.sock\n```\n\nThe socket path includes a hash derived from the project path, allowing multiple project daemons to coexist.\n\n### JSON-RPC Protocol\n\nAll daemon communication uses JSON-RPC 2.0:\n\n```json\n{\"jsonrpc\": \"2.0\", \"method\": \"hook_query\", \"params\": {\"command\": \"rm -rf /\"}, \"id\": 1}\n```\n\nAvailable methods:\n- `hook_query` - Classify command and check approvals\n- `hook_health` - Health check with pattern hash\n- `verify_execution` - Check execution gates\n- `subscribe` - Subscribe to request events\n\n### TCP Mode (Docker/Remote)\n\nFor agents in containers or remote machines:\n\n```toml\n[daemon]\ntcp_addr = \"0.0.0.0:9876\"\ntcp_require_auth = true\ntcp_allowed_ips = [\"192.168.1.0/24\"]\n```\n\n### Timeout Handling\n\nWhen a request's approval window expires:\n\n| Action | Behavior |\n|--------|----------|\n| `escalate` | Transition to ESCALATED, notify humans (default) |\n| `auto_reject` | Automatically reject the request |\n| `auto_approve_warn` | Auto-approve CAUTION tier with warning notification |\n\n```toml\n[general]\ntimeout_action = \"escalate\"\n```\n\n### Desktop Notifications\n\nNative notifications on macOS (AppleScript), Linux (notify-send), and Windows (PowerShell):\n\n```toml\n[notifications]\ndesktop_enabled = true\ndesktop_delay_seconds = 60    # Wait before first notification\n```\n\n## Advanced Configuration\n\n### Cross-Project Reviews\n\nAllow reviewers from other projects:\n\n```toml\n[general]\ncross_project_reviews = true\nreview_pool = [\"agent-a\", \"agent-b\", \"human-reviewer\"]\n```\n\n### Trusted Self-Approval\n\nDesignated agents can self-approve after a delay:\n\n```toml\n[agents]\ntrusted_self_approve = [\"senior-agent\", \"lead-developer\"]\ntrusted_self_approve_delay_seconds = 300    # 5 minute delay\n```\n\n### Conflict Resolution\n\nWhen approvals and rejections conflict:\n\n```toml\n[general]\nconflict_resolution = \"any_rejection_blocks\"  # Default\n# Options: any_rejection_blocks | first_wins | human_breaks_tie\n```\n\n### Different Model Requirement\n\nRequire reviewers to use a different AI model:\n\n```toml\n[general]\nrequire_different_model = true\ndifferent_model_timeout = 300    # Escalate to human after 5 min\n```\n\n### Rate Limiting\n\nPrevent request floods:\n\n```toml\n[rate_limits]\nmax_pending_per_session = 5      # Max concurrent pending requests\nmax_requests_per_minute = 10     # Rate limit per session\nrate_limit_action = \"reject\"     # reject | queue | warn\n```\n\n### Dynamic Quorum\n\nScale approval requirements based on active reviewers:\n\n```toml\n[patterns.critical]\ndynamic_quorum = true\ndynamic_quorum_floor = 2    # Minimum approvals even with few reviewers\n```\n\n### Webhook Notifications\n\nSend events to external systems:\n\n```toml\n[notifications]\nwebhook_url = \"https://slack.com/webhook/...\"\n```\n\nPayload includes request details, classification, and event type.\n\n## Security Design Principles\n\n### Defense in Depth\n\n`slb` implements multiple security layers:\n\n1. **Pattern-based classification** - First line of defense\n2. **Peer review requirement** - Human/agent oversight\n3. **Command hash binding** - Tamper detection\n4. **Approval TTL** - Prevent stale approvals\n5. **Execution verification gates** - Pre-execution checks\n6. **Audit logging** - Full traceability\n\n### Cryptographic Guarantees\n\n- **Command binding**: SHA-256 hash computed at request time, verified at execution\n- **Review signatures**: HMAC signatures using session keys prevent review forgery\n- **Session keys**: Generated per-session, never stored in plaintext\n\n### Fail-Closed Behavior\n\nWhen components fail:\n- Daemon unreachable → Block dangerous commands (hook)\n- Parse error → Upgrade tier by one level\n- Approval expired → Require new approval\n- Hash mismatch → Reject execution\n\n### Audit Trail\n\nEvery action is logged to SQLite with:\n- Timestamp\n- Actor (session ID, agent name)\n- Action type\n- Request/review details\n- Outcome\n\nQuery history:\n```bash\nslb history [--days 7] [--session \u003cid\u003e] [--status executed]\n```\n\n## Environment Variables\n\nAll config options can be set via environment:\n\n| Variable | Description |\n|----------|-------------|\n| `SLB_MIN_APPROVALS` | Minimum approval count |\n| `SLB_REQUEST_TIMEOUT` | Request timeout in seconds |\n| `SLB_TIMEOUT_ACTION` | What to do on timeout |\n| `SLB_DESKTOP_NOTIFICATIONS` | Enable desktop notifications |\n| `SLB_WEBHOOK_URL` | Webhook notification URL |\n| `SLB_DAEMON_TCP_ADDR` | TCP listen address |\n| `SLB_TRUSTED_SELF_APPROVE` | Comma-separated trusted agents |\n\n## Agent Event Streaming\n\nThe `slb watch` command provides real-time event streaming for agent workflows.\n\n### Event Stream Format\n\nEvents are streamed as newline-delimited JSON (NDJSON) for easy programmatic consumption:\n\n```bash\nslb watch --session-id \u003cid\u003e\n```\n\nOutput:\n```json\n{\"type\":\"request_pending\",\"request_id\":\"abc123\",\"tier\":\"dangerous\",\"command\":\"rm -rf ./build\",\"ts\":\"...\"}\n{\"type\":\"request_approved\",\"request_id\":\"abc123\",\"reviewer\":\"BlueLake\",\"ts\":\"...\"}\n{\"type\":\"request_executed\",\"request_id\":\"abc123\",\"exit_code\":0,\"ts\":\"...\"}\n```\n\n### Event Types\n\n| Event | Description |\n|-------|-------------|\n| `request_pending` | New request awaiting approval |\n| `request_approved` | Request was approved |\n| `request_rejected` | Request was rejected |\n| `request_executed` | Approved request was executed |\n| `request_timeout` | Request timed out waiting for approval |\n| `request_cancelled` | Request was cancelled |\n\n### Transport Modes\n\n**Daemon IPC (preferred)**: Real-time streaming via Unix socket subscription when the daemon is running.\n\n**Polling fallback**: If the daemon is unavailable, the command falls back to database polling at configurable intervals:\n\n```bash\nslb watch --poll-interval 5s\n```\n\n### Auto-Approve Mode\n\nFor reviewer agents, auto-approve CAUTION tier requests:\n\n```bash\nslb watch --session-id \u003cid\u003e --auto-approve-caution\n```\n\n## Request Attachments\n\nRequests can include attachments to provide context for reviewers.\n\n### Attachment Types\n\n| Type | Description |\n|------|-------------|\n| `file` | File contents (base64 encoded) |\n| `image` | Screenshots or diagrams (validated dimensions) |\n| `command_output` | Output from context-gathering commands |\n\n### Adding Attachments\n\n```bash\n# Attach file\nslb request \"DROP TABLE users\" --reason \"...\" --attach ./schema.sql\n\n# Attach image (screenshot)\nslb request \"kubectl delete deployment\" --reason \"...\" --attach ./dashboard.png\n\n# Attach command output\nslb request \"terraform destroy\" --reason \"...\" --attach-cmd \"terraform plan -destroy\"\n```\n\n### Attachment Limits\n\n```toml\n[attachments]\nmax_file_size = 1048576        # 1MB\nmax_output_size = 102400       # 100KB\nmax_command_runtime = 10       # seconds\nmax_image_dimension = 4096     # pixels\n```\n\n### Viewing Attachments\n\n```bash\nslb show \u003crequest-id\u003e --with-attachments\n```\n\n## Session Management\n\nSessions track agent identity and activity for audit and coordination.\n\n### Session Lifecycle\n\n```bash\n# Start session (creates session_key for signing)\nslb session start --agent \"GreenLake\" --program \"claude-code\" --model \"opus\"\n\n# Resume after crash (preserves session_key)\nslb session resume --agent \"GreenLake\" --create-if-missing\n\n# Force resume (ends mismatched session)\nslb session resume --agent \"GreenLake\" --force\n\n# Heartbeat (update last_active for GC)\nslb session heartbeat --session-id \u003cid\u003e\n\n# End session gracefully\nslb session end --session-id \u003cid\u003e\n```\n\n### Session Garbage Collection\n\nClean up stale sessions from crashed agents:\n\n```bash\n# Show what would be cleaned (dry run)\nslb session gc --dry-run --threshold 30m\n\n# Clean sessions inactive \u003e 2 hours\nslb session gc --threshold 2h --force\n\n# Interactive cleanup (prompts for each)\nslb session gc --threshold 1h\n```\n\n### Rate Limit Reset\n\nReset rate limits for a session (admin use):\n\n```bash\nslb session reset-limits --session-id \u003cid\u003e\n```\n\n## Emergency Override\n\nFor true emergencies, humans can bypass the approval process with extensive logging.\n\n### Usage\n\n```bash\n# Interactive (prompts for confirmation)\nslb emergency-execute \"rm -rf /tmp/broken\" --reason \"System emergency: disk full\"\n\n# Non-interactive (requires hash acknowledgment)\nHASH=$(echo -n \"rm -rf /tmp/broken\" | sha256sum | cut -d' ' -f1)\nslb emergency-execute \"rm -rf /tmp/broken\" --reason \"Emergency\" --yes --ack $HASH\n```\n\n### Safeguards\n\n1. **Mandatory reason**: Must provide `--reason` explaining the bypass\n2. **Hash acknowledgment**: Non-interactive use requires command hash via `--ack`\n3. **Extensive logging**: Command, reason, timestamp, and operator identity logged\n4. **Rollback capture**: Optional state capture with `--capture-rollback`\n\n### Audit Entry\n\nEmergency executions create a permanent audit record:\n\n```json\n{\n  \"type\": \"emergency_execute\",\n  \"command\": \"rm -rf /tmp/broken\",\n  \"command_hash\": \"abc123...\",\n  \"reason\": \"System emergency: disk full\",\n  \"operator\": \"human\",\n  \"timestamp\": \"2026-01-03T10:30:00Z\",\n  \"exit_code\": 0\n}\n```\n\n## Outcome Tracking\n\nRecord execution feedback to improve pattern classification over time.\n\n### Recording Outcomes\n\nAfter execution, record whether the command caused problems:\n\n```bash\n# No problems\nslb outcome record \u003crequest-id\u003e\n\n# Problems occurred\nslb outcome record \u003crequest-id\u003e --problems --description \"Deleted wrong files\"\n\n# With rating and notes\nslb outcome record \u003crequest-id\u003e --rating 4 --notes \"Worked as expected\"\n```\n\n### Viewing Outcomes\n\n```bash\n# List recent outcomes\nslb outcome list\n\n# Only problematic executions\nslb outcome list --problems-only --limit 50\n\n# Statistics summary\nslb outcome stats\n```\n\n### Statistics Output\n\n```json\n{\n  \"total_executions\": 150,\n  \"problematic\": 3,\n  \"success_rate\": 0.98,\n  \"by_tier\": {\n    \"critical\": {\"total\": 10, \"problems\": 1},\n    \"dangerous\": {\"total\": 50, \"problems\": 2},\n    \"caution\": {\"total\": 90, \"problems\": 0}\n  }\n}\n```\n\nThis data enables:\n- Identifying patterns that should be upgraded/downgraded\n- Detecting agents that frequently cause problems\n- Improving justification quality requirements\n\n## TUI Dashboard\n\nThe interactive terminal UI gives human reviewers an at-a-glance view of pending requests and agent activity.\n\n### Launching\n\n```bash\nslb tui\n```\n\n### Layout\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│  SLB Dashboard                                                       │\n├─────────────────┬───────────────────────────────────────────────────┤\n│  AGENTS         │  PENDING REQUESTS                                  │\n│  ───────        │  ────────────────                                  │\n│▸ GreenLake      │▸ abc123 CRITICAL rm -rf /etc      BlueLake 2m     │\n│  BlueLake       │  def456 DANGEROUS git reset --hard GreenLake 5m   │\n│  RedStone       │  ghi789 CAUTION   npm uninstall   RedStone 10m    │\n│                 │                                                    │\n├─────────────────┴───────────────────────────────────────────────────┤\n│  ACTIVITY                                                            │\n│  ────────                                                            │\n│  10:30:15 GreenLake approved abc123                                  │\n│  10:28:42 BlueLake requested def456 (DANGEROUS)                      │\n│  10:25:00 RedStone executed xyz999 (exit 0)                          │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n### Keyboard Navigation\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Cycle focus between panels |\n| `↑/↓` | Navigate within panel |\n| `Enter` | View selected request details |\n| `a` | Approve selected request |\n| `r` | Reject selected request |\n| `p` | Open pattern management |\n| `h` | Open history view |\n| `q` | Quit |\n\n### Panel Details\n\n**Agents Panel**: Active sessions with last activity time and pending request count.\n\n**Pending Panel**: Requests awaiting approval, sorted by urgency (CRITICAL first).\n\n**Activity Panel**: Real-time feed of approvals, rejections, and executions.\n\n## History \u0026 Search\n\nBrowse and search the full audit history.\n\n### Full-Text Search\n\n```bash\n# Search commands\nslb history -q \"rm -rf\"\n\n# Search with filters\nslb history -q \"database\" --tier critical --status executed\n```\n\n### Filtering\n\n```bash\n# By status\nslb history --status pending|approved|rejected|executed|cancelled\n\n# By tier\nslb history --tier critical|dangerous|caution|safe\n\n# By agent\nslb history --agent \"GreenLake\"\n\n# By date\nslb history --since 2026-01-01\nslb history --since 2026-01-03T10:00:00Z\n\n# Combined\nslb history --tier critical --status executed --since 2026-01-01 --limit 100\n```\n\n### Detailed View\n\n```bash\n# Show full request details\nslb show \u003crequest-id\u003e\n\n# Include all information\nslb show \u003crequest-id\u003e --with-reviews --with-execution --with-attachments\n```\n\n## Agent Mail Integration\n\nSLB integrates with MCP Agent Mail for cross-agent notifications.\n\n### Configuration\n\n```toml\n[integrations]\nagent_mail_enabled = true\nagent_mail_thread = \"SLB-Reviews\"    # Default thread for notifications\n```\n\n### Notification Events\n\n| Event | Thread | Importance |\n|-------|--------|------------|\n| New CRITICAL request | SLB-Reviews | urgent |\n| New DANGEROUS request | SLB-Reviews | normal |\n| Request approved | SLB-Reviews | normal |\n| Request rejected | SLB-Reviews | normal |\n| Request executed | SLB-Reviews | low |\n| Request timeout/escalation | SLB-Reviews | urgent |\n\n### Message Format\n\nNew request notification:\n```markdown\n## Command Approval Request\n\n**ID**: abc123\n**Risk**: CRITICAL\n**Command**: `rm -rf /etc`\n\n### Justification\n- Reason: Emergency cleanup\n- Expected: Remove config files\n- Goal: Reset system state\n- Safety: Backed up to S3\n\n---\nTo review: `slb review abc123`\nTo approve: `slb approve abc123 --session-id \u003cyour-session\u003e`\n```\n\n### Manual Notification\n\nForce send notification for a request:\n\n```bash\nslb notify \u003crequest-id\u003e --via agent-mail\n```\n\n## Output Formats\n\nAll commands support structured output for programmatic use.\n\n### JSON Mode\n\n```bash\n# Global flag\nslb --output json pending\n\n# Per-command\nslb pending --json\nslb history --json\nslb session list --json\n```\n\n### Output Examples\n\n**Pending requests (JSON)**:\n```json\n{\n  \"requests\": [\n    {\n      \"id\": \"abc123\",\n      \"status\": \"pending\",\n      \"tier\": \"critical\",\n      \"command\": \"rm -rf /etc\",\n      \"requestor\": \"GreenLake\",\n      \"created_at\": \"2026-01-03T10:00:00Z\",\n      \"approvals\": 0,\n      \"required_approvals\": 2\n    }\n  ],\n  \"count\": 1\n}\n```\n\n**Session start (JSON)**:\n```json\n{\n  \"session_id\": \"sess_abc123\",\n  \"session_key\": \"key_xyz789\",\n  \"agent_name\": \"GreenLake\",\n  \"program\": \"claude-code\",\n  \"model\": \"opus\",\n  \"project_path\": \"/home/user/myproject\",\n  \"started_at\": \"2026-01-03T10:00:00Z\"\n}\n```\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | General error |\n| 2 | Invalid arguments |\n| 3 | Request not found |\n| 4 | Permission denied |\n| 5 | Timeout |\n| 6 | Rate limited |\n\n## Planning \u0026 Development\n\n- Design doc: `PLAN_TO_MAKE_SLB.md`\n- Agent rules: `AGENTS.md`\n- Task tracking: `bd ready` (beads)\n- Prioritization: `bv --robot-priority`\n\n## Contributions\n\n\u003e *About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other \"stakeholders,\" which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.\n\n## License\n\nMIT License (with OpenAI/Anthropic Rider) — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdicklesworthstone%2Fslb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdicklesworthstone%2Fslb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdicklesworthstone%2Fslb/lists"}