scry

Warning: Honestly, you really shouldn't use this for anything. It's awful and I've been using it forever and I'm too old to stop. I'm only making it public so that I can clone it from remote sites.

An interactive tmux window manager with session grouping support, providing a user-friendly interface for managing tmux windows and sessions.

Features

• Interactive window listing with multi-column display
• Easy window creation and attachment
• Session group management
• History-based window switching
• Visual indicators for active and recently used windows
• Configurable display parameters
• Window list dump and load functionality

Installation

Prerequisites

• Python 3.8+ (or the version specified in pyproject.toml)
• tmux
• uv (Python package installer and resolver)

Recommended Installation (Virtual Environment using uv)

1. Create a virtual environment:

   uv venv
   source .venv/bin/activate  # On Linux/macOS
   # .venv\Scripts\activate    # On Windows

2. Install scry:

   uv pip install .

   This will install scry and its dependencies into your virtual environment. The scry command will then be available.

Alternative: Using shiv (for a single executable)

If you prefer a single executable file and have shiv installed:

# Ensure dependencies are installed for shiv to package them
# Example using a temporary uv environment:
# uv venv .shiv-build-env
# source .shiv-build-env/bin/activate
# uv pip install rich PyYAML # Install direct dependencies

shiv -o /tmp/scry -c scry . --python "/usr/bin/env python3"

# Deactivate if you used a temporary env for shiv
# deactivate

Note: The shiv process might need adjustments based on how shiv discovers dependencies when a pyproject.toml is present. You might need to explicitly install dependencies into the environment shiv is using or point it to a requirements file generated by uv pip freeze > requirements.txt.

Configuration

Scry can be configured through:

1. Default settings
2. Configuration file (~/.scry.yml)
3. Command-line arguments

Command-line Options

• -m, --minnamelen: Minimum length for displayed window names
• -c, --columns: Number of columns to display windows in
• -s, --session_group: Session group to manage
• -d, --debug: Enable debug logging
• -l, --log-file: Path to the log file
• --dump-file: Path to the window dump file

Configuration File

Create ~/.scry.yml with any of these settings:

minnamelen: 15
n_cols: 4
fmt_overhead: 3
session_group: "main"
debug: false
log_file: "/tmp/scry.log"
dump_file: "~/.scry_windows.yml"

Usage

Basic Commands

• ##: Select window by numerical index
• n <name>: Create new window with specified name
• s: Swap to second most recent window
• u: Update screen
• d: Dump list of active windows
• l: Load windows from dump file
• q: Quit
• ?: Show help

Window Navigation

• Windows are displayed in a multi-column layout
• Recently used windows are highlighted
• Active windows are marked with a #
• Empty command returns to the most recent window

Development

1. Clone the repository:

   git clone <repository-url>
   cd scry

2. Create and activate a virtual environment:

   uv venv
   source .venv/bin/activate

3. Install in editable mode:

   uv pip install -e .

Code Style

The project uses:

• Black for code formatting (uv run black .)
• Ruff for linting and import sorting (uv run ruff check . --fix and uv run ruff format .)

Consider adding black and ruff to your [project.optional-dependencies] in pyproject.toml under a dev group.

Project Structure

• scry/
  • __main__.py: Entry point
  • scry.py: Core functionality
  • tmuxcmd.py: tmux command interface
  • bin_utils.py: Binary path utilities
• pyproject.toml: Project metadata and dependencies for uv.
• README.md: This file.

License

BSD 3-Clause License

Author

David Ressman (davidr@ressman.org)