claude-relay 2.5.1 → 2.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +281 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
# Clay
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="media/phone.gif" alt="Clay on phone" width="300">
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h3 align="center">Web UI for Claude Code. Any device. Push notifications.</h3>
|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/claude-relay) [](https://www.npmjs.com/package/claude-relay) [](https://github.com/chadbyte/claude-relay) [](https://github.com/chadbyte/claude-relay/blob/main/LICENSE)
|
|
10
|
+
|
|
11
|
+
Claude Code. Anywhere.
|
|
12
|
+
Same session. Same files. Same machine.
|
|
13
|
+
Your files stay on your computer. Nothing leaves for the cloud.
|
|
14
|
+
|
|
15
|
+
Pick up the same Claude Code session on your phone.
|
|
16
|
+
Start in the terminal, continue on your phone, switch back anytime.
|
|
17
|
+
|
|
18
|
+
Claude Code is automating more of your editing and execution workflow.
|
|
19
|
+
But when it needs approval or asks a question, it halts in the terminal. If you walk away, it just sits there waiting.
|
|
20
|
+
|
|
21
|
+
claude-relay eliminates this bottleneck.
|
|
22
|
+
It is not a thin wrapper that intercepts input/output. It drives Claude Code via the Claude Agent SDK and relays the stream from your local machine to your browser.
|
|
23
|
+
|
|
24
|
+
Get approval notifications while grabbing a coffee.
|
|
25
|
+
Continue working from the sofa on your iPad.
|
|
26
|
+
Split your browser: claude-relay on one side, your app preview on the other, and watch the code change in real time.
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
cd ~/your-project
|
|
30
|
+
npx claude-relay
|
|
31
|
+
# First run: Set Port/PIN -> Scan QR -> Connect
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Never Miss an Approval
|
|
37
|
+
|
|
38
|
+
When Claude Code requests permission before executing a tool, you get a notification on your phone.
|
|
39
|
+
One tap, and Claude Code gets back to work.
|
|
40
|
+
|
|
41
|
+
<p align="center">
|
|
42
|
+
<img src="media/push-notification.jpg" alt="push notification" width="300">
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
It works in browser tabs too. When input is awaited, the favicon blinks and the tab title changes to alert you.
|
|
46
|
+
|
|
47
|
+
## Side by Side Workflow
|
|
48
|
+
|
|
49
|
+
<p align="center">
|
|
50
|
+
<img src="media/split.gif" alt="split-screen workflow" width="700">
|
|
51
|
+
</p>
|
|
52
|
+
|
|
53
|
+
Keep claude-relay on one side and your localhost on the other.
|
|
54
|
+
Watch the results update live while Claude Code fixes your source files.
|
|
55
|
+
|
|
56
|
+
Mermaid diagrams render as diagrams, and tables appear as actual tables.
|
|
57
|
+
You can explore files in the sidebar and use the built-in terminal to run shell commands.
|
|
58
|
+
|
|
59
|
+
## All in One Place
|
|
60
|
+
|
|
61
|
+
Run `npx claude-relay` in each project to register them to the same server.
|
|
62
|
+
Manage all your active sessions from a single dashboard.
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
cd ~/projects/backend && npx claude-relay # Register project
|
|
66
|
+
cd ~/projects/frontend && npx claude-relay # Adds to the same server
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The server runs in the background. Even if you close the terminal window, your sessions and the server remain active.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Getting Started
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
npx claude-relay
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
<p align="center">
|
|
80
|
+
<img src="media/start.gif" alt="npx claude-relay" width="600">
|
|
81
|
+
</p>
|
|
82
|
+
|
|
83
|
+
On the first run, you'll set a port and PIN to launch the server.
|
|
84
|
+
Scan the QR code with your phone to connect instantly, or open the URL displayed in your terminal.
|
|
85
|
+
|
|
86
|
+
## Key Features
|
|
87
|
+
|
|
88
|
+
* **Push Approvals** - Approve or reject from your phone while away, so Claude Code does not get stuck waiting.
|
|
89
|
+
* **Multi Project Daemon** - Manage all projects via a single port. Add and remove projects from the browser.
|
|
90
|
+
* **Usage and Model Switching** - View token usage, rate limit bars, and switch models from the browser.
|
|
91
|
+
* **Session Search** - Full-text search across all session messages with hit timeline.
|
|
92
|
+
* **Auto Session Logs (JSONL)** - Conversations and execution history are always saved locally. No data loss on crashes or restarts. Location: `./.claude-relay/sessions/`
|
|
93
|
+
* **File Browser and Terminal** - Inspect files, execute commands, and manage multiple terminal tabs from the browser.
|
|
94
|
+
|
|
95
|
+
> Note: Session logs may contain prompts, outputs, and commands. Do not share this folder.
|
|
96
|
+
|
|
97
|
+
<details>
|
|
98
|
+
<summary>View Full Feature List</summary>
|
|
99
|
+
|
|
100
|
+
**Notifications**
|
|
101
|
+
|
|
102
|
+
* **Push Notifications** - Approvals, completions, errors, and questions. Add to Home Screen (PWA) to receive notifications without opening the app. Behavior depends on OS and browser. Tested on iPhone (Home Screen PWA) and desktop Chrome.
|
|
103
|
+
* **Favicon and Title Blinking** - Visual cues when input is awaited.
|
|
104
|
+
* **Sound Alerts** - Supports browser notifications, desktop notifications, and audio alerts.
|
|
105
|
+
|
|
106
|
+
**Projects and Sessions**
|
|
107
|
+
|
|
108
|
+
* **Multi Project** - Single port management for all projects. Add and remove projects from the browser with path autocomplete.
|
|
109
|
+
* **Project Names** - Custom names make it easy to distinguish tabs.
|
|
110
|
+
* **Session Persistence** - Sessions survive server restarts, browser crashes, and network drops.
|
|
111
|
+
* **Session Handoff** - Start in the terminal, continue on your phone, pass back to desktop. Browse and resume CLI sessions directly from the web UI.
|
|
112
|
+
* **Session Search** - Full-text search across all session content with highlighted results and a rewind-style hit timeline.
|
|
113
|
+
* **Rewind (Native Claude Code)** - Accessible directly from the browser UI.
|
|
114
|
+
* **Draft Persistence** - Unsent messages are saved per session and restored when you switch back.
|
|
115
|
+
|
|
116
|
+
**Rendering and Tools**
|
|
117
|
+
|
|
118
|
+
* **Mermaid and Markdown** - Proper rendering for diagrams, tables, and code blocks.
|
|
119
|
+
* **Syntax Highlighting** - Support for over 180 languages with copy buttons on every block.
|
|
120
|
+
* **File Browser** - Sidebar navigation with file previews, markdown rendering, and live-reload on external changes.
|
|
121
|
+
* **Built in Terminal** - Multi-tab terminal sessions with rename, reorder, and a mobile special-key toolbar.
|
|
122
|
+
* **Slash Commands** - Execute standard Claude Code commands from the browser, with autocomplete.
|
|
123
|
+
* **Usage Panel** - View token counts and rate limit progress bars via `/usage` command or header button.
|
|
124
|
+
* **Model Switching** - Change the active model directly from the browser header.
|
|
125
|
+
* **Plan Approval** - Review and approve Claude implementation plans from the browser UI.
|
|
126
|
+
|
|
127
|
+
**UI**
|
|
128
|
+
|
|
129
|
+
* **Mobile Optimized** - Large approve and reject buttons. Behaves like a native app via PWA.
|
|
130
|
+
* **Real time Sync** - All devices view the exact same session state.
|
|
131
|
+
* **QR Code** - Scan to connect instantly.
|
|
132
|
+
* **Image Paste and Camera** - Paste images from clipboard or attach photos directly from your camera.
|
|
133
|
+
* **Send While Processing** - Queue messages without waiting for the current response to finish.
|
|
134
|
+
* **Sticky Todo Overlay** - TodoWrite tasks float as a progress bar while you scroll through the conversation.
|
|
135
|
+
* **Scroll Position Hold** - Reading earlier messages will not get interrupted by new content arriving.
|
|
136
|
+
* **RTL Text Support** - Automatic bidirectional text rendering for Arabic, Hebrew, and other RTL languages.
|
|
137
|
+
|
|
138
|
+
**Server and Security**
|
|
139
|
+
|
|
140
|
+
* **Background Daemon** - Server persists even if the CLI is closed.
|
|
141
|
+
* **Keep Awake** - Prevents macOS sleep to keep sessions alive. Configurable toggle.
|
|
142
|
+
* **PIN Protection** - Restrict access with a 6 digit PIN.
|
|
143
|
+
* **HTTPS** - Automatic certificate generation via mkcert.
|
|
144
|
+
* **Zero Config** - Inherits your existing Claude Code configuration.
|
|
145
|
+
|
|
146
|
+
</details>
|
|
147
|
+
|
|
148
|
+
## Network
|
|
149
|
+
|
|
150
|
+
On the same Wi Fi, it just works. Open the URL shown in the terminal on any device.
|
|
151
|
+
|
|
152
|
+
For remote access, [Tailscale](https://tailscale.com) is recommended. Install it on both devices and log in with the same account to connect via an encrypted tunnel without port forwarding. Free for personal use.
|
|
153
|
+
|
|
154
|
+
## Security
|
|
155
|
+
|
|
156
|
+
claude-relay opens on your local network to allow access from other devices such as phones and tablets on the same Wi Fi.
|
|
157
|
+
Setting a PIN is highly recommended.
|
|
158
|
+
|
|
159
|
+
Anyone on your network with the URL and PIN can access the session. PIN protection can be enabled during the initial setup.
|
|
160
|
+
|
|
161
|
+
Do not expose this directly to the public internet. Usage on public or shared networks is not recommended.
|
|
162
|
+
For remote access, use [Tailscale](https://tailscale.com) or a VPN.
|
|
163
|
+
|
|
164
|
+
Users are responsible for their network configuration and exposure scope.
|
|
165
|
+
|
|
166
|
+
## HTTPS for Push
|
|
167
|
+
|
|
168
|
+
Basic features work out of the box. Only push notifications require HTTPS.
|
|
169
|
+
|
|
170
|
+
Set it up once using [mkcert](https://github.com/FiloSottile/mkcert):
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
brew install mkcert
|
|
174
|
+
mkcert -install
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Certificates are generated automatically. The setup wizard handles the rest.
|
|
178
|
+
|
|
179
|
+
If push registration fails: check whether your browser trusts HTTPS and whether your phone can access the address.
|
|
180
|
+
|
|
181
|
+
## CLI Options
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
npx claude-relay # Default (port 2633)
|
|
185
|
+
npx claude-relay -p 8080 # Specify port
|
|
186
|
+
npx claude-relay --yes # Skip interactive prompts (accept defaults)
|
|
187
|
+
npx claude-relay -y --pin 123456
|
|
188
|
+
# Non-interactive with PIN (for scripts/CI)
|
|
189
|
+
npx claude-relay --no-https # Disable HTTPS
|
|
190
|
+
npx claude-relay --no-update # Skip update check
|
|
191
|
+
npx claude-relay --debug # Enable debug panel
|
|
192
|
+
npx claude-relay --add . # Add current directory to running daemon
|
|
193
|
+
npx claude-relay --add /path # Add a project by path
|
|
194
|
+
npx claude-relay --remove . # Remove a project
|
|
195
|
+
npx claude-relay --list # List registered projects
|
|
196
|
+
npx claude-relay --shutdown # Stop the running daemon
|
|
197
|
+
npx claude-relay --dangerously-skip-permissions
|
|
198
|
+
# Bypass all permission prompts (PIN required during setup)
|
|
199
|
+
npx claude-relay --dev # Development mode (foreground, auto-restart on lib/ changes, port 2635)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Requirements
|
|
203
|
+
|
|
204
|
+
* [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
|
|
205
|
+
* Node.js 18+
|
|
206
|
+
* [mkcert](https://github.com/FiloSottile/mkcert) - For push notifications (optional)
|
|
207
|
+
* [Tailscale](https://tailscale.com) - For remote access (optional)
|
|
208
|
+
|
|
209
|
+
## Why claude-relay?
|
|
210
|
+
|
|
211
|
+
**Why not just use tmux + Termius?**
|
|
212
|
+
You can monitor the terminal remotely, but there are no push notifications and no way to approve permission requests without switching back to the terminal. On a phone, navigating a raw terminal session is clunky. You end up checking manually instead of getting notified, and the experience never feels native.
|
|
213
|
+
|
|
214
|
+
**Why not just add hooks to send notifications?**
|
|
215
|
+
Hooks with ntfy or Pushover can get you push notifications, but you still need shell scripts, config files, and third-party accounts just to get alerts. And once you get the notification, there is no UI to approve or reject from. You are back to opening a terminal. claude-relay gives you notifications, a one-tap approval UI, and a full web interface with a single command.
|
|
216
|
+
|
|
217
|
+
**Why not use Claude Code Desktop?**
|
|
218
|
+
The desktop app works great on your computer, but there is no mobile version. To access sessions from your phone, you need remote sessions on Anthropic's cloud, which requires pushing your code to GitHub first. claude-relay runs entirely on your machine and lets you connect from any device on your network.
|
|
219
|
+
|
|
220
|
+
**Why not use Happy Coder?**
|
|
221
|
+
Happy Coder requires installing a native app and routes through its own relay server with end-to-end encryption. claude-relay *is* the relay server, running on your machine. Open a URL and you are in. No app install, no signup, nothing leaves your network.
|
|
222
|
+
|
|
223
|
+
## Architecture
|
|
224
|
+
|
|
225
|
+
claude-relay is not a wrapper that intercepts standard input/output.
|
|
226
|
+
It is a local relay server that drives Claude Code execution via the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and streams data to the browser via WebSocket.
|
|
227
|
+
|
|
228
|
+
```mermaid
|
|
229
|
+
graph LR
|
|
230
|
+
Browser["Browser<br/>(Phone / Desktop)"]
|
|
231
|
+
WS["WebSocket"]
|
|
232
|
+
Server["HTTP Server<br/>lib/server.js"]
|
|
233
|
+
Project["Project Context<br/>lib/project.js"]
|
|
234
|
+
SDK["Claude Agent SDK"]
|
|
235
|
+
Claude["Claude Code<br/>Process"]
|
|
236
|
+
Push["Push Service"]
|
|
237
|
+
|
|
238
|
+
Browser <-->|Real time stream| WS
|
|
239
|
+
WS <--> Server
|
|
240
|
+
Server -->|slug routing| Project
|
|
241
|
+
Project <-->|async iterable| SDK
|
|
242
|
+
SDK <-->|Prompt / Response| Claude
|
|
243
|
+
Project -->|Approval request| Push
|
|
244
|
+
Push -->|Notification| Browser
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
For a detailed sequence diagram, daemon structure, and design decisions, refer to [docs/architecture.md](docs/architecture.md).
|
|
248
|
+
|
|
249
|
+
## Star History
|
|
250
|
+
|
|
251
|
+
<a href="https://star-history.com/#chadbyte/claude-relay&Date">
|
|
252
|
+
<picture>
|
|
253
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=chadbyte/claude-relay&type=Date&theme=dark" />
|
|
254
|
+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=chadbyte/claude-relay&type=Date" />
|
|
255
|
+
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=chadbyte/claude-relay&type=Date" width="600" />
|
|
256
|
+
</picture>
|
|
257
|
+
</a>
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
## Contributors
|
|
262
|
+
|
|
263
|
+
<a href="https://github.com/chadbyte/claude-relay/graphs/contributors">
|
|
264
|
+
<img src="https://contrib.rocks/image?repo=chadbyte/claude-relay" />
|
|
265
|
+
</a>
|
|
266
|
+
|
|
267
|
+
## Contributing
|
|
268
|
+
|
|
269
|
+
Bug fixes and typos are welcome. For feature suggestions, please open an issue first:
|
|
270
|
+
[https://github.com/chadbyte/claude-relay/issues](https://github.com/chadbyte/claude-relay/issues)
|
|
271
|
+
|
|
272
|
+
If you are using claude-relay, let us know how you are using it in Discussions:
|
|
273
|
+
[https://github.com/chadbyte/claude-relay/discussions](https://github.com/chadbyte/claude-relay/discussions)
|
|
274
|
+
|
|
275
|
+
## Disclaimer
|
|
276
|
+
|
|
277
|
+
This is an independent project and is not affiliated with Anthropic. Claude is a trademark of Anthropic.
|
|
278
|
+
|
|
279
|
+
## License
|
|
280
|
+
|
|
281
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "claude-relay",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.7.0",
|
|
4
4
|
"description": "Alias for clay-server — Web UI for Claude Code.",
|
|
5
5
|
"bin": { "claude-relay": "./bin/cli.js" },
|
|
6
|
-
"dependencies": { "clay-server": "2.
|
|
6
|
+
"dependencies": { "clay-server": "2.7.0" },
|
|
7
7
|
"keywords": ["claude","claude-code","cli","mobile","remote","relay","web-ui","tailscale"],
|
|
8
8
|
"repository": { "type": "git", "url": "git+https://github.com/chadbyte/claude-relay.git" },
|
|
9
9
|
"homepage": "https://github.com/chadbyte/claude-relay#readme",
|