docs: point terminal users at codeman tui instead of the sc chooser

codeman tui supersedes the sc bash chooser: it reaches sessions 10+, carries the server's real states instead of a static list, and leaves an attach with one key. Every place that told a user to run sc now names the tui equivalent, including the two wiki pages and install.sh's next-steps banner. Both wiki pages also carried the wrong detach chord (Ctrl+A D; the socket's prefix is C-b), which the tui makes moot. Source comments that explained themselves as "the sc -l replacement" now just say what they do. docs/tui-plan.md and CHANGELOG.md are historical records and keep their references.
2026-09-30 12:39:42 +02:00 · 2026-08-22 14:36:23 +02:00
parent f49249fb2f
commit 5d81cc01ca
12 changed files with 32 additions and 54 deletions
@@ -87,7 +87,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph

 **Requirements**: Node.js 22+, Claude CLI, tmux

-**Git**: Main branch is `master`. SSH session chooser: `sc` (interactive), `sc 2` (quick attach), `sc -l` (list).
+**Git**: Main branch is `master`. Terminal session dashboard: `codeman tui` (`--list` to list, `codeman tui <n>` to attach).

 ## Additional Commands

@@ -285,7 +285,7 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows

 - **Phone/tablet** — the UI is fully touch-optimized; scan the desktop **QR code** to log in without typing a password.
 - **Outside your network** — `./scripts/tunnel.sh start` opens a Cloudflare tunnel (set `CODEMAN_PASSWORD` first).
- **SSH** — the `sc` chooser attaches to any session from a terminal (`sc` interactive, `sc 2` quick-attach, `sc -l` list).
+- **SSH** — `codeman tui` is a full-screen dashboard in the terminal (`codeman tui --list` to list, `codeman tui 2` to attach straight to one).

 ### 7. Operate & maintain

@@ -674,20 +674,6 @@ The web UI remains the primary surface; see **[docs/tui.md](docs/tui.md)** for t

 ---

-## SSH Alternative (`sc`)
-
-If you prefer SSH (Termius, Blink, etc.), the `sc` command is a thumb-friendly session chooser:
-
-```bash
-sc              # Interactive chooser
-sc 2            # Quick attach to session 2
-sc -l           # List sessions
-```
-
-Single-digit selection (1-9), color-coded status, token counts, auto-refresh. `sc` hands you to a plain `tmux attach`, so you leave the pane with tmux's own detach chord: `Ctrl+B`, release, then `d`. (`codeman tui` is the one that gives you a single `F1` instead, because its attach claims that key for the duration.)
-
---
-
 ## Keyboard Shortcuts

 > Ctrl bindings also accept Cmd on macOS.
@@ -253,7 +253,7 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_

 - **手机/平板** —— UI 完全触控优化；扫描桌面上的**二维码**即可免密码登录。
 - **网络之外** —— `./scripts/tunnel.sh start` 打开一条 Cloudflare 隧道（先设置 `CODEMAN_PASSWORD`）。
- **SSH** —— `sc` 选择器可从终端附着任意会话（`sc` 交互式，`sc 2` 快速附着，`sc -l` 列表）。
+- **SSH** —— `codeman tui` 是终端里的全屏会话面板（`codeman tui --list` 列出，`codeman tui 2` 直接附着到某个会话）。

 ### 7. 运维与维护

@@ -615,20 +615,6 @@ Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI

 ---

-## SSH 替代方案（`sc`）
-
-如果你更喜欢 SSH（Termius、Blink 等），`sc` 命令是一个便于拇指操作的会话选择器：
-
-```bash
-sc              # 交互式选择器
-sc 2            # 快速附着到会话 2
-sc -l           # 列出会话
-```
-
-单数字选择（1–9）、颜色编码的状态、token 计数、自动刷新。用 `Ctrl+A D` 分离。
-
---
-
 ## 键盘快捷键

 > Ctrl 绑定在 macOS 上也接受 Cmd。
@@ -139,7 +139,7 @@ set -g extended-keys-format csi-u

 Codeman's browser input path sends `\r` for submit, so basic use works
 unconfigured — what degrades is newline-in-editor, mostly when you attach to the
-pane directly (`sc`).
+pane directly (`codeman tui`).

 ⚠️ Upstream notes the setting may need a full `tmux kill-server` to take effect.
 **Never run `tmux kill-server` on Codeman's socket** — it would kill every live
@@ -20,7 +20,7 @@ codeman tui --list       # print the numbered session list and exit
 codeman tui 2            # attach straight to session 2 of that list
 ```

-The two fast paths are the scriptable ones (they are the `sc -l` / `sc 2` shapes).
+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`.

@@ -228,8 +228,8 @@ The TUI is an ordinary terminal program with no local dependencies beyond tmux,
 separate remote mode.

 Below 72 columns (Termius, an iPhone in portrait) the preview pane is dropped and
-rows take two lines each: the same constraint the `sc` chooser was built around,
-now with a cursor, live states and the answer/prompt/kill verbs. The switch is
+rows take two lines each, keeping the cursor, the live states and the
+answer/prompt/kill verbs. The switch is
 width-driven at draw time, so unfolding a foldable or resizing a window re-lays out
 immediately; there is no mode flag to set.

@@ -88,7 +88,7 @@ would. That indirection buys:
 - **Real scrollback.** History is held by tmux, so reconnecting replays what happened while
  you were gone instead of starting from blank.
 - **Attach from anywhere else.** The same session is reachable from a terminal over SSH
-  with the `sc` chooser, or plain `tmux -L codeman attach`.
+  with `codeman tui`, or plain `tmux -L codeman attach`.
 - **Secrets off the command line.** Environment overrides are injected with socket-scoped
  `tmux setenv` rather than being visible in the spawn command.

@@ -73,8 +73,10 @@ features are Claude-only; [Agent CLIs](Agent-CLIs) lists exactly which.

 ### Can I attach to a session from a terminal instead of the browser?

-Yes. `sc` is an interactive chooser (`sc 2` attaches directly, `sc -l` lists), or use tmux
-directly on the `codeman` socket. Detach with `Ctrl+A D`.
+Yes. `codeman tui` is a full-screen dashboard of your sessions, with the same
+NEEDS YOU / WORKING / IDLE grouping the web UI uses. `codeman tui --list` prints the
+numbered list and exits, and `codeman tui 2` attaches straight to session 2. `Enter`
+attaches, `F1` comes back. You can also use tmux directly on the `codeman` socket.

 ## Running unattended

@@ -179,16 +179,19 @@ the same IP, which matters because all tunnel traffic arrives from one loopback

 ## Terminal alternatives

-You do not have to use a browser. `sc` is a thumb-friendly session chooser for SSH clients
-like Termius or Blink:
+You do not have to use a browser. `codeman tui` is a full-screen session dashboard that
+works well in SSH clients like Termius or Blink:

 ```bash
-sc          # interactive chooser
-sc 2        # attach to session 2
-sc -l       # list
+codeman tui           # the dashboard
+codeman tui 2         # attach straight to session 2
+codeman tui --list    # numbered list, then exit
 ```

-Detach with `Ctrl+A D`. The sessions are the same ones the dashboard shows.
+`Enter` attaches into the pane and `F1` comes back. Under 72 columns it drops the preview
+and becomes a single-column list, so it stays usable on a phone. The sessions are the same
+ones the dashboard shows. See [docs/tui.md](https://github.com/Ark0N/Codeman/blob/master/docs/tui.md)
+for the full guide.

 ## Common problems

@@ -2450,9 +2450,9 @@ main() {

    echo -e "  ${BOLD}Mobile Access (Termius/SSH):${NC}"
    echo ""
-    echo -e "    ${CYAN}sc${NC}              # Interactive tmux session chooser"
-    echo -e "    ${CYAN}sc 2${NC}            # Quick attach to session 2"
-    echo -e "    ${CYAN}sc -h${NC}           # Help"
+    echo -e "    ${CYAN}codeman tui${NC}     # Full-screen session dashboard"
+    echo -e "    ${CYAN}codeman tui 2${NC}   # Attach straight to session 2"
+    echo -e "    ${CYAN}codeman tui -l${NC}  # Numbered list, then exit"
    echo ""

    echo -e "  ${BOLD}Documentation:${NC}"
@@ -2600,8 +2600,9 @@ export async function runTui(options: TuiRunOptions = {}): Promise<number> {
 }

 /**
- * `codeman tui --list`: the `sc -l` replacement. Prints and exits, colored when
- * the output is a terminal and plain when it is piped (chalk's call, not ours).
+ * `codeman tui --list`: prints and exits, colored when the output is a terminal
+ * and plain when it is piped (chalk's call, not ours), so it composes with
+ * grep/awk.
 */
 export async function runTuiList(options: TuiRunOptions = {}): Promise<number> {
  const stdout = options.stdout ?? process.stdout;
@@ -2638,8 +2639,8 @@ export async function runTuiList(options: TuiRunOptions = {}): Promise<number> {
 }

 /**
- * `codeman tui <n>`: the `sc 2` replacement. No screen setup at all, so it is
- * as fast as the API call it makes.
+ * `codeman tui <n>`: attach straight to the nth row of `--list`. No screen setup
+ * at all, so it is as fast as the API call it makes.
 */
 export async function runTuiAttach(position: number, options: TuiRunOptions = {}): Promise<number> {
  const stdin = options.stdin ?? process.stdin;
@@ -213,8 +213,8 @@ export function glyphsFor(tier: TuiGlyphTier): TuiGlyphSet {
 /**
 * Glyph tier from the environment. IO-ish by nature (it reads env), so it takes
 * the env as an argument and the app layer calls it once at startup. The
- * known-capable list is the same gate `scripts/tmux-chooser.sh` uses, plus a
- * UTF-8 locale check and an explicit override.
+ * known-capable list is a TERM allowlist, plus a UTF-8 locale check and an
+ * explicit override.
 */
 export function detectGlyphTier(env: Record<string, string | undefined>): TuiGlyphTier {
  const override = env.CODEMAN_TUI_GLYPHS;
@@ -138,7 +138,7 @@ describe('registered options', () => {
    expect(flagsOf(find(program, 'doctor')!)).toEqual(expect.arrayContaining(['--json', '--category']));
  });

-  it('keeps the two `tui` fast paths, which stand in for `sc -l` and `sc 2`', () => {
+  it('keeps the two `tui` fast paths that scripts call', () => {
    expect(flagsOf(find(program, 'tui')!)).toEqual(expect.arrayContaining(['-l', '--list']));
  });