heyterm 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,10 @@
 <p align="center"><img src="assets/logo-mark.svg" width="96" height="96" alt="HeyTerm"></p>
 
+<p align="center"><a href="https://heyterm.vercel.app">Website</a> · <a href="https://heyterm.vercel.app/playground/">Playground</a> · <a href="https://www.npmjs.com/package/heyterm">npm</a> · <a href="LICENSE">MIT</a> · <a href="SECURITY.md">Security</a></p>
+
 # HeyTerm
 
-Run your coding agents by voice. HeyTerm is one window for all your Claude Code, Codex and Gemini CLI sessions, with an assistant in the middle: you talk through Wispr Flow (or any dictation tool), it works out which session you mean and does it, and it tells you when a session needs you. Five agents at once, no keyboard, no trackpad.
+Run your coding agents by voice. HeyTerm is one window for all your Claude Code, Codex, Gemini CLI, Grok Build and Cursor sessions, with an assistant in the middle: you talk through Wispr Flow (or any dictation tool), it works out which session you mean and does it, and it tells you when a session needs you. Five agents at once, no keyboard, no trackpad.
 
 ## Why
 
@@ -29,16 +31,26 @@ Those happen at once on your computer. Everything else goes to the assistant in
 
 HeyTerm speaks with your Mac's own voice (whatever is set in System Settings, Accessibility, Spoken Content; Siri voices work there), or the browser's voice if you pick it in Setup.
 
+## What you see
+
+- **Sessions on the left**, each with its own face and its state, waits counted while it needs you. The sidebar folds to a rail of faces that are named when you hover.
+- **Terminals in the middle**, in a grid or one at a time.
+- **The conversation on the right.** When a session needs you, its request arrives as a message there, with buttons and the words to say. Answer by voice or click; your answer shows up as your own message under it. Fold the column away and the most urgent request sits in one slim row above the bar you talk into.
+- **Gruvbox, light or dark.** HeyTerm starts in Gruvbox Material light; Setup, Appearance switches to dark or follows your system. Terminals stay dark in both, because coding agents colour their text for a dark terminal.
+
 ## Getting started
 
-You need Node.js 20 or newer on macOS, Linux or Windows, and at least one coding agent signed in once: [Claude Code](https://code.claude.com), [Codex](https://github.com/openai/codex) (`npm install -g @openai/codex`) or [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`npm install -g @google/gemini-cli`). The assistant in the middle runs on Claude Code.
+To see it without installing anything, open the [playground](https://heyterm.vercel.app/playground/): the same interface on three simulated agents.
+
+
+You need Node.js 20 or newer on macOS, Linux or Windows, and at least one coding agent signed in once: [Claude Code](https://code.claude.com), [Codex](https://github.com/openai/codex) (`npm install -g @openai/codex`), [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`npm install -g @google/gemini-cli`), Grok Build (`curl -fsSL https://x.ai/cli/install.sh | bash`, then `grok login`) or Cursor (`curl https://cursor.com/install -fsS | bash`, then `cursor-agent login`). The assistant in the middle runs on Claude Code.
 
 ```bash
 npx heyterm doctor    # checks Node and which agents are installed
 npx heyterm           # starts HeyTerm and opens it in your browser
 ```
 
-Until the package is on npm, run it from source instead:
+To run it from source instead:
 
 ```bash
 git clone https://github.com/adilhusain01/heyterm && cd heyterm
@@ -50,10 +62,10 @@ Then:
 
 1. Click anywhere on the page once, so the browser lets HeyTerm speak.
 2. Open Setup and check your project folders. HeyTerm looks in `~/Documents/Projects`, `~/Projects`, `~/code`, `~/dev`, `~/src` and `~/Developer` by default, and the assistant can start a session in any folder you name.
-3. Hold your dictation key (Fn for Wispr Flow) and say "start a session in" followed by a project name. Say "start a codex session in…" or "open gemini in…" for the other agents.
+3. Hold your dictation key (Fn for Wispr Flow) and say "start a session in" followed by a project name. Say "start a codex session in…", "open gemini in…", "start a grok session in…" or "open cursor in…" for the other agents.
 4. Use headphones, so HeyTerm's spoken alerts never end up in your own dictation.
 
-To see the Claude sessions you start in your own terminals as well, open Setup and turn on **Show my own sessions**. While HeyTerm runs, its hooks sit in `~/.claude/settings.json` (backed up first in `~/.heyterm/backups`); they come out when HeyTerm stops. It can answer those sessions' permissions and questions and tell you when they finish, but it can only type into sessions it started.
+To see the Claude sessions you start in your own terminals as well, open Setup and press **Show them** under Your own Claude sessions. While HeyTerm runs, its hooks sit in `~/.claude/settings.json` (backed up first in `~/.heyterm/backups`); they come out when HeyTerm stops. It can answer those sessions' permissions and questions and tell you when they finish, but it can only type into sessions it started.
 
 ## Starting, stopping and removing it
 
@@ -69,6 +81,7 @@ Closing the page stops HeyTerm after 15 seconds, so a reload never does. Setup h
 
 - **Sessions run in HeyTerm's own terminals** (pseudo-terminals it owns, the same on macOS, Linux and Windows), with a copy of each screen so the assistant can read it and a page opened later sees it.
 - **Agent hooks report every state**, so nothing is guessed from the screen. Claude Code gets them through a settings file for its session; Codex through config overrides for that run (Codex asks once to trust them; say "trust it"). Your own `~/.codex` and Claude settings are not changed.
+- **Grok Build and Cursor read hooks only from global files**, so while HeyTerm runs it writes `~/.grok/hooks/heyterm.json` and adds its entries to `~/.cursor/hooks.json` (backed up first), and takes them out again when it stops or is uninstalled. They only report what happens; nothing in them can approve or block a tool, so each agent's own permission rules stay in charge, and sessions HeyTerm did not start are ignored. Grok's permission card shows as waiting in its terminal: say "go to" the session and answer there.
 - **A permission or a multiple-choice question is held open until you answer by voice**; answering in the terminal by hand still works, and wins.
 - **No extra gates**: HeyTerm adds no permission layer of its own. What an agent's permission mode allows, it runs; when the agent asks, you hear what it wants and its risk, and "approve" answers.
 - **Text is sent as a real prompt**, pasted into the session and confirmed by its prompt hook.
@@ -100,8 +113,13 @@ npm test           # the unit tests; CI also runs them on macOS, Linux and Windo
 npm run typecheck
 npm run build      # dist/web and dist/server/cli.js
 npm run build:playground   # dist/playground: the same UI on three simulated agents, a static site anyone can open
+npm run dev:site           # the landing page (site/) with reload on :5174
+npm run build:site         # dist/site: the landing page, with the playground under /playground/
+npm run deploy:site        # builds both and deploys them to Vercel as one site
 ```
 
+The landing page lives in `site/`. It shares the app's tokens (`src/web/tokens.css`) and motion (`src/web/motion.css`), so the two never drift apart, and its hero is a small HeyTerm running a scene. The faces it shows are drawn at build time by `scripts/site-faces.mjs`, so the page ships pictures instead of the face generator.
+
 `docs/SPEC.md` is the behaviour HeyTerm promises, and the tests are written from it. `scripts/smoke.mjs` checks an installed package end to end (start, the token wall, stop, uninstall). Pure decisions (routing, risk, session states, the attention queue) live in their own files with tests beside them.
 
 Built for [No Hands: The Wispr Challenge](https://www.wemakedevs.org/wispr) by WeMakeDevs and Wispr Flow.