Skip to content

feat: interactive session browser with search filtering (#718)#733

Merged
teknium1 merged 1 commit into
mainfrom
hermes/hermes-cfe83dd1
Mar 9, 2026
Merged

feat: interactive session browser with search filtering (#718)#733
teknium1 merged 1 commit into
mainfrom
hermes/hermes-cfe83dd1

Conversation

@teknium1

@teknium1 teknium1 commented Mar 9, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds hermes sessions browse — a curses-based interactive session picker with live type-to-search filtering. Partially addresses #718.

What This Does

hermes sessions browse              # Interactive picker
hermes sessions browse --source cli # Filter by source
hermes sessions browse --limit 100  # Load more sessions

The picker shows recent sessions with title/preview, last active time, source, and ID. Users can:

  • Arrow keys to navigate through sessions
  • Type characters to live-filter by title, preview, source, or session ID
  • Backspace to edit the filter, Esc to clear filter (first) or quit (second)
  • Enter to select and seamlessly resume the session
  • q to quit (when not filtering)

After selecting a session, the picker seamlessly execs into hermes --resume <id>.

Design Decisions

  • Separate subcommand, not a flag — hermes -c is preserved as-is for instant most-recent-session resume
  • Uses curses (not simple_term_menu) per Known Pitfalls to avoid the arrow-key ghost-duplication rendering bug in tmux/iTerm
  • Follows existing curses pattern from hermes_cli/tools_config.py
  • Windows fallback: numbered list with input() prompt

What This Does NOT Do (remaining #718 scope)

  • No --latest flag (not needed since hermes -c already does this)
  • No sessions list -i flag (could be added later if desired)

Bug Fix

Removed a redundant import os inside the cmd_sessions stats block that shadowed the module-level import. This would cause UnboundLocalError when the browse action tried to use os.execvp since Python treats os as a local variable if any branch of the function contains import os.

Tests

33 new tests in tests/hermes_cli/test_session_browse.py:

  • Curses picker navigation (Enter, Up, Down, Esc, q)
  • Live search filtering (type-to-filter, backspace, Esc-clears-filter)
  • Fallback mode (valid selection, cancel, invalid input, keyboard interrupt)
  • Display logic (title vs preview vs ID, truncation, relative time)
  • Edge cases (missing fields, single session, long titles)

All 2377+ tests pass, no regressions.

Live Testing

Verified interactively via tmux:

  • Arrow navigation works without ghost duplication
  • Type-to-filter narrows results in real time
  • Esc clears filter first, then exits
  • Enter + session selection seamlessly launches into resumed session

Closes #718

Add `hermes sessions browse` — a curses-based interactive session picker
with live type-to-search filtering, arrow key navigation, and seamless
session resume via Enter.

Features:
- Arrow keys to navigate, Enter to select and resume, Esc/q to quit
- Type characters to live-filter sessions by title, preview, source, or ID
- Backspace to edit filter, first Esc clears filter, second Esc exits
- Adaptive column layout (title/preview, last active, source, ID)
- Scrolling support for long session lists
- --source flag to filter by platform (cli, telegram, discord, etc.)
- --limit flag to control how many sessions to load (default: 50)
- Windows fallback: numbered list with input prompt
- After selection, seamlessly execs into `hermes --resume <id>`

Design decisions:
- Separate subcommand (not a flag on -c) — preserves `hermes -c` as-is
  for instant most-recent-session resume
- Uses curses (not simple_term_menu) per Known Pitfalls to avoid the
  arrow-key ghost-duplication rendering bug in tmux/iTerm
- Follows existing curses pattern from hermes_cli/tools_config.py

Also fixes: removed redundant `import os` inside cmd_sessions stats
block that shadowed the module-level import (would cause UnboundLocalError
if browse action was taken in the same function).

Tests: 33 new tests covering curses picker, fallback mode, filtering,
navigation, edge cases, and argument parser registration.
@teknium1 teknium1 merged commit f88343a into main Mar 9, 2026
1 check passed
@teknium1

teknium1 commented Mar 9, 2026

Copy link
Copy Markdown
Contributor Author

Merged to main via f88343a.

angelburgosrosado pushed a commit to angelburgosrosado/hermes-agent that referenced this pull request Apr 27, 2026
02356abc pushed a commit to 02356abc/hermes-agent that referenced this pull request May 14, 2026
olympus-terminal pushed a commit to olympus-terminal/hermes-agent that referenced this pull request May 16, 2026
Egavasyug pushed a commit to Egavasyug/hermes-agent that referenced this pull request Jun 10, 2026
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.

Feature: Interactive Session Picker for hermes --continue — Browsable Session List with Search

1 participant