Developer Documentation

Open Source Repositories

Shadow's companion tools are open source. Contribute, fork, or use them as a starting point for your own projects.

ShadowBridge Setup

ShadowBridge is a Windows system tray app that connects your phone to your PC for clipboard sync, SSH key exchange, and Claude Code relay.

Quick Start

# Clone the repository
git clone https://github.com/alrightryanx/shadow-bridge.git
cd shadow-bridge

# Install dependencies
pip install -r requirements.txt

# Run ShadowBridge
python shadow_bridge_gui.py

Network Ports

• Port 19284 - Data receiver for clipboard and SSH keys
• Port 19285 - Network discovery broadcast
• Port 19286 - Claude Code Companion relay

Claude Shadow Plugin

The Claude Shadow plugin sends notifications to your phone when Claude Code needs permission approvals, allowing you to approve or deny from anywhere.

Installation

# Add the marketplace
/plugin marketplace add alrightryanx/claude-shadow

# Install the plugin
/plugin install claude-shadow@shadowai-plugins

Features

• Permission request notifications on your phone
• Session start/stop event tracking
• Mobile approval and denial responses
• Reply via clipboard sync through ShadowBridge

System Architecture

Shadow components communicate over your local network or via Tailscale VPN for remote access.

+-------------------+     Local Network/Tailscale     +--------------------+
|    ShadowAI       |<------------------------------->|    ShadowBridge    |
|    (Android)      |        Ports 19284-19286        |    (Windows PC)    |
+-------------------+                                 +---------+----------+
                                                                |
                                                                v
                                                      +--------------------+
                                                      |    Claude Code     |
                                                      |   (claude-shadow   |
                                                      |     plugin)        |
                                                      +--------------------+
                    

Connection Options

• Local Network - Automatic discovery when on the same WiFi
• Tailscale VPN - Use Tailscale IP for connections across networks

ShadowAI Android App

ShadowAI is a voice-first AI assistant designed for safe, hands-free use across Android devices. The app supports multiple platforms and AI backends.

Supported Platforms

• Android Phone - Full-featured mobile experience with touch and voice
• Android Auto - Voice-first interface with driving-aware safety restrictions
• Android TV - Dashboard-style interface with full D-pad navigation
• Wear OS - Quick voice queries from your wrist

AI Backend Support

The app uses a backend-agnostic architecture via the IConnectionBackend interface:

• Cloud APIs - Claude (Anthropic), GPT (OpenAI), Gemini (Google)
• SSH Remote - Claude Code, Gemini CLI, Codex, Aider, Ollama, LM Studio
• On-Device - llama.cpp for offline LLM inference (DeepSeek-R1, Gemma, Qwen, SmolLM2)

Driving Safety System

The SafetyManager automatically adapts the interface based on driving speed:

# Safety Levels (auto-detected via GPS)
UNRESTRICTED  - Parked/walking, full features
MINIMAL       - Slow driving (<25 km/h), limited text
MODERATE      - Normal conditions, constrained responses
STRICT        - Fast driving, minimal interaction
AUDIO_ONLY    - Highway speeds (80+ km/h), voice only

Voice Features

• Hotword Detection - "Hey Shadow", "Hey Steve", "Ok Shadow"
• On-Device Speech - whisper.cpp for offline recognition
• Streaming TTS - Real-time voice playback with dual-voice support
• Voice Activity Detection - Silero VAD for natural turn-taking

Key Features

• Projects - Organize conversations by project with dedicated working directories
• Notes - Create, edit, and search notes with encryption support
• Automations - Schedule tasks with cron expressions, trigger via voice or conditions
• AI Teams - Multi-agent orchestration with specialized roles (DEV, QA, OPS)
• DevOps Integrations - Slack, Jira, PagerDuty, GitHub, Linear, n8n workflows

Automations System

Create powerful AI-driven automations that can be triggered manually, on a schedule, or via voice commands.

Automation Types

• Text-based - AI command execution with file operations
• Image Generation - DALL-E 3, Stable Diffusion, Imagen 3
• Browser Automation - Automated web interactions
• n8n Workflows - External workflow orchestration

Trigger Types

# Available trigger methods
Manual      - User-triggered from app or widget
Scheduled   - Cron expressions with timezone support
Condition   - Logical conditions (location, time, etc.)
Voice       - Phrases like "run QA workflow"

Multi-Agent Teams

Run automations with specialized agent teams:

• DEV Team - Code generation and development tasks
• QA Team - Testing and quality assurance
• OPS Team - Operations and deployment
• Custom Teams - Define your own agent roles

On-Device AI

Run AI models completely offline using llama.cpp integration. No internet required.

Supported Models

• DeepSeek-R1 - Reasoning-focused model for complex tasks
• Gemma 2 - Google's efficient open model
• Qwen - Alibaba's multilingual model
• SmolLM2 - Ultra-lightweight for low-RAM devices

Features

• Quantized GGUF format for mobile optimization
• Token streaming for real-time responses
• Model download manager with storage optimization
• Automatic fallback when cloud APIs unavailable

Contributing

We welcome contributions! Here's how to get started:

• Fork the repository on GitHub
• Create a feature branch for your changes
• Submit a pull request with a clear description
• Report bugs or request features via GitHub Issues

For questions or support, reach out on X (Twitter) or Reddit.