Skip to content

Commit e537a64

Browse files
morganlintonmorganlinton
committed
docs: major README polish for v0.1.0 launch
1 parent d0acfd0 commit e537a64

1 file changed

Lines changed: 151 additions & 57 deletions

File tree

‎README.md‎

Lines changed: 151 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,129 +1,223 @@
11
# pastelocal
22

3-
**Your clipboard, everywhere.**
3+
![Header](assets/pastelocal-header.png)
44

5-
Secure, fast clipboard sharing between your local machine and remote hosts over SSH — built for developers who live in the terminal and use tools like Claude.
5+
**Secure clipboard sharing over SSH for remote work and AI tools like Claude.**
6+
7+
PasteLocal lets you access your local clipboard (including screenshots) from any remote machine over SSH — with zero friction. Built for developers who live in the terminal and use tools like Claude, Cursor, or custom AI agents.
8+
9+
---
10+
11+
## Why PasteLocal?
12+
13+
When you SSH into a server, your local clipboard disappears. You take a screenshot or copy some text, switch to the remote shell, and suddenly you can't paste it.
14+
15+
PasteLocal solves this elegantly:
16+
17+
- Works over your existing SSH connection (no new ports or services exposed)
18+
- Extremely simple remote command (`pastelocal-remote`)
19+
- Excellent Claude / AI coding assistant integration via skills
20+
- History, named snippets, and more
621

722
---
823

9-
## 30-Second Start
24+
## 60-Second Quick Start
1025

1126
```bash
12-
# 1. Install
13-
go install github.com/pastelocal/pastelocal/cmd/pastelocal@latest
27+
# 1. Install (or build from source)
28+
go install github.com/Zen-Open-Source/PasteLocal/cmd/pastelocal@latest
1429

15-
# 2. Initialize (generates token, installs daemon)
30+
# 2. Initialize everything
1631
pastelocal init
1732

18-
# 3. Add a remote host
33+
# 3. Add a remote host (automatically edits your SSH config)
1934
pastelocal add-host myserver
2035

21-
# 4. On the remote, just run:
36+
# 4. SSH into the server and run:
2237
pastelocal-remote
2338
```
2439

25-
PasteLocal copies your local clipboard (including screenshots) to any remote machine via an encrypted SSH tunnel. Works great with Claude, Cursor, and any terminal-based workflow.
40+
That's it. `pastelocal-remote` will print a file path. Claude (or any tool) can read the image directly from that path.
2641

2742
---
2843

2944
## Features
3045

31-
- **One-command remote clipboard** — `pastelocal-remote` just works over any SSH connection
32-
- **Claude skills** — `/paste`, `/paste-history`, `/paste-snippet`, `/paste-send`
33-
- **Clipboard history** — Go back to previous copies with `--list` and `--index`
34-
- **Named snippets** — Save and recall frequently used text or images
35-
- **TUI dashboard** — `pastelocal` shows daemon status, hosts, and recent activity
36-
- **Doctor + auto-fix** — `pastelocal doctor --fix` diagnoses and repairs most issues
37-
- **Termius support** — Works with Termius and other SSH clients
38-
- **Experimental: Multi-device relay** — E2E encrypted clipboard sync between machines without SSH tunnels (see below)
46+
### Core Workflow
47+
- One-command remote clipboard access via SSH tunnel
48+
- Full support for images (screenshots) and text
49+
- Works with any SSH client (including Termius)
50+
51+
### Claude & AI Integration
52+
- `/paste` — Paste current clipboard
53+
- `/paste-history` — Choose from recent clipboard entries
54+
- `/paste-snippet` — Recall saved named snippets
55+
- `/paste-send` — Send files from the remote machine back to your local clipboard
56+
57+
### Productivity Tools
58+
- **Clipboard History** — Go back in time with `pastelocal-remote --list`
59+
- **Named Snippets** — Save frequently used text or images locally
60+
- **TUI Dashboard** — Run `pastelocal` to see daemon status, hosts, and recent activity
61+
- **Doctor** — `pastelocal doctor --fix` automatically diagnoses and repairs most issues
62+
63+
### Experimental
64+
- **Multi-device Relay** — E2E encrypted clipboard sync without SSH tunnels (see below)
3965

4066
---
4167

42-
## Experimental: Relay Mode
68+
## Installation
4369

44-
PasteLocal includes an experimental relay server for clipboard sharing between multiple devices without requiring persistent SSH tunnels.
70+
### Recommended: Go Install
4571

46-
**Status:** Experimental / Preview
72+
```bash
73+
go install github.com/Zen-Open-Source/PasteLocal/cmd/pastelocal@latest
74+
```
4775

48-
- Device pairing with X25519 + AES-GCM end-to-end encryption
49-
- Works today for receiving clipboard content from paired peers
50-
- Send path and full daemon integration are still in progress
76+
### Build from Source
5177

52-
Use at your own risk. The core SSH path is the recommended, production-ready experience.
78+
```bash
79+
git clone https://github.com/Zen-Open-Source/PasteLocal.git
80+
cd PasteLocal
81+
make build
82+
```
83+
84+
Binaries will be in the `bin/` directory.
85+
86+
> **Note:** The Go module path is currently being aligned with the new repository location. Building from source is the most reliable method until the first stable release.
5387
5488
---
5589

56-
## Installation
90+
## Usage Examples
5791

58-
### From source (recommended for now)
92+
### Basic Remote Clipboard
5993

6094
```bash
61-
go install github.com/pastelocal/pastelocal/cmd/pastelocal@latest
95+
# On your remote server
96+
pastelocal-remote
97+
# → /home/user/.cache/pastelocal/pastelocal-abc123.png
98+
```
99+
100+
### Using with Claude
101+
102+
Add this to your Claude project or global commands:
103+
104+
```markdown
105+
Run `pastelocal-remote` on the remote host. It will print a file path.
106+
Use the Read tool on that path to get the clipboard content.
62107
```
63108

64-
### Build from source
109+
### Clipboard History
65110

66111
```bash
67-
git clone https://github.com/pastelocal/pastelocal.git
68-
cd pastelocal
69-
make build
112+
pastelocal-remote --list
113+
pastelocal-remote --list --index 3
70114
```
71115

72-
Binaries will be in the `bin/` directory.
116+
### Named Snippets
117+
118+
On your local machine:
119+
120+
```bash
121+
pastelocal snippets save api-key
122+
pastelocal snippets save deploy-script --description "Common deploy command"
123+
```
124+
125+
On the remote:
126+
127+
```bash
128+
pastelocal-remote --snippet api-key
129+
```
130+
131+
---
132+
133+
## Experimental: Multi-Device Relay
134+
135+
PasteLocal has an **experimental** relay system that allows clipboard sharing between multiple devices without requiring direct SSH tunnels.
136+
137+
**Current Status:** Experimental / Preview
138+
139+
**What works today:**
140+
- Device pairing with end-to-end encryption (X25519 + AES-GCM)
141+
- Receiving clipboard content from paired peers via `pastelocal-remote --relay`
142+
143+
**What is still in progress:**
144+
- Reliable sending from the local daemon
145+
- Background notifications
146+
- Persistence across relay restarts
147+
148+
**Recommendation:** Use the SSH-based workflow for daily work. The relay is intended for testing and specific multi-machine setups.
73149

74150
---
75151

76152
## How It Works
77153

78154
```
79-
Local Machine Remote Host
80-
┌──────────────┐ ┌────────────────────┐
81-
│ Your OS │ │ Claude / Terminal │
82-
│ Clipboard │◄── SSH ──────│ pastelocal-remote │
83-
│ │ tunnel │ │
84-
│ pastelocald │ │ ~/.cache/pastelocal/│
85-
│ :7331 │ └────────────────────┘
155+
Your Laptop Remote Server
156+
┌──────────────┐ ┌─────────────────────┐
157+
│ Local │ │ Claude / Terminal │
158+
│ Clipboard │◄── SSH ───────│ pastelocal-remote │
159+
│ │ tunnel │ │
160+
│ pastelocald │ └─────────────────────┘
161+
│ :7331 │
86162
└──────────────┘
87163
```
88164

89-
The daemon only listens on loopback. All traffic travels over your existing encrypted SSH connection.
165+
Everything travels over your existing encrypted SSH connection. No new ports are opened.
90166

91167
---
92168

93-
## Documentation
169+
## Configuration
94170

95-
- [Full Documentation](docs/README.md)
96-
- [Architecture](docs/ARCHITECTURE.md)
97-
- [Security Model](docs/SECURITY.md)
98-
- [Error Codes](docs/ERROR_CODES.md)
99-
- [Termius Setup](docs/TERMIUS.md)
171+
Configuration lives at `~/.config/pastelocal/config.toml`.
100172

101-
---
173+
Key options:
102174

103-
## Status
175+
```toml
176+
[history]
177+
enabled = true
178+
size = 20
179+
ttl_seconds = 3600
104180

105-
PasteLocal is actively used in production by the author for daily remote work with Claude.
181+
[relay]
182+
enabled = false # Experimental
183+
relay_url = "http://localhost:7332"
184+
auto_upload = false
185+
```
106186

107-
The core SSH clipboard bridge is stable. History, snippets, and the TUI are solid. The multi-device relay is experimental and under active development.
187+
Run `pastelocal` (the TUI) or `pastelocal doctor` to inspect your setup.
108188

109189
---
110190

111-
## Contributing
191+
## Troubleshooting
192+
193+
Run this first:
194+
195+
```bash
196+
pastelocal doctor --fix
197+
```
112198

113-
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and how to submit changes.
199+
Common issues and fixes are documented in the full docs:
200+
- [Troubleshooting](docs/README.md#troubleshooting-top-10)
201+
- [Error Codes](docs/ERROR_CODES.md)
114202

115203
---
116204

117-
## License
205+
## Contributing
118206

119-
MIT © pastelocal contributors
207+
Contributions are very welcome!
208+
209+
- Read [CONTRIBUTING.md](CONTRIBUTING.md)
210+
- Check the [Architecture](docs/ARCHITECTURE.md) document
211+
- Open an issue or pull request
212+
213+
We especially welcome improvements to the relay feature and better Claude skill examples.
120214

121215
---
122216

123-
## Acknowledgments
217+
## License
124218

125-
Built out of frustration with constantly switching between local screenshots and remote terminals. Special thanks to everyone who has dealt with "I can't paste this here."
219+
MIT © Zen Open Source contributors
126220

127221
---
128222

129-
*Clipboard infrastructure for people who ssh.*
223+
*Built out of frustration with constantly switching between local screenshots and remote terminals.*

0 commit comments

Comments
 (0)