happier-tui 0.0.0-stage → 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Cyril Peponnet
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,144 @@
1
- # Temporary Holding Version
1
+ # happier-tui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Drive your [Happier](https://github.com/happier-dev/happier) coding agents from a terminal.
4
+
5
+ Pick a session running on any of your machines, read it live, send prompts, answer permission
6
+ requests, start new sessions — and get a bell or a notification from your terminal, tmux or cmux
7
+ when an agent needs you.
8
+
9
+ ![happier-tui start screen](assets/main.png)
10
+
11
+ happier-tui is an independent, unofficial client. It talks to the Happier relay directly (HTTP and
12
+ Socket.IO, end-to-end encrypted) and is built on
13
+ [`@earendil-works/pi-tui`](https://www.npmjs.com/package/@earendil-works/pi-tui), the library
14
+ behind Pi's terminal UI.
15
+
16
+ ## Install
17
+
18
+ You need two things on the machine first:
19
+
20
+ - **Node.js 20 or newer** — check with `node --version`; install with `brew install node` on macOS
21
+ or from [nodejs.org](https://nodejs.org).
22
+ - **The Happier CLI, logged in** — `happier auth login`. happier-tui reuses the credentials the CLI
23
+ stores under `~/.happier`; it has no login of its own.
24
+
25
+ Then:
26
+
27
+ ```bash
28
+ git clone <repo-url> happier-tui
29
+ cd happier-tui
30
+ npm install # downloads dependencies and builds
31
+ npm install -g . # adds the `happier-tui` command
32
+ ```
33
+
34
+ Run `happier-tui`. To update later: `git pull && npm install` in the same folder. To remove it:
35
+ `npm uninstall -g happier-tui`.
36
+
37
+ Prefer not to install a command? Skip the last step and run `node dist/main.js` from the folder.
38
+
39
+ ## Use
40
+
41
+ ```
42
+ happier-tui start screen: pick or start a session
43
+ happier-tui <session-id-or-prefix> open a session directly
44
+ happier-tui --list [--all] print active (or all) sessions and exit
45
+
46
+ --server <id-or-name> server profile from ~/.happier/settings.json
47
+ --server-url <url> override the relay URL
48
+ --home <dir> Happier home (default ~/.happier, or $HAPPIER_HOME_DIR)
49
+ --no-bell notify without ringing the terminal bell
50
+ --no-notify no attention signal at all
51
+ ```
52
+
53
+ ### Start screen
54
+
55
+ Active sessions grouped by machine. Type to search by title, host, agent or path.
56
+
57
+ | Key | Action |
58
+ | --- | --- |
59
+ | `↑` `↓`, `enter` | select, open |
60
+ | `ctrl+n` | new session: machine → agent → directory |
61
+ | `tab` | show or hide inactive sessions |
62
+ | `esc` | clear the search, then go back to the open session |
63
+
64
+ ### In a session
65
+
66
+ | Key | Action |
67
+ | --- | --- |
68
+ | `enter` / `shift+enter` | send / newline |
69
+ | `esc` | interrupt the agent's current turn |
70
+ | `ctrl+s` | back to the start screen |
71
+ | `alt+↑` / `alt+↓` | previous / next active session |
72
+ | `ctrl+r` | answer a pending permission request or agent question |
73
+ | `ctrl+o` / `ctrl+t` | expand tool output / show or hide thinking |
74
+ | `pgup` / `pgdn`, mouse wheel | scroll; reaching the top loads earlier history |
75
+ | `ctrl+shift+f` | search the transcript |
76
+ | `ctrl+c` twice, `ctrl+d` | quit |
77
+
78
+ Slash commands: `/sessions`, `/new-session`, `/model`, `/mode`, `/abort`, `/stop-session`,
79
+ `/archive`, `/reload`, `/keys`, `/quit`. Anything else starting with `/` goes to the agent, whose
80
+ own commands are offered in autocomplete.
81
+
82
+ ## Knowing when an agent needs you
83
+
84
+ When a session you are not looking at finishes its turn, fails, or asks for a permission or an
85
+ answer, happier-tui signals it through the terminal:
86
+
87
+ - **Bell.** Works everywhere. tmux flags the window in its status line, cmux and most terminals
88
+ mark the tab.
89
+ - **Notification with text** (OSC 777): session name and what happened. Shown by cmux (pane ring,
90
+ sidebar badge, banner), Ghostty, WezTerm and others; ignored by terminals that do not know it.
91
+ Inside tmux this part needs `set -g allow-passthrough on`.
92
+
93
+ Nothing is raised for the session on screen while the terminal has focus.
94
+
95
+ **Phone pushes.** While you are at the terminal (it has focus and you used it in the last three
96
+ minutes), happier-tui reports a focused computer to the relay, as the Happier desktop app does.
97
+ With **Settings → Notifications → "Mute phone while a computer is focused"** enabled in the Happier
98
+ app (off by default), pushes for finished turns and permission requests are skipped while you are
99
+ there and resume when you leave or quit. The mute is account-wide, not per session. The open
100
+ session is also marked read, so the unread badge clears on your other devices.
101
+
102
+ If a signal does not show up, run with `HAPPIER_TUI_DEBUG=/tmp/happier-tui.log`. The log records
103
+ focus changes and, for each turn or request change, whether a signal was sent.
104
+
105
+ ## How it works
106
+
107
+ ```
108
+ src/main.ts command line
109
+ src/app.ts application state, keys, layout
110
+ src/new-session.ts the new-session wizard
111
+ src/happier/config.ts server profile and credentials written by the Happier CLI
112
+ src/happier/crypto.ts content encryption (AES-256-GCM data keys, legacy secretbox)
113
+ src/happier/client.ts relay client: sessions, transcripts, prompts, RPC, realtime
114
+ src/happier/transcript.ts decrypted records → display items (Claude, ACP, Codex formats)
115
+ src/ui/ start screen, transcript view, picker, logo, notifications, theme
116
+ ```
117
+
118
+ - **Reading.** Sessions, transcripts and machines come over HTTP and are decrypted locally with
119
+ per-session keys, unwrapped with the account key from the CLI's credentials.
120
+ - **Live updates.** One Socket.IO connection carries new messages, session state and streamed text.
121
+ - **Prompts** go to the relay's pending queue; an inactive session is resumed by its machine.
122
+ - **Interrupting, answering permissions, browsing directories and starting sessions** are encrypted
123
+ calls relayed to the agent or to the machine's daemon.
124
+
125
+ The Happier protocol is not a published, versioned API. This client follows the Happier sources as
126
+ of CLI 0.2.20, so a relay or CLI upgrade may require changes here.
127
+
128
+ ## Limits
129
+
130
+ - Direct sessions (transcript kept on the machine, not the relay) are listed but show no transcript.
131
+ - Subagent transcripts, attachments and images are not displayed.
132
+ - `/model` lists the agent's models; per-model options such as reasoning effort are not exposed.
133
+
134
+ ## Development
135
+
136
+ ```bash
137
+ npm run dev # run from source
138
+ npm test # unit tests
139
+ npm run typecheck
140
+ ```
141
+
142
+ ## License
143
+
144
+ [MIT](LICENSE)