{"id":30764770,"url":"https://github.com/airbnb/appear","last_synced_at":"2025-09-04T17:13:58.623Z","repository":{"id":56842525,"uuid":"64990990","full_name":"airbnb/appear","owner":"airbnb","description":"reveal terminal programs in the gui","archived":false,"fork":false,"pushed_at":"2017-08-23T22:52:49.000Z","size":1644,"stargazers_count":30,"open_issues_count":2,"forks_count":19,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-08-09T19:55:17.512Z","etag":null,"topics":["applescript","iterm2","macos","revealer","tmux"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/airbnb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-05T05:28:04.000Z","updated_at":"2025-02-01T23:00:55.000Z","dependencies_parsed_at":"2022-09-01T09:02:56.163Z","dependency_job_id":null,"html_url":"https://github.com/airbnb/appear","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/airbnb/appear","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbnb%2Fappear","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbnb%2Fappear/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbnb%2Fappear/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbnb%2Fappear/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/airbnb","download_url":"https://codeload.github.com/airbnb/appear/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbnb%2Fappear/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273641916,"owners_count":25142255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"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":["applescript","iterm2","macos","revealer","tmux"],"created_at":"2025-09-04T17:13:56.208Z","updated_at":"2025-09-04T17:13:58.614Z","avatar_url":"https://github.com/airbnb.png","language":"Ruby","readme":"# Appear\n\nAppear your terminal programs in your gui!\n\n[![GitHub repo](https://badge.fury.io/gh/airbnb%2Fappear.svg)](https://github.com/airbnb/appear) [![Build Status](https://secure.travis-ci.org/airbnb/appear.svg?branch=master)](http://travis-ci.org/airbnb/appear) [![Gem Version](https://badge.fury.io/rb/appear.svg)](https://badge.fury.io/rb/appear)\n\nDocs: [current gem](http://www.rubydoc.info/gems/appear), [github master](http://www.rubydoc.info/github/airbnb/appear/master), your branch: `bundle exec rake doc`\n\n[![screenshot demo thing](./screenshot.gif)](https://github.com/airbnb/appear/raw/master/screenshot.gif)\n\u003c!-- the above screenshot is purposefully broken for YARD docs: it's annoying\n     there, but nice on github :) --\u003e\n\nAppear is a tool for revealing a given process in your terminal. Given a\nprocess ID, `appear` finds the terminal emulator view (be it a window, tab, or\npane) containing that process and shows it to you. Appear understands terminal\nmultiplexers like `tmux`, so if your target process is in a multiplexer\nsession, `appear` will reveal a client connected to that session, or start one\nif needed.\n\nThis project intends to support all POSIX operating systems eventually, but\ncurrently only supports macOS.\n\n## usage\n\n```\nUsage: appear [OPTION]... [PID]\nAppear PID in your user interface.\nAppear will use the current process PID by default.\n\nOptions:\n    -l, --log-file [PATH]            log to a file\n    -v, --verbose                    tell many tales about how the appear process is going\n        --record-runs                record every executed command as a JSON file in the appear spec folder\n        --version                    show version information, then exit\n    -?, -h, --help                   show this help, then exit\n\nExit status:\n  0  if successfully revealed something,\n  1  if an exception occurred,\n  2  if there were no errors, but nothing was revealed.\n```\n\n## supported terminal emulators\n\nmacOS:\n\n - iTerm2\n - Terminal\n\ncross-platform:\n\n - tmux\n\nGNU Screen support is a non-goal. It's time for screen users to switch to tmux.\n\n## system requirements\n\n - `ruby` \u003e= 1.9.3\n - `lsof` command\n - `ps` command\n - `pgrep` command\n - if you're a mac, then you should have macOS \u003e= 10.10\n\nAppear depends only on the Ruby standard library.\n\n## how it works\n\nHere's how Appear works in a nutshell, given a `target_pid`\n\n1. get all the parent processes of `target_pid`, up to pid1. We end up with a\n   list of ProcessInfos, which have fields `{pid, parent_pid, command, name}`\n2. go through our list of \"revealers\", one for each terminal emulator (tmux,\n   iterm2, terminal.app) and ask the revealer if it can apply itself to the\n   process tree.\n3. if a revealer finds an associated process in the tree (eg, tmux revealer\n   finds the tmux server process), it performs its reveal action\n    - this usually involves invoking `lsof` on a `/dev/ttys*` device to see what\n      processes are talking on what ttys to each other, which takes a bunch of\n      time\n    - `lsof` in Appear is parallel, so grouped lsof calls are less expensive\n    - the Tmux revealer is smart enough to both focus the pane that the\n      `target_pid` is running in, AND to recurse the revealing process with the\n      tmux client id, to reveal the tmux client.\n4. the revealer sends some instructions to the terminal emulator that contains\n   the view for the PID\n    - for our Mac apps, this involves a helper process using [Javascript for\n      Automation][jfora], a JavaScript x Applescript crossover episode.\n    - for tmux this is just some shell commands, super easy.\n\n[jfora]: https://developer.apple.com/library/mac/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/Articles/OSX10-10.html#//apple_ref/doc/uid/TP40014508-CH109-SW1\n\n## ruby api\n\nThe method documented here is the only part of Appear that should be considered\nstable.\n\n```ruby\nrequire 'appear'\n\n# super simple\nAppear.appear(pid)\n\n# You may customize logging, if needed, using the Config class\nconfig = Appear::Config.new\n\n# print debug info to STDOUT\nconfig.silent = false\n# also write to a log file\nconfig.log_file = '/tmp/my-app-appear.log'\n\nAppear.appear(pid, config)\n```\n\n## contributing\n\nFirst, get yourself set up:\n\n1. make sure you have bundler. `gem install bundler`\n2. inside a git clone of the project, run `./scripts/setup` or `bundle install`\n\nThen, submit PRs from feature branches for review:\n\n1. `git checkout -b my-name--my-branch-topic`\n1. write code\n1. run `./scripts/console` for a nice pry session with an instance ready to go\n1. run `bundle exec rake` to run tests and doc coverage\n1. commit and push your changes, however you do\n1. [open a PR against airbnb master](https://github.com/airbnb/appear/compare?expand=1)\n\n## releasing new versions\n\nYou must be a collaborator on Rubygems.org, and a committer on the main repo at\nhttps://github.com/airbnb/appear.\n\n1. update lib/appear/version.rb with the new version number\n1. update CHANGELOG.md with changes in the new version\n1. commit those changes, and merge them to master\n1. checkout master\n1. `bundle exec rake release`\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairbnb%2Fappear","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fairbnb%2Fappear","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairbnb%2Fappear/lists"}