claude-code-remote
KoichiIshiguro/claude-code-remote
The smallest self-hosted Claude Code web UI on GitHub. ~2000 lines of vanilla JS, no build step, no database. Hackable in a weekend.
Instalação
npx convez-ai KoichiIshiguro/claude-code-remote1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
English | 日本語
🤖 Claude Code Remote
Your own main PC's AI, operable from anywhere. A minimal, self-hosted web UI for Claude Code — one agent running on your machine, driven from any browser or phone, with your files, context, and progress all in one place.
Real session, mid-task, on a phone — reserve a follow-up to fire after the limit resets, switch model/effort inline.
💡 What it really is — your main PC, operable from anywhere
This isn't "Claude in a browser tab." It turns the PC you already work on into an always-on workstation you can drive from your phone, your laptop, or any other machine — without copying files, sessions, or context around.
The agent runs on one machine (your PC). Every device is just a window into it. That single design choice is what makes the three things below actually work:
1. Your real Claude, your subscription — not a metered API key.
It drives the real claude CLI in -p (headless) mode, so it runs on the Pro/Max plan you already pay for — same login, same usage allowance as the TUI. No separate API billing, no per-token surprises.
Example: you're out with just your phone. You open the same Claude that's mid-refactor on your desk, still signed in to your plan — nothing to re-auth, no API key to paste.
2. Hit a rate limit? Reserve the work for the moment it clears.
When Claude returns "session limit · resets 2:50am," the app reads that reset time. Type your next prompt, tap the send button's ▾, and a one-tap "send after the limit clears" preset is already waiting (pre-filled with the detected time). The reservation then fires server-side, shortly after the reset (a ~10-minute safety margin past 2:50am) — you don't have to be awake, the browser doesn't have to be open, and your restored quota isn't left sitting idle.
Example: at 2am you reserve "run the test suite and fix what's red" before bed; by the time you wake up it already ran on its own once the window reopened. (Reserving is a deliberate one-tap action — a normal send still sends immediately, so nothing is deferred behind your back.)
3. One context, one progress — shared across every device.
Because there's a single agent on a single machine, your history, context, and in-flight progress are identical everywhere. Start a task at your desk, check it from your phone on the train, finish it on a laptop at a café — it's literally the same session, mid-thought.
Compare: pointing several machines at a shared drive shares the files but not Claude's history — each machine keeps its own ~/.claude, so the context doesn't follow you. Here it does, because you never left the one machine.
Why so small? Other Claude Code web UIs are 30–50k LOC React/Tauri monsters. This one is vanilla JS + Express in ~3,000 lines of backend — readable in an afternoon, hackable in a weekend, and battle-tested on real iOS Safari.
✨ Features
- 🔐 Tailscale-first auth — local ID/PW set up via browser on first run; designed to sit behind your private Tailscale network, not on the open web
- 💬 Streaming chat UI with tool-use cards, thinking blocks, and per-turn cost
- 📁 Explicit multi-project switcher — register any folder through a built-in file-browser picker (or zip import); each project is sandboxed to its own path, and adding one never auto-spawns a session
- 🧵 Multiple sessions per project — keep parallel conversations in the same repo and switch between them from the sidebar
- 🗄️ Archive / restore / purge sessions — hide finished threads, bring them back, or permanently delete the underlying jsonl
- ↔️ TUI-compatible — Claude's own
~/.claude/projects/*.jsonlis the single source of truth, so sessions you start in theclaudeCLI show up here (and vice-versa) - 🔄 Resume any session via Claude's native
--resume - 🖥️ Built-in terminal — a persistent tmux-backed shell per session that survives server restarts (where tmux is available); plain-shell fallback on Windows / no-tmux hosts
- 🛟 Survive crashes — in-flight responses are persisted to disk; reattach picks up where you left off
- 🖼️ Drag / paste images straight into chat (uses Claude's prompt-path syntax — no proprietary attachment API)
- 📱 Installable PWA with status-bar styling, splash screen, home-screen icon
- 🔌 Auto-reconnect WebSocket that survives mobile network switches and PM2 reloads
- 📄 In-browser file viewer with Markdown rendering and a refresh button
- ⚡ Stateless prompt model — spawns a fresh
claudeper turn, no zombies to babysit - 📊 Context size indicator — a status-bar meter shows the real input-token count from the last API call (matches what the TUI shows)
- 🗜️ Auto-compact at TUI threshold — when context hits 167k (Claude Code TUI's ~83.5% trigger on 200k models),
/compactruns automatically before the next prompt. After any compact it reads the post-compact token count back from Claude'scompact_boundarymetadata, so a fresh/compactdoesn't immediately re-trigger - ⏰ Scheduled prompts (send-later) — a Gmail-style split send button: the button still just sends, the
▾reserves the prompt for a chosen time. Reservations run server-side so they fire with the browser closed and survive a restart. When asession limit · resets …message is seen, the▾menu pre-fills a "send after the limit clears" preset (detected time + a ~10-min safety margin), so one tap reserves your follow-up to fire itself once the window reopens - 🎚️ Inline model & effort picker — tap the status-bar pill for a quick pull-up to switch model (Opus / Sonnet / Haiku / Fable, or a custom model name) and reasoning effort, without opening settings
- ⌨️ Slash-command autocomplete — type
/to pick from the commands your-penvironment actually exposes (skills + built-ins like/compact) - 🖼️ Inline artifacts — screenshots and files Claude writes (
Write/Edit, or image paths inBash) render in the thread as previews or download links
📸 Screenshots
🚀 Quick Start
1. Install prerequisites
- Node.js ≥ 18, git, Claude CLI signed in with your Pro/Max account
2. Set up Tailscale — this is what makes "from anywhere" work 🔑
Don't skip this. This app runs on your main PC and is reached from your phone/laptop over a private network, never the open internet. Tailscale is what stitches your devices into that private network (a "tailnet") — with zero port-forwarding, zero firewall config, and an always-on encrypted tunnel. If you get stuck here, the rest of the app can't reach you, so let's get it right in 3 minutes.
It really is just "make an account and log in on both devices." Concretely:
- Create a free account → tailscale.com → Get started. The free Personal plan is plenty (up to 100 devices). You sign in with Google / Microsoft / GitHub / Apple / email — no credit card.
- Install Tailscale on your main PC (the machine that will run this server)
and log in → Download. On macOS/Windows
it's a normal app; on Linux it's
curl -fsSL https://tailscale.com/install.sh | shthensudo tailscale up. - Install Tailscale on your phone (iOS / Android) and log in with the same account.
That's the whole setup. Both devices are now on your private tailnet and can see each other. MagicDNS is on by default, so you don't even need to memorize an IP — you can use your PC's machine name. No ports to open, no router settings.
How do I find my PC's address? On the main PC, run:
tailscale ip -4 # → e.g. 100.101.102.103 (your tailnet IP)
You'll reach the app from your phone at http://100.101.102.103:4000 — or, with
MagicDNS, http://<your-pc-name>:4000 (the name shown in the Tailscale app /
admin console). The first-run
wizard (next step) also prints this URL with a QR code so you can just point
your phone's camera at the screen.
3. Clone & install
git clone https://github.com/KoichiIshiguro/claude-code-remote.git
cd claude-code-remote
npm install
4. Run it
npm start
Open http://localhost:4000 — you'll be redirected to /setup, the first-run wizard. Pick a username, password, and an access scope (a single folder to sandbox to, or full disk access on a trusted tailnet). Done.
After setup, sign in from your phone at http://<tailscale-ip>:4000 (the wizard shows you the URL + a QR code).
Forgot the address, or didn't write it down? You don't need to re-run setup. Open the app on the machine, click the ⚙ (system settings) button at the top of the left "Projects" sidebar, and hit 📡 アドレスを確認 (Check address). It lists every URL this server is reachable at — Tailscale IP & MagicDNS name, LAN, localhost (port included) — with a one-tap copy button and a QR code to scan from your phone. (It detects Tailscale even when the
tailscaleCLI isn't on your PATH, e.g. the macOS GUI app.)
5. (Strongly recommended) Give the server a long-lived auth token
The server runs the real claude CLI in headless -p mode — a fresh claude
process per prompt. Each of those processes authenticates from the OAuth
credentials Claude persists on disk / in your login Keychain, and those stored
credentials go stale over time: the short-lived access token expires and the
saved refresh token eventually gets rotated out and rejected by the server. When
that happens every prompt fails with:
401 Invalid authentication credentials
…even when you started the server by hand on your own GUI machine. The
confusing part: the interactive claude TUI keeps working the whole time — a
long-running session refreshes its token in memory at startup and never writes it
back — so "the TUI still logs in fine" does not mean the server's -p calls
do. (Background launchd/systemd services have it worse: they run outside your GUI
login session and can't read the Keychain at all.)
The robust fix, for any deployment, is a long-lived token that doesn't depend on the stored credentials. On the machine, in a real terminal (a TTY is required — this opens a browser):
claude setup-token # authorize in the browser; prints sk-ant-oat01-...
Put the printed token in this directory's .env and (re)start the server:
echo 'CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...' >> .env
npm start
.env is gitignored, so the token stays on this machine. The server forwards it
to every spawned claude, so auth no longer depends on the (possibly stale)
Keychain copy. To sanity-check the token on its own:
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-... claude -p "reply with: ok"
If that prints ok, the server will authenticate too. The token is long-lived;
you only redo this if you revoke it or rotate your credentials.
Forgot your username or password?
There is no recovery email and no "forgot password" link by design (single-user, personal-use). To reset:
node server.js --reset-auth
This deletes data/admin.json and exits. The next npm start will redirect to /setup so you can pick a fresh username + password. Your config.json, project list, and conversation history (jsonl) are untouched.
(Optional) Run on boot
If you want the server to come up automatically when the machine restarts, wire it up with launchd (macOS), systemd (Linux), or the Windows Task Scheduler — pointing at node server.js in this directory.
⚠️ Background services must have the long-lived token from step 5. A launchd/systemd agent runs outside your GUI login session and can't read the login Keychain at all, so without
CLAUDE_CODE_OAUTH_TOKENin.envevery prompt fails with401 Invalid authentication credentials. Set up the token as shown in step 5 before registering the service.
(Optional) Public HTTPS
If you want to expose this on the open internet instead of Tailscale, don't — but if you must, terminate TLS in front (Apache / Caddy / nginx), add HTTP basic-auth at the proxy on top of the built-in ID/PW, and seriously consider narrowing the access scope to a sandboxed subtree.
🆚 Comparison
| Claude Code Remote | siteboon/claudecodeui | d-kimuson/claude-code-viewer | |
|---|---|---|---|
| LOC | ~3,000 | 50k+ | 30k+ |
| Auth | Local ID/PW + Tailscale | None / token | Single password |
| Frontend | Vanilla JS (no build step) | React + Vite | React + Vite |
| In-flight response persistence | ✅ | ❌ | ❌ |
| Image paste | ✅ | ❓ | ✅ |
| PWA | ✅ | ❓ | ✅ |
| WebSocket auto-reconnect | ✅ | ❓ | ❓ |
| Multi-project switcher | ✅ | ✅ | ✅ |
| Multiple sessions per project | ✅ | ❓ | ✅ |
| Bring-your-own auth | Drop-in via reverse proxy | Same | Same |
| Read the whole source | ~1 hour | A week | Several days |
Bottom line: if you want a CodeMirror-based editor and a built-in Git GUI, use CloudCLI. If you want a chat window that just works and that you can fork in a weekend, use this.
🏗️ How it Works
┌─────────────────┐ HTTPS ┌──────────────────┐
│ Browser / PWA │ ◄────────► │ Reverse Proxy │
│ (iOS / Desktop) │ │ (Apache / Caddy) │
└─────────────────┘ └────────┬─────────┘
│ HTTP + WS
▼
┌──────────────────┐
│ Node.js server │
│ (this repo) │
│ • Express │
│ • ws │
│ • bcrypt session │
└────────┬─────────┘
│ spawn() per prompt
▼
┌──────────────────┐
│ claude CLI │
│ -p --resume <id> │
│ --output-format │
│ stream-json │
└──────────────────┘
Key design choices
- One
claudeprocess per prompt. No long-lived background agents. Conversation state lives in Claude's own~/.claude/projects/*.jsonland is restored via--resume. - In-flight responses are streamed to disk every 500 ms (debounced). If the server is killed mid-response, reattach renders the partial output and lets you say "continue" — Claude resumes via
--resume. - Images are passed as file paths (
/abs/path/to/image.png) embedded in the prompt — the same way Claude Code's TUI handles drag-and-drop. - No build step. The frontend is
<script>+ Vanilla JS + a singlemarkedimport. You cannpm installover a flaky mobile tether and still ship. - Context tracked from per-call
usage. Eachassistantstream event carries the actual input-token count of that API call (not a turn-aggregate); the meter and the auto-compact decision both read from it, so behavior matches Claude Code TUI's own/compactthreshold. - The prompt queue lives on the server, not the browser. Prompts sent while a turn is streaming accumulate in a per-session queue and the runner drains them browser-independently — close the tab and they still fire. The live queue is in-memory (a restart clears it, by design); scheduled prompts are the persistent cousin, saved to
data/scheduled-prompts.json. When due, the runner pulls them at the top of each turn ahead of the live queue, so a reservation whose time arrives while a turn is still running fires the instant that turn finishes (a 30 s timer only wakes idle sessions — it never fires them itself, so nothing is lost or orphaned mid-turn).
🔧 Configuration Reference
All configuration is optional — the first-run wizard at /setup writes admin credentials and the access scope to data/admin.json and data/config.json, the registered projects live in data/projects.json, and the session secret is auto-generated. Use env vars only to override these defaults.
| Env var | Description |
|---|---|
PORT | HTTP port. Default 4000 |
CLAUDE_PATH | Absolute path to claude — set when PATH isn't inherited (PM2 / systemd / launchd) |
CLAUDE_CODE_OAUTH_TOKEN | Long-lived auth token from claude setup-token. Strongly recommended for any server run (the persisted Keychain/disk OAuth creds go stale and claude -p then 401s even on your own machine), and required under launchd/systemd (can't read the Keychain at all). See step 5 above |
SESSION_SECRET | Override the auto-generated one (useful for shared cookie domains across deployments) |
CLAUDE_AUTO_COMPACT_THRESHOLD | Input-token count that triggers an auto-/compact before the next prompt. Default 167000 (TUI's ~83.5% trigger on 200k-context models). Set to e.g. 835000 for 1M tiers |
TMUX_PATH | Absolute path to tmux for the built-in terminal — set when it isn't on PATH. Auto-detected via which tmux otherwise; falls back to a plain shell if tmux is absent |
CCR_SHELL | Override the shell the terminal launches (default: $SHELL -l, or powershell.exe on Windows) |
NODE_ENV=production | Enforce HTTPS-only session cookies. Only set when terminating TLS in front |
CLAUDE_SANDBOX | macOS only. 0 disables the per-session OS sandbox. On by default — see Security Notes |
🛡️ Security Notes
- Designed to live on Tailscale, not on the public internet. A single bcrypt-hashed password (set at
/setup, stored indata/admin.json) is not enough to survive sustained brute-force from the open web. Keep this on your private tailnet, or put HTTP basic-auth in front of it at the reverse proxy if you must expose it. - HTTPS is still required for any non-Tailscale exposure. Session cookies in cleartext are immediately game-over.
--dangerously-skip-permissionsis on by default because this UI is your personal remote. If you expose it, you're trusting Claude with your filesystem — narrow the access scope to a safe subtree.- Per-session OS sandbox (macOS). Even with
--dangerously-skip-permissions, each spawnedclaudeis wrapped insandbox-exec(kernel-level Seatbelt) so it cannot write anywhere outside its own session folder (plus~/.claudeand temp) and cannot read sibling projects or climb above the session folder — enforced on the syscall, so it holds againstbash/cattoo. The Node server itself is not sandboxed (it needs full access for the picker, git clone, and the file viewer); only the LLM child is. Auth (~/.claude.json+ Keychain) stays reachable so Claude still works. macOS-only; setCLAUDE_SANDBOX=0to disable. No effect on Linux/Windows yet. - Single-user by design. There is no multi-user mode and no admin panel. That is the entire security model.
- Session store is file-backed (
data/auth-sessions.json, atomic writes viasrc/session-store.js), so a server restart or PM2 reload no longer signs you out. Swap toconnect-sqlite3/connect-redisif you outgrow a single JSON file.
🗺️ Roadmap
- Persistent session store so a restart / PM2 reload doesn't sign you out
- Docker image
- CodeMirror live editing in the file viewer
- Push notifications when long prompts finish
- Multi-user via OAuth groups (probably never — that's not the design)
Roadmap items are tracked in issues. Feature requests and bug reports are welcome there.
🤝 Contributing
Pull requests are not accepted. This project is maintained as a single-author codebase. Please file issues for bugs and feature requests — they're read and triaged, just not merged from outside the repo.
If you want a local development setup for your own use:
git clone https://github.com/KoichiIshiguro/claude-code-remote.git
cd claude-code-remote
pnpm install # or: npm install
cp .env.example .env # fill in your secrets
pnpm dev # auto-restart on file change
📜 License
PolyForm Internal Use 1.0.0 — source-available for internal use only.
You may:
- Clone, build, run, and modify the software for your own internal business use (personal or company-internal)
- Self-host it on any infrastructure you control
You may not:
- Distribute the software or any derivative work to third parties (modified or unmodified, free or paid)
- Provide it as a hosted/managed service to third parties
- Re-publish forks of this repository
Versions v0.6.0 and earlier remain available under the MIT License. The license change applies from the first commit following the v0.6.0 release.
claude is Anthropic's commercial product and is not bundled with this repo. You need your own Claude account / API access.
Built because every remote-Claude UI on GitHub was either bloated, abandoned, or both.
If this saved you a weekend, ⭐ star the repo — that's the only reward this project asks for.