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).

Install

You need Cargo:

cargo install finter

Quick Start

1. Configure project roots (absolute paths only):

finter -d /home/username/projects /home/username/work

2. Add a tmux popup hotkey (default example: Prefix + C-o):

bind C-o display-popup -E "finter"

3. 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 = "[email protected]"
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

• Usage
• Tmux Integration
• Behavior and Architecture
• Troubleshooting