tmux observer
Sweep surveillance vocabulary from owner-facing docs
Apply system-anatomy canon to README, INSTALL, AGENTS. Lead with
"observers" / "experiences along with" / "observations" in branded
prose. Preserve all internal-architecture and code-identifier uses
of `capture` (Capture Loop heading, capture.py module, captures/
on-disk path, capture_interval config key). Add a Brand canon
pointer section in AGENTS.md mirroring the solstone-linux precedent.
+18
-8
+12
-2
AGENTS.md
+12
-2
AGENTS.md
···
4
4
5
5
## Project Overview
6
6
7
-
solstone-tmux is a companion app that runs alongside the main solstone journal. It captures all active tmux terminal sessions every 5 seconds, accumulates captures into 5-minute segments in a local cache, and syncs completed segments to the solstone ingest API. Pure Python, no system dependencies beyond tmux itself. Works offline -- segments sync when the server becomes available. Recovers incomplete segments on startup after crashes.
7
+
solstone-tmux is one of the owner's observers. It experiences tmux sessions along with the owner — every 5 seconds it takes in what's on each active pane, accumulating observations into 5-minute segments in a local cache, and syncing completed segments to the solstone ingest API. Pure Python, no system dependencies beyond tmux itself. Works offline -- segments sync when the server becomes available. Recovers incomplete segments on startup after crashes.
8
8
9
-
This is a **solstone observer** -- a standalone capture agent that feeds data into a solstone journal. It follows the same patterns as solstone-macos (the macOS screen/audio observer) but captures terminal content instead of screen recordings.
9
+
This is a **solstone observer** -- a standalone companion that feeds observations into a solstone journal. It follows the same patterns as solstone-macos (the macOS screen/audio observer) but experiences terminal content instead of screen and audio.
10
10
11
11
## Source Layout
12
12
···
97
97
"segment_interval": 300
98
98
}
99
99
```
100
+
101
+
## Brand canon
102
+
103
+
- **solstone-tmux is an observer.** In the system anatomy, `solstone = observers + sol agent + journal`. This repo implements one of those observers.
104
+
- **The canon lives elsewhere.** Owner-facing terminology comes from `~/projects/extro/cmo/brand/system-anatomy.md`. The companion is `~/projects/extro/cmo/brand/voice-terminology.md`.
105
+
- **Use co-experience language in branded prose.** In README, INSTALL, onboarding text, settings copy, and error messages, describe solstone-tmux as something that experiences tmux sessions along with the owner. Never describe it as watching, capturing, recording, monitoring, or tracking the owner.
106
+
- **Keep code language in code-only contexts.** Internal architecture terms such as the `Capture Loop` heading, the `capture.py` module, the `~/.local/share/solstone-tmux/captures/` on-disk path, and the `capture_interval` config key are canon-permitted here and must not be renamed just to match branded prose.
107
+
- **Edit with the surface in mind.** If the owner sees the string, follow the canon. If the text is naming code, pipelines, modules, or storage artifacts for engineers, the existing internal vocabulary stays.
108
+
109
+
Canon source of truth: `~/projects/extro/cmo/brand/system-anatomy.md`.
100
110
101
111
## License
102
112
+2
-2
INSTALL.md
+2
-2
INSTALL.md
···
1
1
# installing solstone-tmux
2
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.
3
+
these instructions are for a coding agent and human working together. solstone-tmux experiences your tmux sessions along with you — every 5 seconds it takes in what's on each pane. lightweight, pure python, no system dependencies. works alongside a desktop observer or standalone.
4
4
5
5
solstone must already be installed and running. if it isn't, start there: https://solstone.app/install
6
6
···
80
80
## notes
81
81
82
82
- if pipx is not installed: `pip install --user pipx` or install via your package manager.
83
-
- captures work offline — segments sync when the server becomes available.
83
+
- the observer works offline — segments sync when the server becomes available.
+4
-4
README.md
+4
-4
README.md
···
1
1
# solstone-tmux
2
2
3
-
Standalone tmux terminal observer for [solstone](https://solpbc.org). Captures tmux terminal sessions to a local cache and syncs them to a solstone server.
3
+
Standalone tmux terminal observer for [solstone](https://solpbc.org). Experiences your tmux sessions along with you, accumulating observations to a local cache and syncing them to a solstone server.
4
4
5
5
## Install
6
6
···
66
66
## How it works
67
67
68
68
- Polls all active tmux sessions every 5 seconds for content changes
69
-
- Accumulates captures in 5-minute segments under `~/.local/share/solstone-tmux/captures/`
69
+
- Accumulates observations in 5-minute segments under `~/.local/share/solstone-tmux/captures/`
70
70
- Background sync service uploads completed segments to the solstone ingest API
71
-
- Captures offline — syncs when server becomes available
71
+
- Works offline — syncs when server becomes available
72
72
- Recovers incomplete segments on startup after crashes
73
73
74
74
## Commands
···
78
78
| `solstone-tmux run` | Start capture + sync (default if no subcommand) |
79
79
| `solstone-tmux setup` | Interactive config wizard |
80
80
| `solstone-tmux install-service` | Install and start systemd user service |
81
-
| `solstone-tmux status` | Show capture state, sync state, cache size |
81
+
| `solstone-tmux status` | Show observer state, sync state, cache size |
82
82
83
83
## License
84
84