finter 0.3.0

A Tmux plugin to quickly create session for folders in configured paths.
Documentation

Finter

finter is a small Rust CLI for tmux users who work across many project folders. It lets you open a popup picker, fuzzy-find a folder, and jump into a matching tmux session (or create it if missing).

screenshot

Install

You need Cargo:

cargo install finter

Quick Start

  1. Configure project roots (absolute paths only):
finter -d /home/username/projects /home/username/work
  1. Add a tmux popup hotkey (default example: Prefix + C-o):
bind C-o display-popup -E "finter"
  1. Trigger the hotkey, fuzzy-select a folder, and finter will switch/create the tmux session.

What It Does

  • Reads configured roots and SSH settings from ~/.finter.toml.
  • Scans immediate child directories of those roots.
  • Lists those folders together with existing tmux session names.
  • Always includes the configured SSH session item (default: ssh_mac_mini).
  • Uses a popup-compatible fuzzy selector (skim).
  • On select:
    • existing session: switch/attach to it
    • missing project session: create detached session in folder, create a second window, stay on window 1, then switch/attach
    • missing SSH session: create one window, auto-run SSH into the remote mac_mini tmux session, then switch/attach

Default ~/.finter.toml (created by finter -d ...):

roots = [
    "/home/username/projects",
    "/home/username/work",
]

[ssh]
session_name = "ssh_mac_mini"
primary = "user@192.168.1.200"
remote_session_name = "mac_mini"

You can also copy the repo template: .finter.toml.example.

SSH details:

  • Connect command is built from ssh.primary.
  • By default, finter runs remote tmux new-session -A -s mac_mini over SSH so it attaches to that session or creates it if missing.
  • Optional fallback is ssh.tailscale in TOML (for example user@macmini.tailnet.ts.net).
  • When ssh.tailscale is set, finter tries LAN first and falls back only if LAN SSH is unreachable.
  • Set ssh.remote_session_name = "" to disable the remote tmux wrapper and use plain SSH instead.
  • Legacy ~/.finter path-list config is no longer read.

Docs