Secure bridge between your Android device and PC for ShadowAI Android app - enables clipboard sync, SSH key exchange, and Claude Code companion relay.
ShadowBridge includes a web dashboard at http://localhost:6767 for managing projects, notes, and team collaboration.
- Clipboard Sync: Share clipboard between PC and phone
- SSH Key Exchange: Quick Connect for ShadowAI SSH authentication
- Claude Code Companion: Relay notifications and approvals between Claude Code and ShadowAI
- System Tray: Runs quietly in the background
ShadowBridge acts as the central nervous system for Hierarchical Agent Swarms.
- Process Management: Spawns and manages isolated Python processes for each sub-agent (
shadow_agent.py). - Context Piping: Securely serializes and pipes
ContextPackets(files, memory, variables) from parent to child processes via stdin/stdout. - Lifecycle Tracking: Monitors process health and exit codes, bubbling up
TaskResultevents to the AndroidAgentOrchestrator.
- llama.cpp Server: Integrated server for running GGUF models locally.
- Model Management: Auto-download and quantization support.
- Windows 10/11
- Python 3.8+
- ShadowAI on your Android device
pip install -r requirements.txt
python shadow_bridge_gui.pyFor a more native Windows experience you can build the MSI installer via python setup.py bdist_msi (see docs/windows-installer.md). The resulting MSI skips the ~2.5 GB PyTorch + AudioCraft bundle, so follow the manual audio dependency steps in that guide after installing the base app.
For Linux users, a build script is provided to automate the setup:
# Make the script executable
chmod +x build_linux.sh
# Run the build script
./build_linux.shThis will create a virtual environment, install dependencies, and build the executable in dist/ShadowBridge/ShadowBridge.
After the build finishes, run ./package_linux.sh to bundle the compiled ShadowBridge alongside its web assets into dist/ShadowBridge-linux-<timestamp>.tar.gz, ready for handoff.
For troubleshooting and system dependencies, see README_LINUX.md.
- Ensure you have Python 3.8+ installed (use
brew install pythonif needed). - Install dependencies:
pip install -r requirements.txt
- Run ShadowBridge:
python shadow_bridge_gui.py
- (Optional) For Tailscale support, click the Install button within the app or install via the App Store.
| Port | Purpose |
|---|---|
| 19284 | Data receiver (clipboard, keys) |
| 19285 | Discovery broadcast |
| 19286 | Claude Code Companion relay |
- Run ShadowBridge on your PC
- Open ShadowAI on your phone
- Use Quick Connect to pair (scan QR or network discovery)
- Done! Clipboard sync and SSH keys are now shared
ShadowBridge includes a relay server for the claude-shadow plugin:
- Receives approval requests from Claude Code
- Forwards to ShadowAI on your phone
- Returns approval/denial responses
- Syncs replies to PC clipboard
- All communication is direct between your devices (local network or via Tailscale)
- No data is sent to external servers
- Works across any network with Tailscale VPN
- Upon Exit: Closing the application or choosing Exit from the system tray stops all background services (Discovery, Data Receiver, Web Dashboard, and Companion Relay). Your settings and data (projects, notes, and session logs) are saved locally in
%USERPROFILE%\.shadowai. - Upon Uninstall: Using the Windows "Uninstall a program" feature removes the application files from
Program Filesand the desktop shortcut.- Persistence: To prevent accidental data loss, the
%USERPROFILE%\.shadowaidirectory (containing your notes and project metadata) and the registered SSH keys are not removed automatically. - Cleanup: To perform a full cleanup after uninstalling, manually delete the
%USERPROFILE%\.shadowaiand%APPDATA%\ShadowBridgefolders.
- Persistence: To prevent accidental data loss, the
MIT License - See LICENSE for details.