happier-tui 0.1.0 → 0.2.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/README.md CHANGED
@@ -6,7 +6,7 @@ Pick a session running on any of your machines, read it live, send prompts, answ
6
6
  requests, start new sessions — and get a bell or a notification from your terminal, tmux or cmux
7
7
  when an agent needs you.
8
8
 
9
- ![happier-tui start screen](assets/main.png)
9
+ ![happier-tui start screen](https://raw.githubusercontent.com/CyrilPeponnet/happier-tui/main/assets/main.png)
10
10
 
11
11
  happier-tui is an independent, unofficial client. It talks to the Happier relay directly (HTTP and
12
12
  Socket.IO, end-to-end encrypted) and is built on
@@ -25,24 +25,34 @@ You need two things on the machine first:
25
25
  Then:
26
26
 
27
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
28
+ npm install -g happier-tui
32
29
  ```
33
30
 
34
- Run `happier-tui`. To update later: `git pull && npm install` in the same folder. To remove it:
31
+ Run `happier-tui`. To update: run the same command again. To remove it:
35
32
  `npm uninstall -g happier-tui`.
36
33
 
37
- Prefer not to install a command? Skip the last step and run `node dist/main.js` from the folder.
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
40
+ npm run build
41
+ npm install -g . # links the `happier-tui` command to this folder
42
+ ```
43
+
44
+ To update: `git pull && npm install && npm run build` in the same folder. Without installing a command, run
45
+ `node dist/main.js` from the folder.
38
46
 
39
47
  ## Use
40
48
 
41
49
  ```
42
50
  happier-tui start screen: pick or start a session
43
51
  happier-tui <session-id-or-prefix> open a session directly
52
+ happier-tui <directory> start a new session on this machine in that directory
44
53
  happier-tui --list [--all] print active (or all) sessions and exit
45
54
 
55
+ --agent <name> agent for the new session (claude, codex, pi, …); asked for otherwise
46
56
  --server <id-or-name> server profile from ~/.happier/settings.json
47
57
  --server-url <url> override the relay URL
48
58
  --home <dir> Happier home (default ~/.happier, or $HAPPIER_HOME_DIR)
@@ -70,14 +80,33 @@ Active sessions grouped by machine. Type to search by title, host, agent or path
70
80
  | `ctrl+s` | back to the start screen |
71
81
  | `alt+↑` / `alt+↓` | previous / next active session |
72
82
  | `ctrl+r` | answer a pending permission request or agent question |
73
- | `ctrl+o` / `ctrl+t` | expand tool output / show or hide thinking |
83
+ | `ctrl+o` / `ctrl+t` | expand tool calls and their output / show or hide thinking |
74
84
  | `pgup` / `pgdn`, mouse wheel | scroll; reaching the top loads earlier history |
75
85
  | `ctrl+shift+f` | search the transcript |
76
86
  | `ctrl+c` twice, `ctrl+d` | quit |
77
87
 
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.
88
+ Type `@` to mention a file: completion lists the files of the session's folder on its machine
89
+ (through the daemon's ripgrep, so `.gitignore` applies).
90
+
91
+ | Command | |
92
+ | --- | --- |
93
+ | `/model`, `/effort` | change the model, and its thinking level when it has one |
94
+ | `/mode` | the agent's own modes (when it reports any) and the permission mode |
95
+ | `/queue` | edit or cancel messages still waiting to be sent |
96
+ | `/tree` | branch into a new session from an earlier message, which is put back in the editor to rewrite (Codex sessions can also roll back in place) |
97
+ | `/goal [text\|clear]` | show, set or clear the session's goal (Claude, Codex) |
98
+ | `/limit` | after a usage limit: resume automatically when it resets, or check now |
99
+ | `/rename` | rename the session |
100
+ | `/sessions`, `/new-session`, `/abort`, `/stop-session`, `/archive`, `/reload`, `/keys`, `/quit` | |
101
+
102
+ Anything else starting with `/` goes to the agent, whose own commands are offered in
103
+ autocomplete. Model, mode and thinking-level changes apply from your next message.
104
+
105
+ Above the editor, the TUI shows what needs you or is pending: permission requests and questions,
106
+ messages waiting in the queue, the session's goal and a usage-limit wait. Once a turn is over, its tool calls
107
+ fold into one line and the turn ends with how long it took; a subagent's work shows as one line
108
+ under the tool call that started it. Click a folded line to unfold it, or a tool to see all its
109
+ output; `ctrl+o` unfolds everything.
81
110
 
82
111
  ## Knowing when an agent needs you
83
112
 
@@ -111,16 +140,20 @@ src/new-session.ts the new-session wizard
111
140
  src/happier/config.ts server profile and credentials written by the Happier CLI
112
141
  src/happier/crypto.ts content encryption (AES-256-GCM data keys, legacy secretbox)
113
142
  src/happier/client.ts relay client: sessions, transcripts, prompts, RPC, realtime
143
+ src/happier/controls.ts modes, thinking level, goal and usage limit, as kept in session metadata
114
144
  src/happier/transcript.ts decrypted records → display items (Claude, ACP, Codex formats)
115
- src/ui/ start screen, transcript view, picker, logo, notifications, theme
145
+ src/ui/ start screen, transcript view, picker, @ completion, logo, notifications, theme
116
146
  ```
117
147
 
118
148
  - **Reading.** Sessions, transcripts and machines come over HTTP and are decrypted locally with
119
149
  per-session keys, unwrapped with the account key from the CLI's credentials.
120
150
  - **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.
151
+ - **Prompts** go to the relay's pending queue, where they can still be edited or cancelled until
152
+ the agent takes them; an inactive session is resumed by its machine.
153
+ - **Model, mode, thinking level and title** are written to the session's encrypted metadata, which
154
+ the agent reads, as the Happier app does.
155
+ - **Interrupting, answering permissions, listing files, branching, goals, usage limits and starting
156
+ sessions** are encrypted calls relayed to the agent or to the machine's daemon.
124
157
 
125
158
  The Happier protocol is not a published, versioned API. This client follows the Happier sources as
126
159
  of CLI 0.2.20, so a relay or CLI upgrade may require changes here.
@@ -128,8 +161,10 @@ of CLI 0.2.20, so a relay or CLI upgrade may require changes here.
128
161
  ## Limits
129
162
 
130
163
  - 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.
164
+ - Images and attachments are neither shown nor sent.
165
+ - Of the per-model options, only the thinking level is offered.
166
+ - Out of scope, as the Happier app covers them: git, terminals, file browsing, moving sessions
167
+ between machines.
133
168
 
134
169
  ## Development
135
170