# Hermes Phone Agent

**Hermes Agent with MCP servers for Android/iOS phone flashing, unlocking, and management**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)

## What is this?

Hermes Phone Agent extends [Hermes Agent](https://github.com/nousresearch/hermes-agent) with Model Context Protocol (MCP) servers for controlling Android and iOS devices. It provides AI-powered phone management, flashing, unlocking, and automation.

## Features

### Android Support
- **ADB**: Full device control (shell, screenshots, input, file transfer)
- **Fastboot**: Flash partitions, unlock bootloader, reboot modes
- **Heimdall**: Samsung-specific flashing and PIT extraction
- **App Management**: Install, uninstall, list packages
- **Screen Control**: Screenshots, tap, swipe, text input, key events
- **System Info**: Battery, storage, logs, device properties

### iOS Support
- **libimobiledevice**: Device info, app management, screenshots
- **SSH/SFTP**: Full access to jailbroken devices
- **AFC**: Apple File Conduit for file system access
- **Backup/Restore**: Full device backups
- **Jailbreak Tools**: checkra1n, palera1n instructions and status

### Integration
- **MCP Protocol**: Works with Claude, Codex, Cursor, and any MCP client
- **Hermes Agent**: Telegram, Discord, Slack, WhatsApp, Signal gateway
- **Windows Desktop**: Native Windows support with one-click installer

## Quick Start

### Windows (Recommended)

1. Download the latest release from [Releases](https://github.com/petrobumaga/hermes-phone-agent/releases)
2. Run `install.ps1` in PowerShell
3. Launch from desktop shortcut or Start Menu

### Manual Install

```bash
# Clone the repository
git clone https://github.com/petrobumaga/hermes-phone-agent.git
cd hermes-phone-agent

# Install dependencies
npm install

# Start the agent
npm start
```

### MCP-Only Mode

If you just want the MCP servers without Hermes Agent:

```bash
# Android MCP server only
npm run android-mcp

# iOS MCP server only
npm run ios-mcp
```

## Configuration

Configuration file: `~/.hermes-phone-agent/config.yaml`

```yaml
android:
  enabled: true
  adbPath: auto        # Auto-detect or path to adb
  fastbootPath: auto
  heimdallPath: auto

ios:
  enabled: true
  sshUser: root
  sshPassword: alpine  # CHANGE THIS!
  sshPort: 22

hermes:
  enabled: true
  configPath: ~/.hermes/config.yaml
```

## Available Tools

### Android Tools (28 tools)

| Tool | Description |
|------|-------------|
| `android_list_devices` | List connected devices |
| `android_device_info` | Get device properties |
| `android_shell` | Execute shell commands |
| `android_screenshot` | Capture screen |
| `android_tap` | Tap at coordinates |
| `android_swipe` | Swipe gesture |
| `android_input_text` | Type text |
| `android_press_key` | Press key (HOME, BACK, POWER, etc.) |
| `android_list_packages` | List installed apps |
| `android_install_apk` | Install APK |
| `android_uninstall_app` | Uninstall app |
| `android_push_file` | Push file to device |
| `android_pull_file` | Pull file from device |
| `android_logcat` | Get system logs |
| `android_battery` | Battery status |
| `android_storage` | Storage info |
| `android_reboot` | Reboot device |
| `fastboot_devices` | List fastboot devices |
| `fastboot_flash` | Flash partition |
| `fastboot_unlock` | Unlock bootloader |
| `fastboot_reboot` | Reboot from fastboot |
| `fastboot_getvar` | Get fastboot variable |
| `heimdall_detect` | Detect Samsung device |
| `heimdall_flash` | Flash Samsung partition |
| `heimdall_download_pit` | Download PIT table |

### iOS Tools (18 tools)

| Tool | Description |
|------|-------------|
| `ios_list_devices` | List connected devices |
| `ios_device_info` | Get device info |
| `ios_list_apps` | List installed apps |
| `ios_install_ipa` | Install IPA |
| `ios_uninstall_app` | Uninstall app |
| `ios_screenshot` | Take screenshot |
| `ios_syslog` | Get system logs |
| `ios_backup` | Backup device |
| `ios_ssh_command` | Execute SSH command |
| `ios_ssh_pull` | Pull file via SSH |
| `ios_ssh_push` | Push file via SSH |
| `ios_mount_afc` | Mount AFC filesystem |
| `ios_detect_jailbreak` | Check jailbreak status |
| `ios_checkra1n_info` | checkra1n info |
| `ios_palera1n_info` | palera1n info |
| `ios_dfu_instructions` | DFU mode instructions |
| `ios_reboot` | Reboot device |
| `ios_shutdown` | Shutdown device |

## Use Cases

- **Phone Repair**: Diagnose and fix bootloops, soft bricks
- **Flashing**: Install custom ROMs, stock firmware
- **Unlocking**: Bootloader unlock, FRP bypass
- **Jailbreaking**: iPhone jailbreak with checkra1n/palera1n
- **Automation**: Automated testing, UI automation
- **Data Recovery**: Backup and restore, file extraction
- **Security Research**: Device analysis, forensic examination

## Prerequisites

### Android
- [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools) (ADB, Fastboot)
- USB Debugging enabled on device
- (Optional) [Heimdall](https://heimdall.ashido.com) for Samsung devices

### iOS
- [libimobiledevice](https://libimobiledevice.org) utilities
- (For jailbroken) OpenSSH installed on device
- USB or WiFi connection

## Development

```bash
# Install dev dependencies
npm install

# Run Android MCP server
npm run android-mcp

# Run iOS MCP server
npm run ios-mcp

# Start all services
npm start
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Hermes Agent](https://github.com/nousresearch/hermes-agent) by Nous Research
- [MCP Protocol](https://modelcontextprotocol.io) by Anthropic
- [libimobiledevice](https://libimobiledevice.org) for iOS support
- [Android SDK](https://developer.android.com) for Android support
- [Heimdall](https://heimdall.ashido.com) for Samsung flashing

## Disclaimer

This tool is for educational and authorized testing purposes only. Always ensure you have proper authorization before modifying device software. The authors are not responsible for any damage caused by misuse of this software.