Skip to content

feat(tui): attach by session name, codeman tui <name> - #834

Open
kkalisz wants to merge 5 commits into
Ark0N:masterfrom
kkalisz:feat/tui-attach-by-name
Open

kkalisz wants to merge 5 commits into
Ark0N:masterfrom
kkalisz:feat/tui-attach-by-name

Conversation

@kkalisz

@kkalisz kkalisz commented Nov 18, 2026 •

Copy link
Copy Markdown

Part 1 of Discussion #833. Part 1 stands on its own; part 2 (--new) waits for your view there.

Problem

codeman tui <n> attaches by list number, but the number changes whenever sessions move between
NEEDS YOU / WORKING / IDLE, so you can't remember it, alias it or script it. From a fresh SSH
login there's no stable way to say "take me back to the docs session".

Change

codeman tui <session> takes a number or a session name.

  • Digits only is a list number, exactly as before (0 and out-of-range keep their messages).
  • Anything else is matched exactly (case-sensitive) against the session's name: never a prefix,
    the folder or a prompt.
  • Names aren't unique in Codeman, so two live matches refuse, print their numbers and suggest
    codeman tui <number>. A name only a RECENT row carries says the session has finished rather
    than "not found".
  • The target is resolved before the TTY check, so a script learns "no such name" /
    "ambiguous" without a terminal. (codeman tui 99 piped now says "there is no session 99" instead
    of "needs an interactive terminal"; both exit 1.)
  • Degraded mode (server down) works unchanged: the rows come from tmux + state.json, names
    included.

Code: resolveAttachTarget() and attachTargetError() in src/tui/tui-app.ts are pure;
runTuiAttach() takes number | string; src/cli.ts routes digits vs names.

Tests

  • test/tui/tui-app.test.ts: position vs name, exact and case-sensitive, no prefix, ambiguous
    positions, finished vs missing, the wording of each refusal.
  • test/tui/tui-e2e.test.ts (piped, against the fake server): a live name gets past resolution
    to the TTY refusal; missing, finished and ambiguous names; digits still a number.
  • docs/tui.md, CLAUDE.md one-liner, changeset.
  • npm run typecheck, lint, format:check, check:frontend-syntax, check:browser-excludes,
    npm test: all TUI and CLI tests pass. On this Mac 99 tests in 21 other files fail identically on plain master (/var vs /private/var paths, locally installed models, watcher timing); CI runs on Linux.

Note: codeman tui (under a pty) > says so when the dialog has already left the screen is flaky
on this machine on plain master too (2 of 4 runs failed with no changes); it is unrelated to this
PR.

Opened with Claude Code on behalf of @kkalisz.

🤖 Generated with Claude Code

kkalisz and others added 2 commits November 17, 2026 23:23
codeman tui <session> takes a list number or a session name. Digits only
stay a number; anything else matches the session name exactly
(case-sensitive, never a prefix, folder or prompt). Names are not unique,
so two live matches refuse and print their numbers; a name only a RECENT
row carries says the session has finished. The target is resolved before
the TTY check, so scripts get these answers without a terminal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kkalisz
kkalisz marked this pull request as ready for review November 18, 2026 06:00
@Ark0N

Ark0N commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Thanks for this, and for splitting it out of Discussion #833. It lets codeman tui <session> take an exact session name as well as the list number, which is what you want when you come back over SSH and the numbers have moved.

The code is in good shape. resolveAttachTarget() is pure and well covered, and digits keep their old meaning. I checked by hand that degraded mode (no server, names from state.json) resolves names, and that a real attach by name lands on the right tmux session. typecheck, lint, format:check, check:frontend-syntax, check:browser-excludes and the TUI and CLI test files all pass here.

A few small docs things:

  1. docs/tui.md (lines 10, 30, 100, 123, 225, 269): most of the diff in this file is a Prettier reflow of the four tables and two *emphasis* markers. docs/ is hand-formatted on purpose and sits outside npm run format's scope, and the reflow turns the What it needs table into 330-character rows. Please keep only the new example line, the fast paths sentence and the new paragraph.
  2. docs/tui.md:24: with "two" dropped, the next line ("Neither sets up a screen, so both are...") no longer fits. There are still two fast paths (--list and attach, which now takes a number or a name), so putting "two" back is enough.
  3. src/tui/tui-app.ts:2: the @fileoverview still lists the fast paths as (--list, <n>). <n|name> would match the new runTuiAttach comment.
  4. Optional: docs/wiki/Remote-Access.md:257 (the SSH page) and the example block at README.md:746 show only codeman tui 2. Adding one codeman tui <name> line there would make the feature easier to find for people who use it over SSH.

You don't need to push again for any of this: I will apply 1 to 3 on top when merging. Part 2 (--new) is outside this review, and that question is still open in Discussion #833.

Review on Ark0N#834: drop the Prettier reflow of docs/tui.md and keep only the
new example line and paragraph, put "two" back in the fast-paths
sentence, list <n|name> in the tui-app.ts fileoverview, and add a
codeman tui <name> line to the README and the Remote Access wiki page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kkalisz

kkalisz commented Nov 18, 2026

Copy link
Copy Markdown
Author

Thanks for the review. All four are in 8b809da, so nothing to apply on merge:

  1. docs/tui.md: the Prettier reflow is gone. The file is back to master plus the example line and the new paragraph (wrapped to the file's width).
  2. "The two fast paths" is back.
  3. The @fileoverview in src/tui/tui-app.ts now lists (--list, <n|name>).
  4. Added a codeman tui api-docs line to the README example block and to docs/wiki/Remote-Access.md.

typecheck, lint, format:check and the pre-push static checks pass.

Posted with Claude Code on behalf of @kkalisz.

@Ark0N

Ark0N commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Thanks @kkalisz, and thanks for the quick turnaround on the first round. With this, codeman tui <session> takes an exact session name as well as the list number, so getting back into the same session over SSH no longer depends on where it sits in the list.

All four points from the first round are in 8b809da4. I ran typecheck, lint, format:check, check:frontend-syntax, check:browser-excludes and the TUI and CLI test files here, and they pass. I also tried it by hand with no server running, where the names come from state.json, and under a real terminal, where a name with a space and a plain name each attached to the right tmux session.

At merge time I will add the matching example line to README.zh-CN.md (its codeman tui block, around line 743). Nothing else is needed from you for this PR.

Review on Ark0N#834.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kkalisz

kkalisz commented Nov 18, 2026

Copy link
Copy Markdown
Author

Added the README.zh-CN.md line in d9ded95 (codeman tui api-docs # 直接附着到名为 api-docs 的活动会话), mirroring the English README, so there is nothing left to add at merge.

Posted with Claude Code on behalf of @kkalisz.

@Ark0N

Ark0N commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Thanks again @kkalisz. This PR lets codeman tui <session> attach by an exact session name as well as by list number, so getting back into the same session over SSH no longer depends on where it sits in the list.

I checked the head commit (d9ded95b) again: typecheck, lint, format:check, check:frontend-syntax, check:browser-excludes, all of test/tui/ and test/cli-commands.test.ts pass, and the empty-name refusal in src/cli.ts works when I run it by hand.

There is one small wording change, which I will make on top when merging, so you don't need to push anything:

  • src/tui/tui-app.ts:2745: the not-found message ends with "Run codeman tui --list to see the names." The --list column is rowLabel() cut to 48 characters. An unnamed session shows its folder there, a long auto-name ends in an ellipsis, and neither one resolves as a name. I will reword the hint so it doesn't promise that the column is the name.

With that change on top, this is ready to merge.

The --list column is rowLabel() cut to 48 characters: an unnamed session
shows its folder, a long name ends in an ellipsis, and neither resolves as
a name. Point at attaching by number instead. Review on Ark0N#834.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kkalisz

kkalisz commented Nov 18, 2026

Copy link
Copy Markdown
Author

Good catch on the --list column. Reworded in d7b195a, so nothing to change at merge:

there is no session named <name>
Names match exactly. Run codeman tui --list and attach by number instead.

typecheck, format:check, the pre-push static checks, test/tui/tui-app.test.ts, test/cli-commands.test.ts and the e2e name tests pass. The one e2e failure here is the pty test "says so when the dialog has already left the screen", flaky on plain master on this Mac as noted in the description.

Posted with Claude Code on behalf of @kkalisz.

@Ark0N

Ark0N commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Thanks @kkalisz, and thanks for the quick turnaround on every round. This PR lets codeman tui <session> attach by an exact session name as well as by list number, so getting back into the same session over SSH no longer depends on where it sits in the list.

I checked the head commit (d7b195a7), which has the reworded not-found hint. It passes typecheck, lint, format:check, check:frontend-syntax and check:browser-excludes, all of test/tui/ and test/cli-commands.test.ts pass, and the full npm test gate is green here. I also tried the edge cases by hand: an empty name, 0, 007, a name starting with - (passed after --), and a name that doesn't exist. Each one gives the right message and exit code.

There is nothing else you need to do. It's ready to merge as it stands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants