From 06b9fe2c51d8e63db0c90bcc21b50f062164f7cc Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Tue, 13 Jan 2026 14:26:46 +0100 Subject: [PATCH] feat(docs): add mobile access guide (ttyd + Tailscale) v3.0.7 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - New mobile-access-setup.md with ToS-safe remote access solution - ttyd exposes terminal via browser, Tailscale provides secure VPN - Complete setup script with tmux for persistent sessions - Marked as WIP/UNTESTED - community feedback welcome - Added to README navigation table - Version bump 3.0.6 → 3.0.7 Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 20 ++ README.md | 1 + cheatsheet-en.md | 4 +- english-ultimate-claude-code-guide.md | 4 +- mobile-access-setup.md | 299 ++++++++++++++++++++++++++ 5 files changed, 324 insertions(+), 4 deletions(-) create mode 100644 mobile-access-setup.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 722fba3..22eaa4f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +## [3.0.7] - 2026-01-13 + +### Added +- **mobile-access-setup.md** - Mobile access guide for Claude Code (NEW, WIP/UNTESTED) + - Problem statement: Claude Code lacks native session relay/sync across devices + - Solution: ttyd + Tailscale for ToS-safe mobile access + - Complete setup script with tmux for persistent sessions + - Security considerations and ToS compliance notes + - Alternatives comparison (Happy Coder, Claude Code Web, tmux+SSH) + - Troubleshooting guide + - Marked as WIP/UNTESTED - community feedback welcome + +- **README.md** - Added mobile access guide to navigation table + - New row: "Want mobile access to Claude Code" → Mobile Access Setup → WIP + +### Stats +- 1 new file created (mobile-access-setup.md, ~300 lines) +- 2 files modified (README.md, cheatsheet-en.md version bump) +- Focus on ToS-safe remote access without third-party wrappers + ## [3.0.6] - 2026-01-13 ### Changed diff --git a/README.md b/README.md index e5f6eb2..2c06e47 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,7 @@ npm install -g @anthropic-ai/claude-code && claude | Want to test your knowledge | [Knowledge Quiz](#-knowledge-quiz) | Interactive | | Want a guided tour | [Personalized Onboarding](./personalized-onboarding-prompt.md) | Interactive | | Having issues with Claude Code | [/diagnose command](./examples/commands/diagnose.md) | Quick fix | +| Want mobile access to Claude Code | [Mobile Access Setup](./mobile-access-setup.md) | WIP | ### ⚡ Audit Your Setup diff --git a/cheatsheet-en.md b/cheatsheet-en.md index e44dede..8610336 100644 --- a/cheatsheet-en.md +++ b/cheatsheet-en.md @@ -6,7 +6,7 @@ **Written with**: Claude (Anthropic) -**Version**: 3.0.6 | **Last Updated**: January 2026 +**Version**: 3.0.7 | **Last Updated**: January 2026 --- @@ -378,4 +378,4 @@ where.exe claude; claude doctor; claude mcp list **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude -*Last updated: January 2026 | Version 3.0.6* +*Last updated: January 2026 | Version 3.0.7* diff --git a/english-ultimate-claude-code-guide.md b/english-ultimate-claude-code-guide.md index 893c291..0cfd3e9 100644 --- a/english-ultimate-claude-code-guide.md +++ b/english-ultimate-claude-code-guide.md @@ -10,7 +10,7 @@ **Last updated**: January 2026 -**Version**: 3.0.6 +**Version**: 3.0.7 --- @@ -9032,4 +9032,4 @@ Thumbs.db **Contributions**: Issues and PRs welcome. -**Last updated**: January 2026 | **Version**: 3.0.6 +**Last updated**: January 2026 | **Version**: 3.0.7 diff --git a/mobile-access-setup.md b/mobile-access-setup.md new file mode 100644 index 0000000..844710b --- /dev/null +++ b/mobile-access-setup.md @@ -0,0 +1,299 @@ +# Claude Code Mobile Access + +> **⚠️ STATUS: WIP / UNTESTED** +> +> This guide is a work in progress. The setup has not been fully tested across different environments. +> Use at your own risk. Contributions and feedback welcome. + +--- + +## The Problem + +Claude Code CLI is a **local interactive process**, not a service with a session API. Each instance is autonomous. Even `claude --remote` only offloads execution—it doesn't create a relay system. + +**What's missing**: A native `claude --serve` mode that exposes a WebSocket API, allows multiple clients, and maintains the same conversation context. + +**The workaround**: Expose your terminal via web browser using `ttyd`, accessible from anywhere via `Tailscale` VPN. + +--- + +## Solution: ttyd + Tailscale + +``` +YOUR COMPUTER YOUR PHONE +┌─────────────────┐ ┌─────────────────┐ +│ Claude Code │◄──────────────│ Browser │ +│ (runs here) │ Tailscale │ (same session) │ +│ │ (VPN) │ │ +└─────────────────┘ └─────────────────┘ +``` + +- **ttyd**: Exposes your terminal in a web browser +- **Tailscale**: Free VPN that gives your computer a fixed IP, accessible from anywhere (4G, public WiFi, etc.) +- **tmux**: Keeps session alive even if you close the browser + +**Use case**: Follow and continue Claude Code sessions from your phone (commuting, away from desk, etc.) + +--- + +## Why This Approach? + +### ToS Considerations + +Some third-party wrappers (like OpenCode) have been blocked by Anthropic for ToS violations. This approach is **ToS-safe** because: + +- You're using the **official Claude Code CLI** +- ttyd just exposes your terminal via browser (no wrapper) +- Tailscale is just a VPN for secure access +- No third-party client interacting with Claude's API + +--- + +## Prerequisites + +- macOS or Linux +- Claude Code CLI installed and authenticated +- Tailscale account (free tier works) + +--- + +## Installation + +### Quick Setup Script + +```bash +#!/bin/bash +# claude-mobile-setup.sh + +set -e + +echo "=== Setup Claude Code Mobile ===" + +# 1. Install ttyd + tmux +echo "[1/2] Installing ttyd..." +if [[ "$OSTYPE" == "darwin"* ]]; then + brew install ttyd tmux +else + sudo apt install -y tmux + sudo snap install ttyd --classic +fi + +# 2. Install Tailscale +echo "[2/2] Installing Tailscale..." +if [[ "$OSTYPE" == "darwin"* ]]; then + brew install tailscale +else + curl -fsSL https://tailscale.com/install.sh | sh +fi + +# 3. Create launcher script +mkdir -p ~/.local/bin +cat > ~/.local/bin/claude-mobile << 'EOF' +#!/bin/bash +PORT=7681 +PASS="${CLAUDE_MOBILE_PASS:-claude123}" + +TS_IP=$(tailscale ip -4 2>/dev/null || echo "not connected") + +echo "══════════════════════════════════" +echo " CLAUDE CODE MOBILE" +echo "══════════════════════════════════" +echo " URL: http://$TS_IP:$PORT" +echo " User: claude" +echo " Pass: $PASS" +echo "══════════════════════════════════" +echo "" +echo "Open this URL on your phone." +echo "Press Ctrl+C to stop." +echo "" + +# Kill existing session if any +tmux kill-session -t cc 2>/dev/null || true + +# Start Claude in tmux, expose via ttyd +tmux new-session -d -s cc 'claude' +exec ttyd -W -p $PORT -c "claude:$PASS" tmux attach -t cc +EOF + +chmod +x ~/.local/bin/claude-mobile + +# Add to PATH +if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then + echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc + echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc +fi + +echo "" +echo "=== Installation Complete ===" +echo "" +echo "Next steps:" +echo " 1. Run: tailscale up" +echo " 2. Run: source ~/.zshrc" +echo " 3. Run: claude-mobile" +echo "" +``` + +### Manual Installation + +```bash +# macOS +brew install ttyd tmux tailscale + +# Linux (Debian/Ubuntu) +sudo apt install -y tmux +sudo snap install ttyd --classic +curl -fsSL https://tailscale.com/install.sh | sh +``` + +--- + +## Usage + +### First Time Setup + +```bash +# 1. Connect to Tailscale (one-time) +tailscale up +# Follow the link to authenticate with Google/GitHub/etc. + +# 2. Install Tailscale on your phone +# iOS: App Store → Tailscale +# Android: Play Store → Tailscale +# Login with same account + +# 3. Start Claude Code Mobile +claude-mobile +``` + +### Output + +``` +══════════════════════════════════ + CLAUDE CODE MOBILE +══════════════════════════════════ + URL: http://100.78.42.15:7681 + User: claude + Pass: claude123 +══════════════════════════════════ +``` + +### On Your Phone + +1. Open Safari/Chrome +2. Go to `http://100.78.42.15:7681` (use your actual Tailscale IP) +3. Login with `claude` / `claude123` +4. You now have Claude Code in your browser + +--- + +## Configuration + +### Change Password + +```bash +export CLAUDE_MOBILE_PASS="your-secure-password" +claude-mobile +``` + +Or add to your shell config: + +```bash +echo 'export CLAUDE_MOBILE_PASS="your-secure-password"' >> ~/.zshrc +``` + +### Change Port + +Edit `~/.local/bin/claude-mobile` and change `PORT=7681` to your preferred port. + +--- + +## Security + +| Layer | Protection | +|-------|------------| +| **Network** | Tailscale uses WireGuard encryption | +| **Authentication** | Basic auth (username:password) via ttyd | +| **Access** | Only accessible from your Tailscale network | + +**Recommendations**: +- Use a strong password (not the default `claude123`) +- Don't expose ttyd directly to the internet without Tailscale +- Keep Tailscale client updated on all devices + +--- + +## Troubleshooting + +### "not connected" instead of IP + +```bash +# Check Tailscale status +tailscale status + +# If disconnected, reconnect +tailscale up +``` + +### Can't access from phone + +1. Ensure Tailscale app is installed on phone and connected to same account +2. Check firewall isn't blocking port 7681 +3. Try accessing locally first: `http://localhost:7681` + +### Session not persisting + +The tmux session should persist. To manually reattach: + +```bash +tmux attach -t cc +``` + +### ttyd command not found + +```bash +# macOS +brew reinstall ttyd + +# Linux +sudo snap install ttyd --classic +``` + +--- + +## Alternatives Considered + +| Solution | Pros | Cons | ToS Risk | +|----------|------|------|----------| +| **ttyd + Tailscale** ✅ | Simple, no wrapper, ToS-safe | Terminal UX on mobile | ✅ Safe | +| Happy Coder (7.1K ⭐) | Native apps, polished | Wraps CLI | ⚠️ Unknown | +| Claude Code Web (5.5K ⭐) | Rich UI | Wraps CLI | ⚠️ Unknown | +| tmux + SSH | Zero deps | Needs SSH client on phone | ✅ Safe | + +We chose ttyd + Tailscale because: +- It's just your terminal exposed via browser +- No third-party wrapper around Claude Code +- Zero ToS risk—you're using the official CLI + +--- + +## Related Resources + +- [ttyd GitHub](https://github.com/tsl0922/ttyd) - Terminal web server +- [Tailscale](https://tailscale.com/) - Zero-config VPN +- [ttyd + Claude Code Guide](https://aiengineerguide.com/blog/agentic-cli-browser-ttyd/) - Community tutorial +- [VPS Setup Guide](https://joshualent.com/snippets/claude-phone/) - Alternative: run on VPS + +--- + +## Contributing + +This doc is **WIP/UNTESTED**. If you test this setup, please share: +- Your OS/environment +- Any issues encountered +- Suggested improvements + +Open an issue or PR on this repo. + +--- + +*Last updated: January 2026 | Status: WIP/UNTESTED*