vigil-tui 0.1.0

TUI mission control for tmux worktree sessions

vigil

TUI mission control for tmux worktree sessions. Monitors session status, git changes, and PR state from a single dashboard.

Prerequisites

• Python 3.10+
• tmux
• git
• gh (GitHub CLI, authenticated)

Installation

From PyPI

pipx install vigil-tui

Or with pip:

pip install vigil-tui

From source

git clone https://github.com/joshuazd/vigil.git
cd vigil
./vigil

The ./vigil bootstrap script auto-creates a venv and installs dependencies.

Keybindings

Key	Action
q	Quit
j / k	Navigate down / up
Enter	Switch to session (popup mode) or toggle detail
Tab	Toggle detail panel
o	Open PR in browser
m	Merge PR (press twice to confirm)
a	Approve PR
x	Cleanup session (press twice to confirm)
d	Dispatch (run configured hook with input)
b	Rebase and force-push
r	Refresh
Esc	Cancel

Configuration

Config file

~/.config/vigil/config.toml — optional TOML config for hooks and future settings.

[settings]
git_interval = 3       # Git polling interval (seconds)
pr_interval = 30       # PR polling interval (seconds)
cache_ttl = 30         # Cache staleness threshold (seconds)
log_level = "INFO"     # DEBUG, INFO, WARNING, ERROR
git_workers = 8        # Max parallel git status threads

[hooks]
cleanup = "tmux kill-session -t {session} && git worktree remove {path}"
dispatch = "my-dispatch-script {input}"
merge = "gh pr merge {branch} --squash --delete-branch"
approve = "gh pr review {branch} --approve"

Hooks

Actions can be customized via shell command templates with {placeholder} variables:

Hook	Variables	Default
cleanup	{session}, {path}, {branch}, {git_root}	Built-in: kill tmux session + remove worktree
dispatch	{input}	(none — must be configured)
merge	{branch}, {git_root}	gh pr merge {branch} --squash --delete-branch
approve	{branch}, {git_root}	gh pr review {branch} --approve

Variables are automatically shell-escaped. Set a hook to "" to disable it.

The default merge hook uses --squash --delete-branch. Override [hooks] merge for a different strategy.

Environment variable overrides

Environment variables override TOML settings for quick testing or per-machine config:

VIGIL_GIT_INTERVAL, VIGIL_PR_INTERVAL, VIGIL_CACHE_TTL, VIGIL_LOG_LEVEL, VIGIL_GIT_WORKERS

Logs are written to ~/.local/share/vigil/vigil.log (rotating, 2 MB max).

Development

pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/
mypy src/

Architecture

See CLAUDE.md for module-level documentation.

License

GPL-3.0