package

github.com/ch1c0t/crystal.pty

main / published Nov 14, 2026 / repository

crystal.pty

A Linux PTY library for Crystal. It supports one-shot commands as well as long-lived sessions that keep the same pseudo-terminal open across multiple input writes.

Interactive sessions

Use PTY::Session when a process should stay attached to one PTY while you interact with it repeatedly:

session = PTY::Session.new(["/bin/sh", "-i"], rows: 40, columns: 120)
session.start do |chunk|
  print chunk
end

session.write("export PTY_SESSION_VALUE=kept\n")
session.write("printf '%s\\n' \"$PTY_SESSION_VALUE\"\n")
session.write("exit\n")
exit_code = session.wait

start launches the process and returns without waiting for it to exit. The optional callback receives output chunks as they arrive; the complete transcript is available through session.output. Call write as often as needed to send input to the same terminal. resize(rows:, columns:) changes the PTY window size. alive? checks whether the command leader is still running, wait returns its exit status, and terminate or close terminates the process group and waits for cleanup.

A PTY is one continuous terminal byte stream. It does not inherently tell you which output belongs to a particular command or when a command sent to an interactive shell has finished; applications that need per-command completion should use their own markers or protocol.

One-shot API used by tmux.run

PTY::Command remains the backwards-compatible one-shot API. Its three-argument constructor and streaming callback are preserved:

command = PTY::Command.new(command_string, index, run_id)
output, exit_code = command.execute_inside_pty do |chunk|
  output_sink.write(chunk)
end

The implementation now uses PTY::Session internally, then waits for completion and returns the accumulated terminal transcript and exit status. Existing consumers do not need to change.

Prefer an argv array when shell parsing is not required:

output, exit_code = PTY.run(["/usr/bin/printf", "hello\\n"]) do |chunk|
  print chunk
end

Use a shell string only when shell syntax is intended:

output, exit_code = PTY.run("printf 'hello\\n'; exit 3")

When both rows and columns are supplied, they configure the PTY window size. When omitted, the native openpty default is preserved:

output, exit_code = PTY.run("stty size", rows: 40, columns: 120)

Logging

PTY emits diagnostics through Crystal's logging system instead of writing directly to STDERR. Startup lifecycle messages use the pty.session source at DEBUG level; detailed output, sentinel, and synchronization diagnostics use pty.session.trace at TRACE level. Both are covered by the source pattern pty.*.

The library does not configure the application's global logger. To use LOG_LEVEL=DEBUG or LOG_LEVEL=TRACE, configure logging in the application (for example, with Log.setup_from_env):

require "log"

Log.setup_from_env(backend: Log::IOBackend.new(STDERR))

For explicit source-based configuration, bind the PTY sources separately from the rest of the application:

Log.setup do |c|
  backend = Log::IOBackend.new(STDERR)
  c.bind "*", :info, backend
  c.bind "pty.*", :debug, backend # Use :trace to include detailed internals.
end

Reliability contract

  • Child launch uses openpty, fork, login_tty and a shell wrapper that writes command status to a unique temporary file using atomic rename. Child-side launch failures terminate through _exit(127).
  • A blocking PTY reader drains output concurrently, preserving the combined stdout/stderr terminal stream.
  • Linux PTY EIO on final slave closure is treated as end-of-stream.
  • If descendants keep the slave terminal open after command status is reported, the session allows up to two seconds for natural EOF, then sends SIGHUP and SIGKILL to the command process group.
  • Callback exceptions terminate the process group, clean up the reader and PTY, and are re-raised.
  • stdin, stdout and stderr are attached to the controlling PTY. If TERM is unset, it defaults to xterm-256color in the child.

Running specs in isolated processes

Build the srun runner and invoke it from the repository root:

shards build srun
./bin/srun --timeout 30

srun discovers spec/**/*_spec.cr and runs each file as a separate crystal spec <file> process. It uses GNU timeout (coreutils) to enforce a 30-second per-spec timeout by default; override it with --timeout SECONDS or SRUN_TIMEOUT. Every invocation creates a directory named after the current directory with both Unix time and a %Y%m%d_%H%M%S timestamp. Full output is saved under passing/ or failing/, and report.txt lists each result, failure details and timeout events. Timed-out process groups receive TERM and are escalated to KILL after two seconds if they do not exit.

Development

bundle install
bundle exec rake
crystal spec
bundle exec rspec

GitHub Actions regenerates sources, builds the CLI target, verifies generated-source consistency, and runs the PTY regression suite plus Ruby CLI smoke tests on Crystal 1.22.

API