Superbrain - switchAILocal

Superbrain transforms switchAILocal from a passive API gateway into an intelligent, self-healing orchestrator. Instead of treating errors as terminal states, Superbrain actively monitors executions, diagnoses failures using AI, and takes autonomous remediation actions.

Overview

Superbrain implements an Observer-Critic architecture where every execution is monitored by a lightweight supervisor that can:

Detect failures in real-time (within seconds, not minutes)
Diagnose issues using AI (permission prompts, auth errors, context limits)
Take autonomous healing actions (stdin injection, process restart, intelligent failover)
Report all actions transparently (healing metadata in responses)

Key Benefits

Real-Time Monitoring

Detects hung processes and silent failures before hard timeouts

AI-Powered Diagnosis

Uses lightweight models to analyze failures and prescribe fixes

Autonomous Healing

Automatically responds to prompts, restarts with flags, or routes to alternatives

Intelligent Failover

Routes failed requests to alternative providers based on capabilities

Context Optimization

Pre-analyzes large requests and optimizes content to fit model limits

Transparent Actions

Every autonomous action is logged and included in response metadata

Quick Start

Basic Configuration

Add the superbrain section to your config.yaml:

config.yaml

superbrain:
  enabled: true
  mode: "conservative"  # Safe autonomous healing
  
  component_flags:
    overwatch_enabled: true    # Real-time monitoring
    doctor_enabled: true       # AI diagnosis
    injector_enabled: true     # Stdin injection
    recovery_enabled: true     # Process restart
    fallback_enabled: true     # Intelligent failover
    sculptor_enabled: true     # Context optimization
  
  overwatch:
    silence_threshold_ms: 30000      # 30 seconds
    log_buffer_size: 50
    heartbeat_interval_ms: 1000      # 1 second
    max_restart_attempts: 2
  
  doctor:
    model: "gemini-flash"            # Lightweight diagnostic model
    timeout_ms: 5000
  
  stdin_injection:
    mode: "conservative"             # Only safe patterns
    forbidden_patterns:
      - "delete"
      - "remove"
      - "sudo"
  
  fallback:
    enabled: true
    providers:
      - "geminicli"
      - "gemini"
      - "ollama"
    min_success_rate: 0.5
  
  context_sculptor:
    enabled: true
    token_estimator: "tiktoken"
    priority_files:
      - "README.md"
      - "main.go"
      - "index.ts"
  
  security:
    audit_log_enabled: true
    audit_log_path: "./logs/superbrain_audit.log"

Operational Modes

Superbrain supports five operational modes for gradual rollout:

disabled

Superbrain is completely disabled. Legacy pass-through mode.

observe

Monitor and log only, no autonomous actions. Ideal for initial deployment.

diagnose

Diagnose failures and log proposed actions without executing them. Validate diagnosis accuracy.

conservative

Heal safe patterns only (whitelisted prompts, known recoverable errors). Recommended for production.

autopilot

Full autonomous healing for all detected issues. Maximum automation after validation.

Core Components

1. Overwatch Layer

Real-time monitoring of all CLI executions, tracking output streams and detecting silent hangs.

config.yaml

overwatch:
  silence_threshold_ms: 30000      # Detect hung processes after 30s
  log_buffer_size: 50              # Capture last 50 lines for diagnosis
  heartbeat_interval_ms: 1000      # Check every second
  max_restart_attempts: 2          # Maximum restart attempts

Features:

Heartbeat detection (tracks stdout/stderr activity)
Rolling log buffer for diagnosis
Diagnostic snapshot capture on anomalies
Configurable silence threshold

2. Internal Doctor

AI-powered failure analysis using a lightweight model to identify root causes and recommend fixes.

config.yaml

doctor:
  model: "gemini-flash"     # Fast, cheap diagnostic model
  timeout_ms: 5000          # Maximum diagnosis time

Detects:

Permission prompts (file access, tool execution)
Authentication errors
Context limit exceeded
Rate limiting
Network errors
Process crashes

3. Stdin Injector

Automatically responds to interactive CLI prompts to prevent processes from hanging.

Conservative Mode
Autopilot Mode

config.yaml

stdin_injection:
  mode: "conservative"
  forbidden_patterns:
    - "delete"
    - "rm -rf"
    - "sudo"

Only responds to explicitly whitelisted prompts:

claude_file_permission: “Allow read file? [y/n]” → “y”
claude_tool_permission: “Allow tool execution? [y/n]” → “y”
generic_continue: “Press enter to continue” → “\n”

config.yaml

stdin_injection:
  mode: "autopilot"
  forbidden_patterns:
    - "delete"
    - "remove"
    - "sudo"

Automatically approves all safe operations (file reads, tool executions) while respecting forbidden patterns.

4. Process Recovery

Automatically restarts failed processes with corrective flags based on diagnosis. Example flow:

Diagnosis: “Permission prompt detected”
Action: Restart with --dangerously-skip-permissions flag
Result: Process completes successfully

Process recovery is limited by max_restart_attempts to prevent infinite loops. Default is 2 attempts.

5. Fallback Router

Routes failed requests to alternative providers based on capabilities and success rates.

config.yaml

fallback:
  enabled: true
  providers:
    - "geminicli"    # Preferred fallback
    - "gemini"       # Fallback 2
    - "ollama"       # Fallback 3
  min_success_rate: 0.5  # Minimum to consider provider

Selection criteria:

Provider capabilities (context size, streaming support)
Current availability
Historical success rates
Request requirements

6. Context Sculptor

Pre-flight analysis and optimization to fit requests within model context limits.

config.yaml

context_sculptor:
  enabled: true
  token_estimator: "tiktoken"  # or "simple"
  priority_files:
    - "README.md"
    - "main.go"
    - "package.json"

Features:

Token estimation for file/folder references
Intelligent file prioritization
High-density map generation for excluded content
Alternative model recommendations

Healing Metadata

When Superbrain takes autonomous actions, responses include detailed healing metadata:

Successful Healing
Negotiated Failure

{
  "id": "chatcmpl-123",
  "model": "geminicli:gemini-2.5-pro",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Here is the response..."
    }
  }],
  "superbrain": {
    "healed": true,
    "original_provider": "claudecli",
    "final_provider": "geminicli",
    "healing_actions": [
      {
        "timestamp": "2026-01-26T10:30:45Z",
        "action_type": "stdin_injection",
        "description": "Injected 'y' response to permission prompt",
        "success": true
      },
      {
        "timestamp": "2026-01-26T10:30:50Z",
        "action_type": "restart_with_flags",
        "description": "Restarted with --dangerously-skip-permissions",
        "success": true
      }
    ],
    "context_optimized": false,
    "total_healing_time_ms": 5200
  }
}

{
  "error": {
    "message": "Request could not be completed after autonomous remediation attempts",
    "type": "negotiated_failure",
    "code": "healing_exhausted"
  },
  "superbrain": {
    "attempted_actions": [
      "stdin_injection: permission_prompt",
      "restart_with_flags: --dangerously-skip-permissions",
      "fallback_routing: geminicli, gemini"
    ],
    "diagnosis_summary": "Process repeatedly hung on permission prompt despite auto-approval",
    "suggestions": [
      "Check CLI tool version and update if needed",
      "Verify file permissions in working directory",
      "Try using API-based provider instead of CLI"
    ],
    "fallbacks_tried": ["geminicli", "gemini"]
  }
}

Phased Rollout

Deploy Superbrain incrementally to manage risk:

Phase 1: Observe Mode (Week 1)

config.yaml

superbrain:
  enabled: true
  mode: "observe"

Goal: Establish baseline metrics without any autonomous actions.Success Criteria:

Metrics endpoint shows Superbrain data
Audit log captures all detected issues
No impact on existing functionality

Phase 2: Diagnose Mode (Week 2)

config.yaml

superbrain:
  enabled: true
  mode: "diagnose"
  component_flags:
    doctor_enabled: true

Goal: Validate diagnosis accuracy.Success Criteria:

Diagnosis correctly identifies failure types
Proposed actions are appropriate
No false positives in diagnosis

Phase 3: Conservative Mode (Week 3-4)

config.yaml

superbrain:
  enabled: true
  mode: "conservative"
  component_flags:
    overwatch_enabled: true
    doctor_enabled: true
    injector_enabled: true
    recovery_enabled: true
    fallback_enabled: true
    sculptor_enabled: true

Goal: Enable safe autonomous healing.Success Criteria:

Success rate improvement (measure before/after)
No security incidents
Healing metadata is accurate

Phase 4: Autopilot Mode (Week 5+)

config.yaml

superbrain:
  enabled: true
  mode: "autopilot"
  stdin_injection:
    mode: "autopilot"

Goal: Maximum automation.Success Criteria:

Consistent success rate improvement
Reduced manual intervention
Stable operation over time

Monitoring & Metrics

Metrics Endpoint

Superbrain exposes metrics via the management API:

curl http://localhost:18080/management/metrics

Example Response:

{
  "superbrain": {
    "total_healing_attempts": 142,
    "successful_healings": 128,
    "failed_healings": 14,
    "healing_by_type": {
      "stdin_injection": 45,
      "restart_with_flags": 38,
      "fallback_routing": 32,
      "context_optimization": 13
    },
    "average_healing_latency_ms": 3200,
    "silence_detections": 89,
    "diagnoses_performed": 89,
    "fallbacks_triggered": 32
  }
}

Audit Log

All autonomous actions are logged in JSON format:

tail -f logs/superbrain_audit.log

Log Entry Example:

{
  "timestamp": "2026-01-26T10:30:45Z",
  "request_id": "req-abc123",
  "action_type": "stdin_injection",
  "provider": "claudecli",
  "model": "claude-sonnet-4",
  "action_details": {
    "pattern_matched": "claude_file_permission",
    "response_injected": "y\n"
  },
  "outcome": "success"
}

Security & Safety

Stdin Injection Whitelist

Only safe patterns are auto-approved by default:

claude_file_permission: Allow read file?
claude_tool_permission: Allow tool execution?
generic_continue: Press enter to continue

Forbidden Patterns

Patterns that will NEVER be auto-approved:

config.yaml

stdin_injection:
  forbidden_patterns:
    - "delete"
    - "remove"
    - "sudo"
    - "rm -rf"

Security Fail-Safe

If a security-sensitive operation is detected, Superbrain will:

Abort autonomous remediation
Return a safe failure response
Log the incident to the audit log

Superbrain will never auto-approve operations matching forbidden patterns, even in autopilot mode.

Emergency Procedures

Emergency Disable

If Superbrain causes issues, disable it immediately:

Configuration File
Environment Variable
Mode Change

config.yaml

superbrain:
  enabled: false

Changes apply automatically without restart.

export SUPERBRAIN_ENABLED=false
./switchAILocal

config.yaml

superbrain:
  mode: "disabled"  # Alternative to enabled: false

Rollback Procedure

Set safe mode

Set mode to observe or disabled in config.yaml

Monitor metrics

Monitor metrics endpoint for stability

Review audit log

Review audit log for issues

Adjust configuration

Adjust configuration as needed

Re-enable gradually

Gradually re-enable features

Troubleshooting

Superbrain not activating

Check:

superbrain.enabled: true in config.yaml
Mode is not disabled
Provider supports CLI execution (Superbrain only monitors CLI providers)

Too many healing attempts

Solution:

config.yaml

overwatch:
  max_restart_attempts: 1  # Reduce from default 2

Unwanted stdin injections

Solution:

config.yaml

stdin_injection:
  mode: "disabled"  # Disable stdin injection entirely

Or use conservative mode with explicit whitelist:

config.yaml

stdin_injection:
  mode: "conservative"
  custom_patterns:
    - name: "my_safe_pattern"
      regex: "Continue\\? \\[y/n\\]"
      response: "y\n"
      is_safe: true

Diagnosis taking too long

Solution:

config.yaml

doctor:
  timeout_ms: 3000  # Reduce from default 5000ms

Best Practices

Start with Observe Mode

Always deploy in observe mode first to establish baseline metrics.

Monitor Audit Logs

Regularly review audit logs to understand what actions Superbrain is taking.

Use Conservative Mode in Production

The conservative mode provides the best balance of automation and safety.

Tune Silence Threshold

Adjust based on your typical request latency:

Fast models (< 10s): 15000ms
Medium models (10-30s): 30000ms (default)
Slow models (> 30s): 60000ms

Configure Fallback Order

List providers in order of preference based on your needs.

Next Steps

Memory System

Enable learning from execution history

Heartbeat Monitoring

Configure health checks and monitoring

Get Started

Core Concepts

Configuration

Intelligent Systems

Advanced Features

Guides

​Overview

​Key Benefits

Real-Time Monitoring

AI-Powered Diagnosis

Autonomous Healing

Intelligent Failover

Context Optimization

Transparent Actions

​Quick Start

​Basic Configuration

​Operational Modes

​Core Components

​1. Overwatch Layer

​2. Internal Doctor

​3. Stdin Injector

​4. Process Recovery

​5. Fallback Router

​6. Context Sculptor

​Healing Metadata

​Phased Rollout

​Monitoring & Metrics

​Metrics Endpoint

​Audit Log

​Security & Safety

​Stdin Injection Whitelist

​Forbidden Patterns

​Security Fail-Safe

​Emergency Procedures

​Emergency Disable

​Rollback Procedure

​Troubleshooting

​Best Practices

​Next Steps

Memory System

Heartbeat Monitoring

Overview

Key Benefits

Quick Start

Basic Configuration

Operational Modes

Core Components

1. Overwatch Layer

2. Internal Doctor

3. Stdin Injector

4. Process Recovery

5. Fallback Router

6. Context Sculptor

Healing Metadata

Phased Rollout

Monitoring & Metrics

Metrics Endpoint

Audit Log

Security & Safety

Stdin Injection Whitelist

Forbidden Patterns

Security Fail-Safe

Emergency Procedures

Emergency Disable

Rollback Procedure

Troubleshooting

Best Practices

Next Steps