diff --git a/README.md b/README.md index 2f71aec8..f6e7ad97 100644 --- a/README.md +++ b/README.md @@ -744,6 +744,7 @@ A full-screen dashboard for your sessions, in the terminal. Same states as the w codeman tui # the dashboard codeman tui --list # numbered session list, then exit (scriptable) codeman tui 2 # attach straight to session 2 of that list +codeman tui api-docs # attach straight to the live session named api-docs ``` Sessions are grouped **NEEDS YOU → WORKING → IDLE → RECENT**, longest-waiting first. `↑↓`/`j`/`k` select, `1`-`9` and `[`/`]` switch between sessions, `Enter` attaches into the tmux pane (**`F1`** to come back). Inside a pane the bar across the top keeps the session strip visible and `Alt+1`-`Alt+9` switch without leaving. `y`/`n`/digit answer a pending permission dialog right from the list, `p` sends a one-line prompt, `n` starts a session and opens straight into it, `x` kills one (`y` confirms), `/` searches, `g` shows the away digest, `?` is help, `q` quits. Below 72 columns it drops the preview pane and becomes a single-column list, so it stays usable in Termius on a phone. With no server running it still starts in attach-only degraded mode. diff --git a/docs/tui.md b/docs/tui.md index 4a1f7581..571e0f15 100644 --- a/docs/tui.md +++ b/docs/tui.md @@ -7,7 +7,7 @@ tmux pane with one keystroke. It is **additional, not a replacement**: the web UI stays the primary surface and gets every feature first. The TUI exists for the terminal workflow (SSH, Termius, -a tmux window you keep open all day), and it is a _client_ of the running server, +a tmux window you keep open all day), and it is a *client* of the running server, so the two surfaces can never disagree about what a session is doing. It is also not a multiplexer: tmux still owns every pane, and attaching hands the terminal to tmux rather than proxying bytes. @@ -21,17 +21,17 @@ codeman tui 2 # attach straight to session 2 of that list codeman tui api-docs # attach straight to the live session named api-docs ``` -The fast paths are the scriptable ones. +The two fast paths are the scriptable ones. Neither sets up a screen, so both are as quick as the one API call they make, and `--list` prints plain text when piped, so it composes with `grep`/`awk`. What it needs: -| Needs | What you get | -| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Needs | What you get | +| --- | --- | | **Full features** | A running Codeman server (states, approvals, preview, prompts, search, digest). The TUI finds it the way `codeman attach` does: `CODEMAN_API_URL`, else loopback on `CODEMAN_PORT` for this `CODEMAN_INSTANCE`. The self-signed certificate an `--https` install generates is accepted, as it is everywhere else in the CLI. | -| **Server down** | It still starts, in **degraded mode**: sessions are enumerated straight from `tmux -L codeman` plus a read-only peek at `state.json`, and attach is the only verb. See [Troubleshooting](#troubleshooting). | -| **A terminal** | `codeman tui` refuses to run when stdin/stdout are not a TTY, and says to use `--list` instead. A cron job or a pipe therefore fails loudly rather than emitting escape codes into a log. | +| **Server down** | It still starts, in **degraded mode**: sessions are enumerated straight from `tmux -L codeman` plus a read-only peek at `state.json`, and attach is the only verb. See [Troubleshooting](#troubleshooting). | +| **A terminal** | `codeman tui` refuses to run when stdin/stdout are not a TTY, and says to use `--list` instead. A cron job or a pipe therefore fails loudly rather than emitting escape codes into a log. | ## What it looks like @@ -85,25 +85,26 @@ The same world through `--list`: The numbers are the same on both surfaces, so `codeman tui --list` then `codeman tui 4` is one thought. -A number moves as sessions change state; a name does not. `codeman tui ` attaches to the -live session whose name is exactly `` (case-sensitive, never a prefix, never the folder), so -the same line gets you back into the same session from any folder or a fresh SSH login. Digits -only always mean a list number. Session names are not unique in Codeman, so when two live -sessions share the name it refuses and prints their numbers instead of guessing; a name only a -RECENT row carries says the session has finished. Both refusals are printed before the terminal -check, so a script can tell them apart without a TTY. +A number moves as sessions change state; a name does not. `codeman tui ` +attaches to the live session whose name is exactly `` (case-sensitive, +never a prefix, never the folder), so the same line gets you back into the same +session from any folder or a fresh SSH login. Digits only always mean a list +number. Session names are not unique in Codeman, so when two live sessions share +the name it refuses and prints their numbers instead of guessing; a name only a +RECENT row carries says the session has finished. Both refusals are printed +before the terminal check, so a script can tell them apart without a TTY. ## The four groups Groups are always in this order, and a session is in exactly one of them: -| Group | Glyph | Means | Comes from | -| ------------- | ------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| **NEEDS YOU** | `⚠` | A permission or question dialog is blocking the agent | The approvals inbox (`permission_prompt` hooks, with the on-screen options parsed; for Codex, a dialog read off its screen) | -| | `✋` | Waiting for your next instruction, or errored | `idle_prompt`, or an errored session (equally something only a human clears) | -| **WORKING** | `✻` animating | A turn is running | The same working classification the web dashboard uses | -| **IDLE** | `○` | Live, but sitting there | | -| **RECENT** | `✔` | A past session from the unified list | History rows, no live pane | +| Group | Glyph | Means | Comes from | +| --- | --- | --- | --- | +| **NEEDS YOU** | `⚠` | A permission or question dialog is blocking the agent | The approvals inbox (`permission_prompt` hooks, with the on-screen options parsed; for Codex, a dialog read off its screen) | +| | `✋` | Waiting for your next instruction, or errored | `idle_prompt`, or an errored session (equally something only a human clears) | +| **WORKING** | `✻` animating | A turn is running | The same working classification the web dashboard uses | +| **IDLE** | `○` | Live, but sitting there | | +| **RECENT** | `✔` | A past session from the unified list | History rows, no live pane | Ordering inside a group is "the one that has waited longest, first": blocked sessions sort by how long the dialog has been up, working sessions by when their @@ -120,20 +121,20 @@ same item announced twice does not ring twice. ## Keymap -| Key | Does | -| ------------------ | ------------------------------------------------------------------------------------------------ | -| `↑` `↓` or `j` `k` | Move the cursor. PageUp/PageDown jump five rows. | -| `Enter` | Attach to the selected session (see [Attaching](#attaching)) | -| `1`-`9` | Jump to that row and attach. When a dialog is on screen, a digit answers it instead (see below). | -| `y` | Approve the selected session's dialog | -| `n` | Deny it, or **start a new session** when there is no dialog | -| `p` | Send one line to the selected session without attaching | -| `x` | Kill the selected session; `y` confirms, any other key cancels | -| `/` | Search sessions, events and files | -| `g` | Away digest: what happened while you were gone | -| `?` | Help overlay | -| `Esc` | Close whatever overlay is open | -| `q` or `Ctrl+C` | Quit, restoring the screen you started with | +| Key | Does | +| --- | --- | +| `↑` `↓` or `j` `k` | Move the cursor. PageUp/PageDown jump five rows. | +| `Enter` | Attach to the selected session (see [Attaching](#attaching)) | +| `1`-`9` | Jump to that row and attach. When a dialog is on screen, a digit answers it instead (see below). | +| `y` | Approve the selected session's dialog | +| `n` | Deny it, or **start a new session** when there is no dialog | +| `p` | Send one line to the selected session without attaching | +| `x` | Kill the selected session; `y` confirms, any other key cancels | +| `/` | Search sessions, events and files | +| `g` | Away digest: what happened while you were gone | +| `?` | Help overlay | +| `Esc` | Close whatever overlay is open | +| `q` or `Ctrl+C` | Quit, restoring the screen you started with | Inside the `p` composer and the `/` query: `←` `→` `Home` `End` `Delete` `Backspace` plus `Ctrl+A` / `Ctrl+E` / `Ctrl+U` / `Ctrl+W`, `Enter` to send or open, @@ -222,11 +223,11 @@ resume the conversation in a fresh one instead. Three cases: -| Where you are | What happens | -| ----------------------------------- | --------------------------------------------------------------------------------------- | -| Not in tmux | `tmux -L codeman attach-session` | -| Already in tmux on Codeman's socket | `switch-client`, so you do not nest | -| In tmux on a **different** socket | Refused, with an explanation: detach from that tmux first, then run `codeman tui` again | +| Where you are | What happens | +| --- | --- | +| Not in tmux | `tmux -L codeman attach-session` | +| Already in tmux on Codeman's socket | `switch-client`, so you do not nest | +| In tmux on a **different** socket | Refused, with an explanation: detach from that tmux first, then run `codeman tui` again | A direct-PTY session has no pane to attach to, and says so. @@ -266,7 +267,7 @@ server. Start the server (`codeman web -d`, or `systemctl --user start codeman-w and the banner clears on its own: the TUI keeps re-probing. **It found the wrong server, or none.** Discovery is instance-scoped. A beta -instance (`CODEMAN_INSTANCE=beta`) has its own data dir _and_ its own tmux socket, +instance (`CODEMAN_INSTANCE=beta`) has its own data dir *and* its own tmux socket, so its TUI sees only its own sessions. Set `CODEMAN_PORT` or `CODEMAN_API_URL` explicitly when you run more than one. diff --git a/docs/wiki/Remote-Access.md b/docs/wiki/Remote-Access.md index 49e577cb..8c42113a 100644 --- a/docs/wiki/Remote-Access.md +++ b/docs/wiki/Remote-Access.md @@ -255,6 +255,7 @@ works well in SSH clients like Termius or Blink: ```bash codeman tui # the dashboard codeman tui 2 # attach straight to session 2 +codeman tui api-docs # attach to the live session named api-docs codeman tui --list # numbered list, then exit ``` diff --git a/src/tui/tui-app.ts b/src/tui/tui-app.ts index f32f513f..6859ee18 100644 --- a/src/tui/tui-app.ts +++ b/src/tui/tui-app.ts @@ -1,6 +1,6 @@ /** * @fileoverview `codeman tui`: the full-screen dashboard plus the two - * non-interactive fast paths (`--list`, ``). + * non-interactive fast paths (`--list`, ``). * * This is the IO half of `src/tui/`: it owns the terminal, the timers, stdin * and the tmux handoff. Every decision it makes that can be stated as a