# phoneshell

**Repository Path**: ggbook666/phoneshell

## Basic Information

- **Project Name**: phoneshell
- **Description**: 當你電腦使用codex、claude等CLI工具時暫時要出門，如何遠端繼續任務？
PhoneShell,現代化shell連結工具
將一台手機、N台電腦成群，在任何地方都可存取任何設備，會話不中斷。
安全最佳化－掃碼建立群組、連線需要手機授權
操作優化－便捷存取電腦目錄、claude、codex指令手機快速輸入
管理最佳化－裝置重新命名、會話重新命名
擴充優化－支援所有CLI工具
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: https://www.phoneshell.sbs
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 2
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">PhoneShell</h1>
<p align="center">
  <strong>中文</strong> · <a href="README_EN.MD">English</a>
</p>
<p align="center">
  <img src="assets/screenshots/readme-hero-zh.png" width="80%" alt="PhoneShell 软件界面预览" />
</p>

<p align="center">
  <strong>手机上的终端。随时随地远程操控 Windows / Linux 终端，AI 编程不受限。</strong>
</p>

---

## 第 1 步：手机安装客户端

<p align="center">
  <a href="https://play.google.com/store/apps/details?id=ggbook.flutter.phoneshell&pcampaignid=web_share">
    <img src="https://img.shields.io/badge/Google_Play-下载_Android_版-34A853?style=for-the-badge&logo=googleplay&logoColor=white" alt="Google Play 下载 PhoneShell Android 版" />
  </a>
  <a href="https://appgallery.huawei.com/app/detail?id=com.example.phoneshell&channelId=SHARE&source=appshare">
    <img src="https://img.shields.io/badge/HUAWEI_AppGallery-下载_鸿蒙版-C7000B?style=for-the-badge&logo=huawei&logoColor=white" alt="华为应用市场下载 PhoneShell 鸿蒙版" />
  </a>
</p>


## 第 2 步：启动你的电脑端或 Linux 端（本项目支持任意多终端同时连接）

### Windows 端

1. 以管理员身份运行 `PhoneShell.App.exe`。
2. 点击 **Start**。
3. 打开防火墙对应端口（默认 `9090`，也可自定义）。

### Linux 端

```bash
# 安装依赖（Ubuntu / Debian）
sudo apt-get update
sudo apt-get install -y git nodejs npm python3 build-essential

# 克隆并安装
git clone https://gitee.com/ggbook666/phoneshell
cd phoneshell
sudo bash linux2/deploy/phoneshell install
```

完成这两步后，打开手机 App，扫描 Windows 或 Linux 端显示的二维码即可连接。

---

## 为什么用 PhoneShell
电脑claude\codex等CLI工具，支持电脑和手机同时编辑。
当电脑干活干到一半，出门在外手机可以继续无缝接管干活窗口，回家后电脑又可以无缝接管这些AI的窗口。

- **手机即终端** — 在手机上获得原生 Shell 体验，随时随地 AI 编程。
- **会话不中断** — 以群组为概念，在群组中终端会话在手机、PC、Linux 之间无缝切换，进程持续运行。
- **兼容所有 CLI** — 支持一切CLI工具：claude、codex、gemini、kiro、droid...
- **多平台覆盖** — Windows 桌面端 + Linux 服务端 + Android / HarmonyOS 手机端（iOS 计划中）。
- **新手友好** — 无需复杂配置，打开程序、扫码即连，开箱即用。

---

## 与同类工具对比
| 他们的            | 特点                         | 我们的      | 特点                                             |
|------------------|------------------------------|------------|--------------------------------------------------|
| claude、codex     | CLI 单一                     | phoneshell | claude、codex、gemini、kiro、droid 等所有 CLI     |
| 传统 ssh 工具     | 古老、移动端不友好、体验差   | phoneshell | 现代化体验、会话无缝切换                         |
| termius 等移动端  | 贵、做不到无缝连接           | phoneshell | 手机、PC、Linux 都可互连                         |
| happy            | 无法运行终端命令、可扩展性差 | phoneshell | 更高扩展性                                       |

---

| 支持平台 | Windows | Android | Linux | Harmony | iOS |
|----------|---------|---------|--------|----------|-----|
|          | ✔       | ✔       | ✔      | ✔        | ✘   |

## 界面预览

<p align="center">
  <img src="assets/screenshots/preview-group-2.png" width="30%" />
  <img src="assets/screenshots/preview-session-2.png" width="30%" />
</p>
<p align="center">
  <img src="assets/screenshots/pc.png" width="60%" />
</p>

---

## 核心功能

| 功能 | 说明 |
|------|------|
| 多设备管理 | 随时随地切换设备、会话无缝切换 |
| 历史回放 | 分页加载终端输出历史，断线重连不丢失上下文 |
| 二维码连接 | 手机扫码、多设备加入群组互连 |
| 群组与邀请码 | Relay 中继、扫码加入、密钥轮换、服务器迁移 |
| 安全管理 | 只能绑定一台手机、除手机外的设备相互连接需要手机授权确认、linux端可关闭web面板 |
| 便捷操作 | PC端新增文件资源管理器和快捷面板，手机端可访问pc端文件路径、手机端pc端支持快捷指令操作 |
| 优化体验 | 支持设备重命名、会话窗口重命名 |

---

### Linux 端特别说明

### 前置要求

- Linux（systemd）
- Node.js >= 18
- `node-pty` 构建依赖：`python3`、`make`、`g++`

### 设置

```bash
sudo phoneshell set
```

### 常用命令

```bash
phoneshell                       # 连接本地终端
phoneshell list                  # 列出活跃会话
phoneshell attach                # 附加到已有会话
phoneshell local --shell bash    # 指定 shell 类型
phoneshell set                   # 修改配置
phoneshell start                 # 启动服务
```

### LINUX端Web 面板

- 启用后访问：`http://<host>:<panelPort>/panel/`
- 若 `modules.webPanel=false`，面板接口返回 404，但 `/ws/` 仍可用。
- 配置 SSL 证书后自动启用 wss 连接，不配置则为WS连接。

---

### 我们更新了什么
2026-4-24（请更新最新版本）

1. windows桌面端新增工具面板：包含资源管理器、快捷指令。手机端可以访问windows的资源管理器、快捷指令，方便手机操作。
   <p align="center">
     <img src="assets/screenshots/update-shortcuts-2.png" width="48%" alt="快捷面板预览" />
     <img src="assets/screenshots/update-explorer-2.png" width="48%" alt="资源管理器预览" />
   </p>
2. windows桌面端及手机端支持对会话窗口重命名、多窗口方便管理会话。
3. 所有优化扫码连接协议，扫码连接更加稳定。
4. 新增安全规则：群组设备里只允许有一台手机端，其他设备若要互相连接需要手机确认。Linux端web面板可在设置里关闭，只保留转发功能，防止网络攻击。
5. 性能优化。

---

有问题直接联系我邮箱 fu648227368@gmail.com

本项目认可LINUX DO，https://linux.do

## 许可证

本项目采用 GNU AGPL-3.0 许可证，详见 [LICENSE](LICENSE)。