From 5d81cc01cadcf388776eb0a5791809f2521fd5b4 Mon Sep 17 00:00:00 2001 From: Codeman maintainer Date: Sat, 22 Aug 2026 14:36:23 +0200 Subject: [PATCH] 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. --- CLAUDE.md | 2 +- README.md | 16 +--------------- README.zh-CN.md | 16 +--------------- docs/pi-integration.md | 2 +- docs/tui.md | 6 +++--- docs/wiki/Core-Concepts.md | 2 +- docs/wiki/FAQ.md | 6 ++++-- docs/wiki/Remote-Access.md | 15 +++++++++------ install.sh | 6 +++--- src/tui/tui-app.ts | 9 +++++---- src/tui/tui-render.ts | 4 ++-- test/cli-commands.test.ts | 2 +- 12 files changed, 32 insertions(+), 54 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index fc16be1d..871b9874 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 ` to attach). ## Additional Commands diff --git a/README.md b/README.md index 081b9fb4..00947459 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/README.zh-CN.md b/README.zh-CN.md index 051db98a..6cca19dc 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -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。 diff --git a/docs/pi-integration.md b/docs/pi-integration.md index 3bc95a88..3d66e32c 100644 --- a/docs/pi-integration.md +++ b/docs/pi-integration.md @@ -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 diff --git a/docs/tui.md b/docs/tui.md index 1f2a1080..145de274 100644 --- a/docs/tui.md +++ b/docs/tui.md @@ -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. diff --git a/docs/wiki/Core-Concepts.md b/docs/wiki/Core-Concepts.md index 062d00c5..5110e5ef 100644 --- a/docs/wiki/Core-Concepts.md +++ b/docs/wiki/Core-Concepts.md @@ -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. diff --git a/docs/wiki/FAQ.md b/docs/wiki/FAQ.md index 66708101..bdbdf26b 100644 --- a/docs/wiki/FAQ.md +++ b/docs/wiki/FAQ.md @@ -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 diff --git a/docs/wiki/Remote-Access.md b/docs/wiki/Remote-Access.md index b3b00bb3..e7e810c1 100644 --- a/docs/wiki/Remote-Access.md +++ b/docs/wiki/Remote-Access.md @@ -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 diff --git a/install.sh b/install.sh index 6ff0abb7..c30a598a 100755 --- a/install.sh +++ b/install.sh @@ -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}" diff --git a/src/tui/tui-app.ts b/src/tui/tui-app.ts index d263d764..a7a96c69 100644 --- a/src/tui/tui-app.ts +++ b/src/tui/tui-app.ts @@ -2600,8 +2600,9 @@ export async function runTui(options: TuiRunOptions = {}): Promise { } /** - * `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 { const stdout = options.stdout ?? process.stdout; @@ -2638,8 +2639,8 @@ export async function runTuiList(options: TuiRunOptions = {}): Promise { } /** - * `codeman tui `: the `sc 2` replacement. No screen setup at all, so it is - * as fast as the API call it makes. + * `codeman tui `: 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 { const stdin = options.stdin ?? process.stdin; diff --git a/src/tui/tui-render.ts b/src/tui/tui-render.ts index edb4897b..8033104c 100644 --- a/src/tui/tui-render.ts +++ b/src/tui/tui-render.ts @@ -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): TuiGlyphTier { const override = env.CODEMAN_TUI_GLYPHS; diff --git a/test/cli-commands.test.ts b/test/cli-commands.test.ts index 9946a961..6298f451 100644 --- a/test/cli-commands.test.ts +++ b/test/cli-commands.test.ts @@ -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'])); });