{"id":50560046,"url":"https://github.com/left-arm/tty-proxy","last_synced_at":"2026-06-04T11:30:41.927Z","repository":{"id":353944415,"uuid":"1221521143","full_name":"left-arm/tty-proxy","owner":"left-arm","description":"A Unix-socket TTY proxy for interactive Common Lisp sessions, written in Zig","archived":false,"fork":false,"pushed_at":"2026-04-26T10:35:12.000Z","size":9,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T12:22:12.234Z","etag":null,"topics":["commonlisp","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/left-arm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T10:25:19.000Z","updated_at":"2026-04-26T10:36:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/left-arm/tty-proxy","commit_stats":null,"previous_names":["left-arm/tty-proxy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/left-arm/tty-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/left-arm%2Ftty-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/left-arm%2Ftty-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/left-arm%2Ftty-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/left-arm%2Ftty-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/left-arm","download_url":"https://codeload.github.com/left-arm/tty-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/left-arm%2Ftty-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33903134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commonlisp","zig"],"created_at":"2026-06-04T11:30:41.086Z","updated_at":"2026-06-04T11:30:41.922Z","avatar_url":"https://github.com/left-arm.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tty-proxy\n\n`tty-proxy` is a Zig 0.15.2 executable that owns terminal handling and forwards\nbytes between a terminal and a local Common Lisp peer over a Unix socket.\n\n## Building\n\nThis project uses Zig's standard build system (`build.zig`). The build script\ninstalls the executable into `zig-out/bin/tty-proxy`.\n\n```sh\nzig build\n```\n\nCommon build commands:\n\n```sh\nzig build                # compile and install tty-proxy\nzig build test           # run unit tests\nzig build run -- [args]  # run tty-proxy with optional arguments\n```\n\nYou can also pass Zig's standard build options, for example:\n\n```sh\nzig build -Dtarget=x86_64-linux -Doptimize=ReleaseSafe\n```\n\nRun `zig build --help` to see the full list of project-specific and standard\noptions.\n\n## Requirements\n\n- Zig 0.15.2\n- A Unix-like system with Unix sockets, `termios`, and `pselect`\n\n## Configuration\n\nAt runtime, `tty-proxy` reads a plain-text config file from either:\n\n1. `TTY_PROXY_CONFIG`, or\n2. `~/.config/tty-proxy/config`\n\nEntries map an executable name to a peer socket path. Resolution prefers the\nexact `argv[0]` key and falls back to the basename of `argv[0]`.\n\nExample:\n\n```text\n# comments and blank lines are ignored\ntty-proxy = socket:/tmp/tty-proxy.sock\n```\n\nOnly `socket:` values are used. Other values are ignored.\n\n## Runtime Protocol\n\nOn startup, `tty-proxy`:\n\n1. verifies that `stdin` is a tty\n2. resolves and connects to the configured Unix socket\n3. sets `stdin`, `stdout`, `stderr`, and the peer socket non-blocking\n4. queues startup info to the peer as a Lisp plist:\n\n```lisp\n(:args (...) :tty \"/dev/tty...\"\n :env ((NAME VALUE) ...)\n :size (:rows R :cols C :xpixels X :ypixels Y))\n```\n\nAfter reading startup info, the peer sends a single operation-mode byte:\n\n- `R` — `tty-proxy` enables raw mode on `stdin` and restores the\n  original terminal settings on exit\n- `C` — `tty-proxy` leaves the terminal mode unchanged\n- `E` — `tty-proxy` leaves the terminal mode unchanged and treats peer\n  output as an error stream\n\nIn `C` and `E`, `tty-proxy` does not call `tcsetattr(2)`. The peer still can\nchange terminal settings itself, for example by opening the reported `:tty`\npath and configuring it directly.\n\n`tty-proxy` consumes that first byte, then forwards the remaining peer payload.\n\n## I/O Behavior\n\n`tty-proxy` uses a single-threaded `pselect(2)` loop with two internal buffers:\n\n- `to_lisp` — bytes pending to the peer\n- `to_term` — bytes pending to terminal output\n\nBehavior by mode:\n\n- In `R` and `C`, terminal input is read and forwarded to the peer.\n- In `R`, `tty-proxy` enables raw mode before forwarding interactive\n  input and restores the original terminal settings on exit.\n- In `C`, `tty-proxy` leaves the existing terminal mode untouched.\n- Peer output is written to `stdout` in `R` and `C`.\n- In `E`, no further bytes are sent to the peer.\n- In `E`, peer output is written to `stderr`.\n- On peer EOF, `tty-proxy` drains buffered output before exiting.\n- If the final mode was `E`, `tty-proxy` exits with status `1` after flushing\n  the error message.\n\nSignals:\n\n- `SIGINT` and `SIGTERM` are handled\n- signal exit status is `128 + signal`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleft-arm%2Ftty-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleft-arm%2Ftty-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleft-arm%2Ftty-proxy/lists"}