How akiriwas/visscreen works
1. What this repository is
- VisScreen is a local terminal UI application for Linux that manages existing GNU screen sessions.
- It is not a server/client app and has no database or network layer; the main external dependency is the local screen executable.
2. Top-level structure
- visscreen/app.py is the TUI application entrypoint and likely owns the Textual app lifecycle, key bindings, and screen navigation.
- visscreen/manager.py is the command/adapter layer that talks to GNU screen, parses session state, and performs operations like list, create, rejoin, detach, and kill.
- visscreen/renderers.py is the presentation layer for formatting session data into widgets/panes for the TUI.
- visscreen/config.py likely holds runtime constants and UI/config defaults.
- tests/test_manager.py and tests/test_tui.py cover the core behavior and the UI integration points.
3. Primary runtime flow
- On startup, the TUI app initializes and asks the manager for the current set of screen sessions.
- The manager runs screen commands locally, converts their output into structured session records, and returns them to the UI.
- The UI renders those records in a list plus a detail pane; user actions then flow back through the manager to execute the selected screen operation.
4. Core subsystem boundary: UI vs session orchestration
- The UI layer (app.py + renderers.py) is responsible for interaction, filtering/search, selection state, and confirmation dialogs.
- The manager layer (manager.py) is responsible for the semantics of screen session management and for isolating subprocess/CLI details from the UI.
- This separation is important for the architecture: the TUI should not need to know GNU screen command syntax directly.
5. Session model and data shape
- The README indicates each session has visible attributes such as ID, name, timestamp, and state (Attached / Detached).
- That implies the manager normalizes raw screen output into a session object or dictionary-like record that the renderers can consume consistently.
- The detail pane likely uses the same structured session data to show extended metadata.
6. User interaction model
- The UI supports search/fuzzy filtering, selection, and command shortcuts:
- Enter: rejoin selected session
- d: detach and rejoin
- n: create new named session
- k: kill with confirmation
- r: refresh list
- q: quit
- This makes the TUI event-driven: keystrokes mutate UI state, then call manager actions, then refresh the session list.
7. Subprocess and system boundary
- The only meaningful external runtime boundary is the host system’s GNU screen installation.
- All session operations are almost certainly implemented via local subprocess execution of screen commands, meaning the app depends on shell-level availability and Linux-like terminal behavior.
- There are no indications of remote APIs, persistent storage, or background daemons.
8. Rendering responsibilities
- renderers.py likely contains the logic for turning session objects into Textual components: list rows, detail views, status styling, and possibly empty/loading states.
- This layer is distinct from the manager so the UI can re-render the same data in multiple places without re-parsing command output.
9. Configuration and constants
- config.py likely centralizes things such as command names, key labels, UI text, and possibly default refresh or filtering behavior.
- Keeping these values out of the app and manager reduces coupling and makes the TUI easier to adjust without changing business logic.
10. Testing strategy
- tests/test_manager.py probably validates session parsing and command execution behavior, which is the highest-risk logic because it bridges Python and screen output.
- tests/test_tui.py likely checks app-level behavior such as bindings, widget state updates, and reactions to user actions.
- The tests suggest the repo treats manager logic as the core domain layer and the TUI as an interactive presentation shell.
11. Packaging and toolchain
- The presence of pyproject.toml and requirements.txt indicates standard Python packaging plus dependency pinning.
- The project is intended to be installed as a command-line entrypoint (visscreen) rather than imported as a library.
12. Diagram-friendly summary
- A clear architecture diagram would show:
- Terminal user interacting with
- Textual-based TUI app (app.py)
- which depends on
- renderer components (renderers.py) for display and
- manager/services layer (manager.py) for GNU screen orchestration
- which talks to
- local GNU screen subprocesses / system terminal environment
- config.py sits as a shared support module feeding both UI and manager concerns, while tests verify the manager and app behavior separately.
Main entry points: app.py TUI App · manager.py Manager · renderers.py Renderers · test_tui.py TUI Tests
Components 9
Interface
Terminal UI and presentation components
Orchestration
Session management and command execution
- Manager · Runs screen commands and normalizes session operations
visscreen/manager.py
Support
Shared configuration and data shape
- Session Records · Structured session state shared between manager and UI
- Config · Shared constants and runtime/UI defaults
visscreen/config.py
Validation
Test coverage for core behavior
- Manager Tests · Parsing and command-behavior coverage
tests/test_manager.py - TUI Tests · App behavior and interaction coverage
tests/test_tui.py
External
Host-provided GNU screen runtime
- GNU screen · Local screen executable and terminal environment
Connections 12
- User → TUI App: keystrokes · User interacts through the terminal UI
- TUI App → Renderers: render · App asks renderers to build the visible panes
- TUI App → Manager: actions · UI triggers refresh, join, detach, create, and kill flows
- TUI App → Config: defaults · App consumes shared labels and behavior constants
- Manager → GNU screen: subprocess · Manager invokes local GNU screen commands
- Manager → Session Records: normalize · Manager converts raw screen output into session records
- Renderers → Session Records: display · Renderers format structured session data for widgets
- Session Records → TUI App: state · App uses session data for selection and detail views
- Config → Manager: settings · Manager reads shared runtime defaults
- Manager Tests → Manager: covers · Validates command execution and parsing
- TUI Tests → TUI App: covers · Validates UI behavior and interactions
- TUI Tests → Renderers: covers · Checks presentation behavior