Skip to content
Projects

iurysza/termscope has 70 GitHub stars and 15 forks. GitHot measured 0 stars in 24 hours, -1 in 7 days, and 0 in 15 days. Last checked 2026-11-17 02:03 UTC. Last push 2026-10-25.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
-1
in 15 days
0
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Open files and links already visible on your terminal screen in a split.

Developer Tools

README.md

Original

termscope

termscope cover

CI License: MIT herdr 0.7.4+ platforms: macOS • Linux

Open the files and links your agent just mentioned.

termscope turns terminal output into a jump list. It reads the visible terminal viewport of every pane in the current window/tab, finds real files and URLs, then opens the selected target beside the conversation you were already reading.

visible terminal viewport
        │
        ▼
Ctrl-Shift-A  →  pick a visible file  →  nvim opens src/main.py:42
Ctrl-E        →  pick a visible link  →  browser opens it

Demo

https://github.com/user-attachments/assets/12447931-8fa4-441c-a406-a0abc40930ed

Why

Agents constantly mention files: stack traces, changed tests, docs, configs, links, PRs. termscope lets you keep up without doing the little dance: select text, copy, cd, paste, fix the path, add the line number.

If it's visible in the window and exists in the repo, you can jump to it.

Termscope stays conservative:

  • scans only the visible text of the current window's panes
  • verifies paths against the repo/worktree on disk
  • preserves file:line targets
  • falls back to a full repo picker when no visible file matches
  • uses a session-modal Herdr popup, leaving the tiled pane layout untouched

Requirements

You must already have these on PATH. Plugin install does not install them.

  • python3 3.11+ (the plugin and shebang call python3, not python)
  • fd as the fd binary. Debian/Ubuntu apt install fd-find ships fdfind; symlink it to fd (a shell alias is not enough).
  • nvim for the default file-open action
  • a URL/default-app opener: open on macOS, xdg-open on Linux, wslview on WSL

Host — pick one:

  • Herdr >= 0.7.4 for the plugin
  • tmux for the standalone termscope script

Picker UI:

  • Television >= 0.15 (tv). herdr plugin install and ./scripts/install-dependencies.sh install or upgrade it through Homebrew when needed. Herdr popups often omit Homebrew from PATH; Termscope records the absolute tv path at install and also looks in /opt/homebrew/bin and /usr/local/bin.
  • Homebrew only if tv is missing or older than 0.15. The installer never installs Homebrew; without it, and without a new enough tv, install aborts before the plugin is registered.
  • bat optional for syntax-highlighted file previews

Native Windows is not claimed. WSL may work through wslview when your WSL environment provides it.

Install

Herdr plugin

herdr plugin install iurysza/termscope

Pin a release tag with --ref vX.Y.Z.

Herdr clones the repo, then runs scripts/install-dependencies.sh before registering the plugin. That script:

  1. exits 0 if tv already reports Television 0.15+
  2. otherwise brew install / brew upgrade the television formula
  3. writes the absolute tv path to $XDG_CONFIG_HOME/termscope/television.path (~/.config/termscope/television.path when XDG_CONFIG_HOME is unset)
  4. exits 1 (plugin not registered) if Homebrew is missing or tv is still too old

It finds tv and brew on PATH and in /opt/homebrew/bin and /usr/local/bin, so a Herdr install that omits Homebrew from PATH still works. It does not install python3, fd, nvim, bat, or Homebrew.

Confirm the actions exist:

herdr plugin action list --plugin termscope

You should see open and open-links. The install does not bind keys; add the bindings below and reload config.

Local Herdr checkout

herdr plugin link skips install-time build commands, so provision Television yourself:

git clone https://github.com/iurysza/termscope.git
cd termscope
./scripts/install-dependencies.sh
herdr plugin link "$PWD"
herdr plugin action list --plugin termscope

tmux

Clone this repo, run ./scripts/install-dependencies.sh (or install Television 0.15+ another way), and keep python3, fd, and nvim on PATH. Point tmux at the termscope script in that clone — see tmux usage.

Bind keys in Herdr

Herdr plugins register actions; keybindings still live in your ~/.config/herdr/config.toml.

[[keys.command]]
key = "ctrl+shift+a"
type = "plugin_action"
command = "termscope.open"
description = "visible-screen file picker"

[[keys.command]]
key = "ctrl+e"
type = "plugin_action"
command = "termscope.open-links"
description = "visible-screen link picker"

Reload config:

herdr server reload-config

Use it

termscope.open captures the visible text of every pane in the current Herdr tab or tmux window, indexes the git worktree with fd (pane cwd if git is missing or you are not in a repo), and opens a Television popup of matching paths plus any visible http:// / https:// URLs.

  • A path is listed only if it exists on disk in that tree. file:line is kept and passed to Neovim as nvim +line path.
  • Only text that looks like a path counts. Plain words don't match files: report in a sentence doesn't list report.md. Write `README` in backticks, or on its own line, to match README.md.
  • A bare file name such as main.py:12 matches only when exactly one file of that name exists in the repo.
  • Mentioning docs/setup/guide.md lists that file, not its parent folders.
  • Results keep the order they appear on screen.
  • If no visible file matches, the picker falls back to the full repo listing (visible URLs stay first). Indexing $HOME is skipped.
  • termscope.open-links is URLs only.

With the bindings above:

Key Action
Ctrl-Shift-A termscope.open — file picker (URLs included after files)
Ctrl-E termscope.open-links — URL picker

File picker (Television):

Key Action
Enter Open in a new Neovim split beside the source pane or on a new tab
Ctrl-O Open with the default app
Ctrl-Y Agent pane: send /plannotator-annotate <file>; shell pane: run plannotator annotate <file>
Ctrl-S Cycle appearance order / alphabetical sort

On a URL row, Enter / Ctrl-O open it with the default opener and Ctrl-Y copies it (pbcopy on macOS, wl-copy on Wayland, then xclip or xsel). When those tools fail, or when there is no display, Ctrl-Y writes OSC 52 (ESC ] 52 ; c ; <base64> BEL) to the controlling terminal, /dev/tty. Inside tmux the sequence is wrapped for passthrough. The picker shows "Link sent to terminal clipboard" for that write, because the terminal cannot confirm it. A refused copy, including a payload over 100 KB of base64 or an unwritable /dev/tty, shows "Could not copy link to clipboard".

Link picker:

Key Action
Enter Open URL with the default opener
Ctrl-Y Copy URL, or send OSC 52 to the terminal
Ctrl-S Cycle appearance order / alphabetical sort

tmux usage

After the tmux install steps, set @termscope to the absolute path of the termscope script in your clone (not the repo directory).

set -g @termscope "/path/to/termscope/termscope"

bind-key -n C-S-a run-shell "tmux display-popup -E -w 80% -h 60% '#{@termscope} pick --pane-path #{q:pane_current_path} --pane-id #{q:pane_id}'"
bind-key -n C-e run-shell "tmux display-popup -E -w 80% -h 60% '#{@termscope} links --pane-path #{q:pane_current_path} --pane-id #{q:pane_id}'"

bind-key -T copy-mode-vi C-S-a run-shell "tmux display-popup -E -w 80% -h 60% '#{@termscope} pick --pane-path #{q:pane_current_path} --pane-id #{q:pane_id}'"
bind-key -T copy-mode-vi C-e run-shell "tmux display-popup -E -w 80% -h 60% '#{@termscope} links --pane-path #{q:pane_current_path} --pane-id #{q:pane_id}'"

bind-key -T copy-mode-vi 'o' send -F -X copy-pipe-and-cancel "#{@termscope} open --mode nvim --pane-path #{q:pane_current_path} --pane-id #{q:pane_id}"
bind-key -T copy-mode-vi 'O' send -F -X copy-pipe-and-cancel "#{@termscope} open --mode default --pane-path #{q:pane_current_path} --pane-id #{q:pane_id}"
bind-key -T copy-mode-vi P run-shell "tmux display-popup -E -w 80% -h 60% '#{@termscope} pick --pane-path #{q:pane_current_path} --pane-id #{q:pane_id}'"

In tmux copy-mode these bindings preserve the scrolled viewport instead of jumping back to the live bottom of the pane. Reload tmux config after editing (tmux source-file ~/.tmux.conf, or your config path).

The script also accepts --multiplexer tmux|herdr|auto (default auto).

Configuration

When running as a Herdr plugin, Termscope reads settings from config.toml in the plugin config directory, which herdr plugin config-dir termscope prints. If the file is missing, Termscope uses the defaults below.

Setting Values Default Purpose
open_target split, tab, popup split split opens the file beside the source pane; tab opens it in a new tab; popup opens it inside the picker popup, which closes when nvim exits.
close_on_exit true, false false true launches nvim with exec, so the pane closes when nvim exits.
open_target = "tab"
close_on_exit = true
Environment variable Purpose
TERMSCOPE_TV Absolute Television binary. Set by the Herdr wrapper when the installer recorded a path or Homebrew tv exists off PATH.
TERMSCOPE_OPENER Override default opener, e.g. open -a Zen or open -a Firefox
TERMSCOPE_SORT Default sort: appearance (default) or alpha
BAT_THEME bat theme for file previews. Default: ansi, the terminal's own colors, so text stays readable on light and dark themes
TERMSCOPE_LOG JSON event log path. Default: $XDG_CACHE_HOME/termscope/termscope.log (~/.cache/... if unset)
TERMSCOPE_DEBUG_DIR Directory for per-run debug dumps (unset = off)

Examples:

export TERMSCOPE_OPENER='open -a Zen'
export TERMSCOPE_SORT=alpha

Put these in the environment of the Herdr server / tmux session that launches the picker, not only an unrelated interactive shell.

Dry run / debug

scan prints JSON of visible file candidates (no URLs, no Television). It needs a real pane id:

# inside a Herdr pane
./termscope scan --pane-path "$PWD" --pane-id "$HERDR_PANE_ID" --multiplexer herdr

# tmux
./termscope scan --pane-path "$PWD" --pane-id "$(tmux display-message -p '#{pane_id}')" --multiplexer tmux

Enable debug dumps:

export TERMSCOPE_DEBUG_DIR=/tmp/termscope-debug

Each run writes the captured screen, indexed files, candidates, picker result, and final selection decision.

How it works

Herdr plugin actions run without a TTY, so termscope.open first opens an 80% × 60% session-modal popup. The popup inherits the source pane id/cwd and an absolute Television path when Homebrew tv is off the popup PATH. It captures visible text from every pane in the tab with herdr pane read --source visible, scans the repo with fd, and runs Television. Two bundled channels let Ctrl-S cycle between appearance and alphabetical order. File previews use bat when available and a built-in text preview otherwise.

When you choose a file, Termscope opens a split beside the source pane, or a new tab with open_target = "tab", and runs nvim +line path in it. With close_on_exit = true, Termscope launches nvim with exec, so the pane closes when nvim exits. With open_target = "popup", nvim replaces the picker inside its popup, and the popup closes when nvim exits; the pane layout stays as it was. For URLs, it uses the default opener unless TERMSCOPE_OPENER is set.

Project documentation

Development

python3 -m py_compile termscope termscope_herdr.py
python3 -m unittest discover -s tests
herdr plugin link "$PWD"
herdr plugin action invoke termscope.open

There is no package manager. herdr plugin install clones the repo, reads herdr-plugin.toml, and runs scripts/install-dependencies.sh. plugin link does not run that script.

License

MIT © iury souza