iurysza/termscope
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.
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 ToolsREADME.md
Originaltermscope

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:linetargets - 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.
python33.11+ (the plugin and shebang callpython3, notpython)fdas thefdbinary. Debian/Ubuntuapt install fd-findshipsfdfind; symlink it tofd(a shell alias is not enough).nvimfor the default file-open action- a URL/default-app opener:
openon macOS,xdg-openon Linux,wslviewon WSL
Host — pick one:
- Herdr
>= 0.7.4for the plugin - tmux for the standalone
termscopescript
Picker UI:
- Television
>= 0.15(tv).herdr plugin installand./scripts/install-dependencies.shinstall or upgrade it through Homebrew when needed. Herdr popups often omit Homebrew fromPATH; Termscope records the absolutetvpath at install and also looks in/opt/homebrew/binand/usr/local/bin. - Homebrew only if
tvis missing or older than0.15. The installer never installs Homebrew; without it, and without a new enoughtv, install aborts before the plugin is registered. batoptional 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:
- exits 0 if
tvalready reports Television 0.15+ - otherwise
brew install/brew upgradethetelevisionformula - writes the absolute
tvpath to$XDG_CONFIG_HOME/termscope/television.path(~/.config/termscope/television.pathwhenXDG_CONFIG_HOMEis unset) - exits 1 (plugin not registered) if Homebrew is missing or
tvis 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:lineis kept and passed to Neovim asnvim +line path. - Only text that looks like a path counts. Plain words don't match files:
reportin a sentence doesn't listreport.md. Write`README`in backticks, or on its own line, to matchREADME.md. - A bare file name such as
main.py:12matches only when exactly one file of that name exists in the repo. - Mentioning
docs/setup/guide.mdlists 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
$HOMEis skipped. termscope.open-linksis 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