pty
Version, currently main branch1 version
- main branchlatestNov 14, 2026
github.com/ch1c0t/crystal.pty
No description declared in shard.yml.
Installation
# Add this to your shard.yml
dependencies:
pty:
github: ch1c0t/crystal.pty
branch: mainmain is a branch, not a release, so this tracks it rather than pinning a version.
Then run:
shards installshard.yml
- Crystal
>= 1.15.1- Author
- Anatoly Chernov
- Target
crystal.ptyfrom src/bin/crystal.pty.cr
Dependencies
Runtime Dependencies
- queue*github: ch1c0t/crystal.queue
README
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_ttyand 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
EIOon 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
TERMis unset, it defaults toxterm-256colorin 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.
Documentation
Built from the current release. The first visit to a release nobody has asked for starts its build.
Links
This branch
- Branch
main- Seen
- Nov 14, 2026
- Crystal
>= 1.15.1- Indexed
- yes
Dependents
Repository
github.com/ch1c0t/crystal.pty
Metadata
- Created
- Nov 13, 2026
- Updated
- Nov 18, 2026
- Synced
- Nov 18, 2026
- Versions
- 1