# anycoding

**Repository Path**: gurudin/anycoding

## Basic Information

- **Project Name**: anycoding
- **Description**: 床上、地铁、洗手间 随时用手机vibe coding
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gurudin.github.io/anycoding/zh/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Nodejs, Android, Cli, Mobile, claude-code

## README

# AnyCoding · 中文说明

> 手机远程控制电脑上的 AI 编程 CLI —— 无 USB、无端口转发、无需局域网。

**🌍 Language**: [English](./README.md) · **中文**

[![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](./LICENSE)
[![npm version](https://img.shields.io/npm/v/any-coding.svg)](https://www.npmjs.com/package/any-coding)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#系统需求)
[![Android](https://img.shields.io/badge/Android-7.0%2B-3DDC84?logo=android&logoColor=white)](#android-app)
[![Open Core](https://img.shields.io/badge/model-open--core-orange)](./ARCHITECTURE.md)
[![Discord](https://img.shields.io/badge/Discord-加入聊天-5865F2?logo=discord&logoColor=white)](https://discord.gg/HWs6GtCg)

🌐 **Landing**: [gurudin.github.io/anycoding](https://gurudin.github.io/anycoding/)  · 
📦 **npm**: [`any-coding`](https://www.npmjs.com/package/any-coding)  · 
📖 **Architecture**: [ARCHITECTURE.md](./ARCHITECTURE.md)  · 
💬 **Discord**: [加入社区](https://discord.gg/HWs6GtCg)

---

**AnyCoding** 是一个开源的 "AI 编程 CLI 手机遥控" 工具包：在 Mac / Linux 上跑一行 `any-coding`，正在运行的 **[Claude Code](https://github.com/anthropics/claude-code)** 或 **[OpenAI Codex](https://github.com/openai/codex)** 会话就会镜像到你的 Android App，**手机上看到的就是电脑上同一个 pty 进程** —— 中日韩宽字符、truecolor、ANSI 转义、alt screen 全部原生支持。

沙发上、地铁里、客户那边都能继续跟 agent 对话、看输出、打断回复。支持 **两种联网模式**：托管云 relay（零配置） 或 **cloudflared 直连**（无账号、无闭源服务器）。

_English TL;DR: `any-coding` runs a local pty hub on your laptop and streams your Claude Code / Codex session to a native Android app over WebSocket. Choose managed cloud relay (free tier + 30-day trial) or fully self-hosted `hub --public` mode via cloudflared tunnel. Open-source CLI + Android app under Apache-2.0. Works through any NAT — no port forwarding, no USB, no LAN required._

---

## 为什么选 AnyCoding · Why AnyCoding

| 痛点 | AnyCoding 的方案 |
|---|---|
| 手机 SSH client 软键盘打不动 TUI，`claude` 的交互动不了 | **原生 Termux `TerminalView`**，带 Nerd Font，VT100 状态机完整，和桌面终端体验一样 |
| 出门前电脑上跑着 agent，临时续上变成两个会话 | 手机接的是**同一个 pty 进程**，关桌面窗口不杀 session，回来自动 256KB 回放 |
| ngrok / frp / Tailscale 自建隧道太重 | `any-coding hub --public` 一行起 cloudflared quick tunnel，手机扫码秒连 |
| 代码敏感，不想走第三方服务器 | Direct mode 下全链路只过**你自己的机器 + cloudflared 加密隧道**，无任何闭源服务在中间 |
| 一台电脑开 N 个项目的 agent | 每个项目跑一次 `any-coding`，手机顶部 tab 栏自动列出，图标区分 Claude / Codex |
| 想让队友用你的 relay | 支持自托管 relay (`ANYCODE_RELAY=...`) + 多设备管理 |

---

## 🚀 60 秒起步 · Quick Start

### 1. 装 CLI

```bash
npm install -g any-coding
```

**前置**：安装至少一个 agent CLI。
```bash
npm install -g @anthropic-ai/claude-code   # Claude Code
npm install -g @openai/codex               # OpenAI Codex
```

### 2. 装 Android App

从 [Releases](https://github.com/gurudin/anycoding/releases) 下 APK 直接安装（Android 7.0+），或从源码构建见 [`any-code-android/README.md`](./any-code-android/README.md)。

### 3. 选一种联网模式

**A) 云模式**（官方 relay 托管，零配置）

```bash
any-coding                    # 在任意项目目录
```

首次运行显示 **6 位配对码 + 二维码** → App 扫码或手填 → 绑定完成，之后这台 Mac 跑 `any-coding` 就直接起 session。附带账号系统 + 30 天试用。

**B) 直连模式**（100% 自主，无账号）

```bash
any-coding hub --public       # 一次装 cloudflared: brew install cloudflared
```

启一个 cloudflared quick tunnel，终端打印 `anycode://connect?url=...&token=...` URL 和二维码，App 扫码直连 —— **全程不经过 AnyCoding 云服务，不需要注册账号**。

```bash
any-coding hub --public --tunnel=none          # 仅 LAN（跳过 tunnel，手填局域网 IP）
any-coding hub --public --tunnel=cloudflared   # 默认
```

---

## 功能 · Features

- ✅ **多 agent 内置**：`any-coding claude [args]` / `any-coding codex [args]`，子命令后参数原样透传
- ✅ **交互式选择**：无参数启动时交互式选 `1` Claude / `2` Codex
- ✅ **多 tab 多项目**：N 个 `any-coding` 进程 = N 个 tab，手机顶部切换
- ✅ **Session 归属区分**：电脑端启动的 session 带 `🖥`，防止手机误删桌面 viewer
- ✅ **断线回放**：256 KB 环形缓冲，切 tab / 断网重连自动恢复 TUI
- ✅ **原生 Android 终端**：Termux `TerminalView`，CJK 宽字符、truecolor、alt screen、bracketed paste 全覆盖
- ✅ **公网直连模式**：`hub --public` + cloudflared，无账号
- ✅ **云 relay + 订阅门控**：FastAPI relay（closed source），账号 / 设备 / 配对码 / 试用期管理
- ✅ **多 PC 管理**：一个 App 绑定多台 Mac，设备列表切换
- ✅ **自托管 relay**：`ANYCODE_RELAY=https://your.host` 环境变量
- 🚧 **更多 agent**：Gemini CLI / Aider / goose / Open Interpreter（P0 规划中）
- 🚧 **Agent 插件 manifest**：社区通过配置扩展新 agent，不需改核心代码（P0 规划中）
- 🚧 **iOS 版**：SwiftTerm 或 xterm.js shell（规划中）

---

## 📐 架构 · Architecture

```
【云模式 · Cloud Mode】                  【直连模式 · Direct Mode】

 Android App                              Android App
     │ wss                                    │ wss
     ▼                                        ▼
 Hosted relay ◀── wss ─▶ any-coding       Cloudflared ◀── wss ─▶ any-coding
 (托管)                  hub (Mac)        tunnel                 hub --public
                              │                                       │
                              ▼                                       ▼
                         pty.spawn('claude'/'codex')            pty.spawn('claude'/'codex')
```

- **为什么 Mac dial out？** 任何 NAT、家宽、咖啡店 WiFi 都不用端口转发
- **为什么本地 hub？** 让 Ghostty / iTerm 的本地 viewer 和手机**看到同一个 pty**
- **为什么 vendored Termux？** 试过 WebView + xterm.js，顽固坑多（rAF 降频、软键盘 viewport 抖、canvas backing 竞争）。Termux 的 `TerminalView` 是 Android 上最完整的 VT100 实现
- **为什么 relay 不解析 pty 字节？** 纯字节转发 → 加新 agent 零改 relay 代码 + 隐私更好 + 横向扩容简单

完整设计决策与数据流见 **[ARCHITECTURE.md](./ARCHITECTURE.md)**。

---

## 仓库结构 · Repo Layout

```
anycoding/
├── any-code-cli/                 Node CLI 本体（Apache-2.0）
│   ├── wrapper.js                单文件：hub / attach / pair / hub --public / logout
│   ├── scripts/                  postinstall 修 node-pty spawn-helper
│   └── package.json              bin: any-coding
│
├── any-code-android/             Android App（Kotlin，Apache-2.0）
│   ├── app/                      MainActivity (WebView 配对) + TerminalActivity (原生终端)
│   ├── terminal-emulator/        vendored Termux VT 状态机（Apache-2.0）
│   └── terminal-view/            vendored Termux Android View（Apache-2.0）
│
├── LICENSE                       Apache License 2.0
├── NOTICE                        所有第三方依赖归属
├── ARCHITECTURE.md               分层 + 数据流 + 设计决策
├── CONTRIBUTING.md               怎么贡献
├── CODE_OF_CONDUCT.md            Contributor Covenant v2.1
├── SECURITY.md                   安全披露（含 safe harbor）
└── .github/                      Issue / PR 模板
```

> 云模式下的 relay server（FastAPI + MySQL + Redis）以托管服务形式运行，**不包含在本仓库**。所有客户端组件 —— CLI 和 Android App —— 都在这里，统一 Apache-2.0。Direct mode 完全绕过托管 relay。

---

## 命令一览 · Commands

| 命令 | 说明 |
|---|---|
| `any-coding` | 无参数交互选 agent（1 Claude / 2 Codex），在当前目录起 session |
| `any-coding claude [args...]` | 起 Claude Code 会话，args 原样透传 |
| `any-coding codex [args...]` | 起 OpenAI Codex 会话，args 原样透传 |
| `any-coding [legacy args...]` | 首个参数不是子命令时默认走 Claude（向后兼容 `-c` / `--dangerously-skip-permissions` 等）|
| `any-coding hub` | 前台跑 hub（debug 用，默认 detached）|
| `any-coding hub --public` | 前台 hub + cloudflared 公网 tunnel（直连模式）|
| `any-coding restart-hub` | 重启 hub（⚠️ 会带走所有活跃 session）|
| `any-coding pair` | 手动触发配对（重新扫码绑定）|
| `any-coding logout` | 删除 `~/.any-coding/device.json`，断开 relay |

更多细节（环境变量、配置文件、高级用法）见 [`any-code-cli/README.md`](./any-code-cli/README.md)。

---

## 路线图 · Roadmap

**AnyCoding 的北极星目标是成为"任意 pty 型 AI 编程 agent 的统一手机前端"**。路线图围绕这个定位展开 —— agent 生态优先级最高。

### P0 — Agent 生态

- **内置更多 agent**：`any-coding gemini`（[Gemini CLI](https://github.com/google-gemini/gemini-cli)）/ `any-coding aider`（[Aider](https://github.com/Aider-AI/aider)）/ `any-coding goose`（[goose](https://github.com/block/goose)）/ `any-coding interpreter`（[Open Interpreter](https://github.com/OpenInterpreter/open-interpreter)）
- **Agent 插件 manifest**：声明式格式（binary 名、install 提示、prompt 标记、图标、args 透传规则），社区通过 PR 或本地配置就能加新 agent，不需要改核心代码。**设计草案**：[`docs/agent-manifest.md`](./docs/agent-manifest.md)（英文，征求反馈中）
- **智能 agent picker**：自动检测本地已装的 agent，交互式选择器只列出可用的，对缺失的给安装命令提示

### P1 — 平台覆盖

- **Linux + Windows 验证**：`package.json` 已声明兼容，需要 CI 和真机验证
- **iOS App**：SwiftTerm 或 WebView + xterm.js 方案（复用同一套 hub / relay 协议）
- **手动输入配对码 fallback**：相机失效时粘贴 `anycode://` URL 的兜底流程

### P2 — Session 体验

- **App 内建 session 启动器**：目录选择器，从手机启动新 session（协议已就绪，缺 UI）
- **命名 / 固定 session**：友好标题、tab 可重排
- **Session 日志导出**：导出完整 ANSI log（不止 256 KB 环形缓冲）

### P2 — 开发者基建

- **GitHub Actions CI**：lint + build CLI + build APK，每个 PR 自动跑
- **自动签 APK release**：tag 触发构建并挂到 GitHub Release
- **一键安装脚本**：`curl -fsSL install.anycoding.sh | bash`（非 npm 环境适用）

### P3 — 附加

- 消息计数器（发 / 回次数，按 agent 拆分）
- 服务端使用聚合（云模式订阅配额）
- 快捷短语 / 键盘快捷键 / agent 专属宏

---

## 系统需求 · System Requirements

| 端 | 最低要求 |
|---|---|
| 电脑（CLI） | Node.js **≥ 18**，macOS / Linux / Windows |
| agent CLI | `claude`（`@anthropic-ai/claude-code`）或 `codex`（`@openai/codex`）至少装一个 |
| Android App | **Android 7.0**（API 24）及以上 |
| 直连模式 | `cloudflared` (`brew install cloudflared` 或等价) |
| 自托管 relay | Python 3.10+、MySQL 8、Redis 6、TLS 反代（可选）|

---

## 隐私 · Privacy

| 模式 | managed relay 记录什么 | 是否落盘 prompt / pty 内容 |
|---|---|---|
| **Cloud**（托管 relay） | 每小时一行聚合计数 `(user_id, platform, hour, direction, count)`，**不包含**你说了什么 | ❌ pty 字节仅在 relay 内存中转发 |
| **`--public` / direct** | **什么都不记。** 流量走手机 ↔ cloudflared ↔ 你自己的电脑，relay 完全不在链路里 | N/A —— relay 根本看不到 |
| **自托管 relay** | 你自己配置。`ENABLE_STATS=false` 关闭计数表；`ANYCODE_RELAY=...` 指向你自己的 relay | 你说了算 |

计数表的用途：以后 App 内展示「你自己这个月用了多少次」、给订阅配额用。**不存 prompt / 回复 / 文件内容 / 除 `user_id` 以外的标识符**。源码见 [`any-code-server/`](https://github.com/gurudin/anycoding)（近期公开）。

---

## 社区 · Community

- 💬 **[Discord 群](https://discord.gg/HWs6GtCg)** —— 问问题、分享配置、讨论要接的新 agent、dogfood 互助最快的地方，欢迎进来打招呼
- 🐛 **[GitHub Issues](https://github.com/gurudin/anycoding/issues)** —— bug 报告和需求提议（有模板指引）
- 🔒 **安全问题**：请**不要**在 Discord 或 Issue 里公开漏洞 —— 私密渠道见 [SECURITY.md](./SECURITY.md)

---

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=gurudin/anycoding&type=Date)](https://www.star-history.com/#gurudin/anycoding&Date)

---

## 贡献 · Contributing

我们很乐意接受 PR / Issue。请先读：
- [CONTRIBUTING.md](./CONTRIBUTING.md) — 分支策略、PR 流程、测试要求（双模式都要测）
- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) — Contributor Covenant v2.1
- [SECURITY.md](./SECURITY.md) — 漏洞披露流程（含 safe harbor）

报 bug / 提 feature：[GitHub Issues](https://github.com/gurudin/anycoding/issues)（有模板指引）。日常交流直接进 [Discord](https://discord.gg/HWs6GtCg)。

---

## 技术栈 · Built On

| 依赖 | 用途 | 许可 |
|---|---|---|
| [node-pty](https://github.com/microsoft/node-pty) | pty 进程管理 | MIT |
| [ws](https://github.com/websockets/ws) | Node WebSocket | MIT |
| [qrcode-terminal](https://github.com/gtanner/qrcode-terminal) | 终端二维码渲染 | Apache-2.0 |
| [Termux terminal-emulator / terminal-view](https://github.com/termux/termux-app) | Android 原生 VT100 终端 | Apache-2.0 |
| [OkHttp](https://square.github.io/okhttp/) | Android WebSocket 客户端 | Apache-2.0 |
| [jsQR](https://github.com/cozmo/jsQR) | WebView 二维码解码 | Apache-2.0 |
| [cloudflared](https://github.com/cloudflare/cloudflared) | 直连模式的隧道 | Apache-2.0 |
| [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) | 终端等宽字体 | OFL-1.1 |

完整归属见 [NOTICE](./NOTICE)。

---

## 许可 · License

本项目采用 **[Apache License 2.0](./LICENSE)**。

- `any-code-cli/` + `any-code-android/app/` —— AnyCoding 原创代码
- `any-code-android/terminal-emulator/` + `any-code-android/terminal-view/` —— 从 [Termux](https://github.com/termux/termux-app) vendored，保留上游 Apache-2.0

Apache-2.0 提供显式**专利授权**条款，与所有依赖兼容，商业友好。第三方归属详见 [NOTICE](./NOTICE)。

---

<p align="center">
  <sub>
    Made with ❤️ for everyone who codes on the move.<br>
    <b>Keywords</b>: claude code mobile · claude code android · codex remote · ai coding agent · remote terminal · mobile pty · anthropic · openai codex · cloudflared tunnel · open-core
  </sub>
</p>