interms
interms
A terminal session manager for Crystal. It runs multiple interactive shells through independent PTY::Session instances and lets you switch between them with keyboard shortcuts.
The same Interms::Manager API can be embedded in another Crystal application, or used through the standalone interms executable. The frontend works in a normal terminal, an SSH terminal, or a Tmux pane.
Build
bundle install
shards install
bundle exec rake
Run
./bin/interms
./bin/interms --shell bash --name builder --cwd /mnt/shared
Press Ctrl+Space to open the session command menu:
| Key | Action |
|---|---|
| Ctrl+Space, l | List sessions and select one with 1–9 |
| Ctrl+Space, 1–9 | Switch directly to a session |
| Ctrl+Space, n | Select the next session |
| Ctrl+Space, p | Select the previous session |
| Ctrl+Space, a | Add a new shell session |
| Ctrl+Space, x | Close the active session |
| Ctrl+Space, q | Exit interms |
Ordinary keys are forwarded to the active PTY session. Sessions that are not visible continue running and their output is retained. Selecting a session clears the display and replays its captured terminal byte stream.
Library
Add the shard to shard.yml:
dependencies:
interms:
github: ch1c0t/interms
branch: main
Then use the library:
require "interms"
manager = Interms::Manager.new(rows: 40, columns: 120)
manager.add("shell", shell: :bash, cwd: Dir.current)
manager.add("builder", shell: :bash, cwd: "/mnt/shared/grml-live-build")
# Or register a PTY::Session that the application configured itself.
pty = PTY::Session.new(:bash, rows: 40, columns: 120, cwd: Dir.current)
manager.add("custom", pty)
manager.on_output do |session, chunk|
# Receive output from any session.
end
manager.start
manager.select("builder")
manager.write("pwd\n")
manager.next_session
manager.stop
Manager#add creates a session. Manager#start starts all configured sessions; sessions added afterward start immediately. The manager owns session lifecycle and forwards input to the active session. on_output receives (Session, String) pairs from the corresponding session's PTY reader fiber. Use on_switch to observe active-session changes.
The lower-level Interms::Session abstraction is also public when an application needs to manage a PTY session directly. Construct one with shell options, or wrap an existing PTY::Session and register it with Manager#add(session). Access the underlying object through Interms::Session#pty.
Current rendering model and limitations
Each session owns an independent PTY process and retains its raw output bytes. The initial frontend is a pass-through terminal with transcript replay: it forwards the active session's bytes to the outer terminal and replays a session's captured stream when switching back to it. This preserves ordinary ANSI colour output and commonly used cursor-control sequences when replayed.
This is not yet a full virtual-terminal emulator. Complex full-screen programs that depend on terminal modes, mouse input, focus events, or exact independent screen state may not be restored perfectly after switching. A per-session VT screen model is a planned next layer; the manager and PTY lifecycle API do not depend on the current renderer.
The output transcript is currently retained in memory for the lifetime of each session. Long-running sessions with large output can therefore consume substantial memory.
Design
Interms::Managerowns a registry of namedInterms::Sessionobjects.- Each
Interms::Sessionowns onePTY::Sessionand an interactive child shell. Input is written to that PTY, and output is captured through the PTY session's streaming callback. Interms::Frontendowns the outer terminal's raw mode, hotkeys, display, and resize detection. It does not own the sessions.- The library can be used without loading or starting the interactive frontend.
Run specs with:
bundle exec rake
crystal spec
bundle exec rspec
interms
- 0
- 0
- 0
- 0
- 1
- about 4 hours ago
- November 21, 2026
Sun, 22 Nov 2026 02:34:31 GMT