How quantumsheep/sshs works
1. Repository shape
- This is a single-binary Rust project (Cargo.toml, src/main.rs) that builds a terminal user interface for SSH host selection and connection.
- The runtime is local only: it reads the user’s SSH config, shows an interactive host picker, and then hands off to the system ssh client.
2. Top-level control flow
- main.rs is the orchestration point.
- The app likely follows a pipeline of: load SSH config → parse into host records → make records searchable → render UI → launch SSH for the chosen host.
3. SSH config ingestion boundary
- The src/ssh_config/ module is the parsing subsystem.
- It is split into:
- parser.rs for reading OpenSSH-style config syntax,
- host.rs / host_entry.rs for the domain model of hosts and their entries,
- parser_error.rs for parse failures,
- mod.rs as the module boundary.
- Input comes from ~/.ssh/config by default, with support for an alternate config path per the README.
4. Data model produced by parsing
- The parser turns the config file into a set of host definitions that can be displayed and matched in the UI.
- The important architectural boundary is that the rest of the app consumes parsed host metadata, not raw config text.
5. Search/indexing layer
- searchable.rs suggests an abstraction for filtering or ranking hosts by user input.
- This sits between parsed host data and the UI, enabling interactive narrowing of the host list as the user types.
6. Terminal UI subsystem
- ui.rs contains the interactive terminal interface.
- Its job is to display the host list, accept keyboard input, apply search/filter logic, and return the selected host.
- This is the main user-facing loop of the application.
7. SSH execution subsystem
- ssh.rs is the execution boundary to the outside world.
- Once a host is selected, this layer is responsible for invoking the external ssh executable with the right target details.
- The README makes clear that the system ssh binary must already be installed and accessible in PATH.
8. Key external dependencies and boundaries
- Filesystem: reads SSH config from local disk.
- Terminal: all interaction happens in a TUI, so the app owns the terminal while running.
- Process execution: delegates actual connection handling to ssh, rather than reimplementing SSH.
9. Error handling
- Parse-time failures are isolated in parser_error.rs, which suggests clean separation between config syntax issues and UI/runtime issues.
- A likely user-visible failure mode is missing or invalid SSH config; the README explicitly documents this.
10. Testing and release infrastructure
- test/ indicates there are repository-level tests or fixtures for config parsing or behavior.
- .github/workflows/push.yml and release.yml show CI for validation and release automation.
- This is a packaged CLI app, distributed through package managers and GitHub releases rather than through a server deployment.
11. Architecture diagram hint
- The central flow to diagram is: SSH config file → parser → host model → searchable list → TUI → ssh subprocess.
- Everything else is supporting structure around that loop.
Main entry points: parser.rs Parser · ui.rs Terminal UI · main.rs Main · host.rs Host model
Components 16
Core app
Runtime flow from entrypoint through parsing, search, UI, and SSH handoff.
- Main · Orchestrates config loading, search, UI, and execution.
src/main.rs - Searchable · Makes host records searchable for interactive narrowing.
src/searchable.rs - Terminal UI · Interactive host picker and input loop.
src/ui.rs - SSH runner · Launches the system ssh client for the selected host.
src/ssh.rs - System ssh · Installed ssh executable invoked after selection.
- Terminal · Interactive terminal session owned by the TUI.
- Filesystem · Local disk source for SSH config and fixtures.
SSH config
Parsing and modeling OpenSSH-style host configuration.
- SSH config mod · Module boundary for SSH config parsing and host modeling.
src/ssh_config/mod.rs - Parser · Reads OpenSSH-style config syntax into host data.
src/ssh_config/parser.rs - Host model · Represents parsed SSH host definitions.
src/ssh_config/host.rs - Host entry · Captures individual host entry fields and options.
src/ssh_config/host_entry.rs - Parse error · Represents SSH config parsing failures.
src/ssh_config/parser_error.rs - SSH config file · Local ~/.ssh/config or alternate config path.
Ops
CI and release automation around the CLI binary.
- GitHub Actions · Workflow automation for validation and releases.
.github/workflows - Push workflow · Validation pipeline on repository changes.
.github/workflows/push.yml - Release workflow · Automates packaging and publishing releases.
.github/workflows/release.yml
Connections 17
- Main → SSH config mod: load config · Main starts by reading SSH configuration through the config module.
- SSH config mod → Parser: parse · Module boundary delegates syntax parsing to the parser.
- Parser → Host model: build hosts · Parser produces host definitions consumed by the rest of the app.
- Parser → Host entry: emit entries · Parser populates individual host entry records.
- Parser → Parse error: fail with · Syntax and read failures are reported as parse errors.
- SSH config file → Parser: input · Parser reads the user SSH config from disk.
- Filesystem → SSH config file: stores · The config file lives on local filesystem.
- Host model → Searchable: index · Parsed host data is transformed into searchable records.
- Searchable → Terminal UI: filter list · UI uses search abstraction to narrow hosts as the user types.
- Terminal UI → Terminal: render/input · Terminal UI owns display and keyboard interaction.
- Terminal UI → Host model: select host · UI returns the chosen host record to the caller.
- Main → Terminal UI: run picker · Main launches the interactive selection loop.
- Main → SSH runner: launch ssh · Main hands the selected host to the SSH execution layer.
- SSH runner → System ssh: exec · Execution layer invokes the external ssh binary.
- System ssh → Terminal: connects via · SSH session takes over the user terminal after launch.
- GitHub Actions → Push workflow: includes · CI validation workflow is defined under GitHub Actions.
- GitHub Actions → Release workflow: includes · Release automation workflow is defined under GitHub Actions.