happier-tui 0.0.0-stage → 0.1.1
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 +21 -0
- package/README.md +150 -2
- package/dist/app.js +937 -0
- package/dist/app.js.map +1 -0
- package/dist/happier/client.js +757 -0
- package/dist/happier/client.js.map +1 -0
- package/dist/happier/config.js +69 -0
- package/dist/happier/config.js.map +1 -0
- package/dist/happier/crypto.js +111 -0
- package/dist/happier/crypto.js.map +1 -0
- package/dist/happier/transcript.js +421 -0
- package/dist/happier/transcript.js.map +1 -0
- package/dist/main.js +85 -0
- package/dist/main.js.map +1 -0
- package/dist/new-session.js +156 -0
- package/dist/new-session.js.map +1 -0
- package/dist/ui/format.js +56 -0
- package/dist/ui/format.js.map +1 -0
- package/dist/ui/home.js +238 -0
- package/dist/ui/home.js.map +1 -0
- package/dist/ui/logo.js +60 -0
- package/dist/ui/logo.js.map +1 -0
- package/dist/ui/notify.js +49 -0
- package/dist/ui/notify.js.map +1 -0
- package/dist/ui/picker.js +81 -0
- package/dist/ui/picker.js.map +1 -0
- package/dist/ui/theme.js +79 -0
- package/dist/ui/theme.js.map +1 -0
- package/dist/ui/transcript-view.js +178 -0
- package/dist/ui/transcript-view.js.map +1 -0
- package/package.json +51 -4
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,151 @@
|
|
|
1
|
-
#
|
|
1
|
+
# happier-tui
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+

|
|
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
|
+
npm install -g happier-tui
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Run `happier-tui`. To update: run the same command again. To remove it:
|
|
32
|
+
`npm uninstall -g happier-tui`.
|
|
33
|
+
|
|
34
|
+
### From source
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
git clone https://github.com/CyrilPeponnet/happier-tui.git
|
|
38
|
+
cd happier-tui
|
|
39
|
+
npm install # downloads dependencies and builds
|
|
40
|
+
npm install -g . # adds the `happier-tui` command
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
To update: `git pull && npm install` in the same folder. Without installing a command, run
|
|
44
|
+
`node dist/main.js` from the folder.
|
|
45
|
+
|
|
46
|
+
## Use
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
happier-tui start screen: pick or start a session
|
|
50
|
+
happier-tui <session-id-or-prefix> open a session directly
|
|
51
|
+
happier-tui --list [--all] print active (or all) sessions and exit
|
|
52
|
+
|
|
53
|
+
--server <id-or-name> server profile from ~/.happier/settings.json
|
|
54
|
+
--server-url <url> override the relay URL
|
|
55
|
+
--home <dir> Happier home (default ~/.happier, or $HAPPIER_HOME_DIR)
|
|
56
|
+
--no-bell notify without ringing the terminal bell
|
|
57
|
+
--no-notify no attention signal at all
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Start screen
|
|
61
|
+
|
|
62
|
+
Active sessions grouped by machine. Type to search by title, host, agent or path.
|
|
63
|
+
|
|
64
|
+
| Key | Action |
|
|
65
|
+
| --- | --- |
|
|
66
|
+
| `↑` `↓`, `enter` | select, open |
|
|
67
|
+
| `ctrl+n` | new session: machine → agent → directory |
|
|
68
|
+
| `tab` | show or hide inactive sessions |
|
|
69
|
+
| `esc` | clear the search, then go back to the open session |
|
|
70
|
+
|
|
71
|
+
### In a session
|
|
72
|
+
|
|
73
|
+
| Key | Action |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `enter` / `shift+enter` | send / newline |
|
|
76
|
+
| `esc` | interrupt the agent's current turn |
|
|
77
|
+
| `ctrl+s` | back to the start screen |
|
|
78
|
+
| `alt+↑` / `alt+↓` | previous / next active session |
|
|
79
|
+
| `ctrl+r` | answer a pending permission request or agent question |
|
|
80
|
+
| `ctrl+o` / `ctrl+t` | expand tool output / show or hide thinking |
|
|
81
|
+
| `pgup` / `pgdn`, mouse wheel | scroll; reaching the top loads earlier history |
|
|
82
|
+
| `ctrl+shift+f` | search the transcript |
|
|
83
|
+
| `ctrl+c` twice, `ctrl+d` | quit |
|
|
84
|
+
|
|
85
|
+
Slash commands: `/sessions`, `/new-session`, `/model`, `/mode`, `/abort`, `/stop-session`,
|
|
86
|
+
`/archive`, `/reload`, `/keys`, `/quit`. Anything else starting with `/` goes to the agent, whose
|
|
87
|
+
own commands are offered in autocomplete.
|
|
88
|
+
|
|
89
|
+
## Knowing when an agent needs you
|
|
90
|
+
|
|
91
|
+
When a session you are not looking at finishes its turn, fails, or asks for a permission or an
|
|
92
|
+
answer, happier-tui signals it through the terminal:
|
|
93
|
+
|
|
94
|
+
- **Bell.** Works everywhere. tmux flags the window in its status line, cmux and most terminals
|
|
95
|
+
mark the tab.
|
|
96
|
+
- **Notification with text** (OSC 777): session name and what happened. Shown by cmux (pane ring,
|
|
97
|
+
sidebar badge, banner), Ghostty, WezTerm and others; ignored by terminals that do not know it.
|
|
98
|
+
Inside tmux this part needs `set -g allow-passthrough on`.
|
|
99
|
+
|
|
100
|
+
Nothing is raised for the session on screen while the terminal has focus.
|
|
101
|
+
|
|
102
|
+
**Phone pushes.** While you are at the terminal (it has focus and you used it in the last three
|
|
103
|
+
minutes), happier-tui reports a focused computer to the relay, as the Happier desktop app does.
|
|
104
|
+
With **Settings → Notifications → "Mute phone while a computer is focused"** enabled in the Happier
|
|
105
|
+
app (off by default), pushes for finished turns and permission requests are skipped while you are
|
|
106
|
+
there and resume when you leave or quit. The mute is account-wide, not per session. The open
|
|
107
|
+
session is also marked read, so the unread badge clears on your other devices.
|
|
108
|
+
|
|
109
|
+
If a signal does not show up, run with `HAPPIER_TUI_DEBUG=/tmp/happier-tui.log`. The log records
|
|
110
|
+
focus changes and, for each turn or request change, whether a signal was sent.
|
|
111
|
+
|
|
112
|
+
## How it works
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
src/main.ts command line
|
|
116
|
+
src/app.ts application state, keys, layout
|
|
117
|
+
src/new-session.ts the new-session wizard
|
|
118
|
+
src/happier/config.ts server profile and credentials written by the Happier CLI
|
|
119
|
+
src/happier/crypto.ts content encryption (AES-256-GCM data keys, legacy secretbox)
|
|
120
|
+
src/happier/client.ts relay client: sessions, transcripts, prompts, RPC, realtime
|
|
121
|
+
src/happier/transcript.ts decrypted records → display items (Claude, ACP, Codex formats)
|
|
122
|
+
src/ui/ start screen, transcript view, picker, logo, notifications, theme
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
- **Reading.** Sessions, transcripts and machines come over HTTP and are decrypted locally with
|
|
126
|
+
per-session keys, unwrapped with the account key from the CLI's credentials.
|
|
127
|
+
- **Live updates.** One Socket.IO connection carries new messages, session state and streamed text.
|
|
128
|
+
- **Prompts** go to the relay's pending queue; an inactive session is resumed by its machine.
|
|
129
|
+
- **Interrupting, answering permissions, browsing directories and starting sessions** are encrypted
|
|
130
|
+
calls relayed to the agent or to the machine's daemon.
|
|
131
|
+
|
|
132
|
+
The Happier protocol is not a published, versioned API. This client follows the Happier sources as
|
|
133
|
+
of CLI 0.2.20, so a relay or CLI upgrade may require changes here.
|
|
134
|
+
|
|
135
|
+
## Limits
|
|
136
|
+
|
|
137
|
+
- Direct sessions (transcript kept on the machine, not the relay) are listed but show no transcript.
|
|
138
|
+
- Subagent transcripts, attachments and images are not displayed.
|
|
139
|
+
- `/model` lists the agent's models; per-model options such as reasoning effort are not exposed.
|
|
140
|
+
|
|
141
|
+
## Development
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
npm run dev # run from source
|
|
145
|
+
npm test # unit tests
|
|
146
|
+
npm run typecheck
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## License
|
|
150
|
+
|
|
151
|
+
[MIT](LICENSE)
|