tmux observer
Add INSTALL.md for agent-human collaborative setup
Instructions written for a coding agent working with a human.
Includes idempotency check, sol root/observers clone path,
and stream naming convention as a collaborative decision point.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+62
+62
INSTALL.md
+62
INSTALL.md
···
1
+
# installing solstone-tmux
2
+
3
+
these instructions are for a coding agent and human working together. solstone-tmux captures all active tmux sessions and panes every 5 seconds. lightweight, pure python, no system dependencies. works alongside a desktop observer or standalone.
4
+
5
+
solstone must already be installed and running. if it isn't, start there: https://solstone.app/install
6
+
7
+
## before you begin
8
+
9
+
if `sol` is not in PATH, check `~/.local/bin/sol` or use `.venv/bin/sol` inside the solstone repo.
10
+
11
+
check if solstone-tmux is already installed and running:
12
+
13
+
```
14
+
systemctl --user status solstone-tmux
15
+
sol remote list
16
+
```
17
+
18
+
if it's already active and connected, you're done.
19
+
20
+
## what to sort out together
21
+
22
+
- **stream name.** this identifies the capture source. the convention is `hostname.tmux` (e.g., `fedora.tmux`).
23
+
24
+
## install sequence
25
+
26
+
1. if not already cloned, clone into solstone's observers directory and install with pipx:
27
+
```
28
+
cd "$(sol root)/observers"
29
+
git clone https://github.com/solpbc/solstone-tmux.git
30
+
cd solstone-tmux
31
+
pipx install .
32
+
```
33
+
34
+
2. register the observer with solstone and save the API key:
35
+
```
36
+
sol remote create solstone-tmux
37
+
```
38
+
39
+
3. write the config to `~/.local/share/solstone-tmux/config/config.json`:
40
+
```json
41
+
{
42
+
"server_url": "http://localhost:5015",
43
+
"key": "THE_API_KEY_FROM_STEP_2",
44
+
"stream": "HOSTNAME.tmux"
45
+
}
46
+
```
47
+
48
+
4. install and start the systemd user service:
49
+
```
50
+
solstone-tmux install-service
51
+
```
52
+
53
+
5. verify it's running and connected:
54
+
```
55
+
systemctl --user status solstone-tmux
56
+
sol remote list
57
+
```
58
+
59
+
## notes
60
+
61
+
- if pipx is not installed: `pip install --user pipx` or install via your package manager.
62
+
- captures work offline — segments sync when the server becomes available.