tmux observer
Improve README: document sol remote create setup flow
The proper setup path is sol remote create → write config → install
service, not just the interactive wizard. Document the full flow with
the config file format and verification steps.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+53
-10
+53
-10
README.md
+53
-10
README.md
···
6
6
7
7
```bash
8
8
pipx install solstone-tmux
9
+
# or
10
+
uv tool install solstone-tmux
9
11
```
10
12
11
13
## Setup
14
+
15
+
### 1. Register a remote observer on the solstone server
12
16
13
17
```bash
14
-
solstone-tmux setup
18
+
sol remote create solstone-tmux
15
19
```
16
20
17
-
Prompts for your solstone server URL and auto-registers an observer key.
21
+
This prints the server URL and API key. You'll need both for the next step.
18
22
19
-
## Run
23
+
### 2. Write the config
24
+
25
+
Create `~/.local/share/solstone-tmux/config/config.json`:
26
+
27
+
```json
28
+
{
29
+
"server_url": "http://localhost:8000",
30
+
"key": "<api-key-from-sol-remote-create>",
31
+
"stream": "<hostname>.tmux",
32
+
"capture_interval": 5,
33
+
"segment_interval": 300
34
+
}
35
+
```
36
+
37
+
Set `stream` to `<your-hostname>.tmux` (e.g., `fedora.tmux`, `archon.tmux`). This matches the stream naming convention used by the built-in observers.
38
+
39
+
Alternatively, `solstone-tmux setup` runs an interactive wizard that prompts for the server URL and auto-registers.
40
+
41
+
### 3. Install the systemd service
20
42
21
43
```bash
22
-
# Run directly
23
-
solstone-tmux run
44
+
solstone-tmux install-service
45
+
```
46
+
47
+
This writes the unit file to `~/.config/systemd/user/solstone-tmux.service`, enables it, and starts it.
24
48
25
-
# Or install as a systemd user service
26
-
solstone-tmux install-service
49
+
### 4. Verify
50
+
51
+
```bash
27
52
systemctl --user status solstone-tmux
53
+
solstone-tmux status
54
+
sol remote list # should show the new remote as "connected"
28
55
```
29
56
30
-
## Status
57
+
## Manual run
31
58
32
59
```bash
33
-
solstone-tmux status
60
+
solstone-tmux run # foreground, ctrl-c to stop
61
+
solstone-tmux run -v # verbose/debug logging
34
62
```
35
63
36
-
Shows capture state, sync state, cache size, and last sync time.
64
+
## How it works
65
+
66
+
- Polls all active tmux sessions every 5 seconds for content changes
67
+
- Accumulates captures in 5-minute segments under `~/.local/share/solstone-tmux/captures/`
68
+
- Background sync service uploads completed segments to the solstone ingest API
69
+
- Captures offline — syncs when server becomes available
70
+
- Recovers incomplete segments on startup after crashes
71
+
72
+
## Commands
73
+
74
+
| Command | What it does |
75
+
|---------|-------------|
76
+
| `solstone-tmux run` | Start capture + sync (default if no subcommand) |
77
+
| `solstone-tmux setup` | Interactive config wizard |
78
+
| `solstone-tmux install-service` | Install and start systemd user service |
79
+
| `solstone-tmux status` | Show capture state, sync state, cache size |
37
80
38
81
## License
39
82