tmuxido/README.md

tmuxido

A Rust-based tool to quickly find and open projects in tmux using fzf. No external dependencies except tmux and fzf!

Features

• Search for git repositories in configurable paths
• Interactive selection using fzf
• Native tmux session creation (no tmuxinator required!)
• Support for project-specific .tmuxido.toml configs
• Smart session switching (reuses existing sessions)
• TOML-based configuration
• Smart caching system for fast subsequent runs
• Configurable cache TTL
• Self-update capability (tmuxido --update)
• Keyboard shortcut setup for Hyprland, GNOME, and KDE (tmuxido --setup-shortcut)
• Zero external dependencies (except tmux and fzf)

Installation

curl -fsSL https://raw.githubusercontent.com/cinco/tmuxido/main/install.sh | sh

Installs the latest release binary to ~/.local/bin/tmuxido. On first run, the config file is created automatically at ~/.config/tmuxido/tmuxido.toml.

Build from source

cargo build --release
cp target/release/tmuxido ~/.local/bin/

Configuration

The configuration file is located at ~/.config/tmuxido/tmuxido.toml.

On first run, a default configuration will be created automatically.

Example configuration:

# List of paths where to search for projects (git repositories)
paths = [
    "~/Projects",
    # "~/work",
]

# Maximum depth to search for .git directories
max_depth = 5

# Enable project caching (default: true)
cache_enabled = true

# Cache TTL in hours (default: 24)
cache_ttl_hours = 24

# Default session configuration (used when project has no .tmuxido.toml)
[default_session]

[[default_session.windows]]
name = "editor"
panes = []

[[default_session.windows]]
name = "terminal"
panes = []

Usage

Run without arguments to search all configured paths and select with fzf:

tmuxido

Or provide a specific directory:

tmuxido /path/to/project

Force refresh the cache (useful after adding new projects):

tmuxido --refresh
# or
tmuxido -r

Check cache status:

tmuxido --cache-status

Update tmuxido to the latest version:

tmuxido --update

Set up a desktop keyboard shortcut (Hyprland, GNOME, KDE):

tmuxido --setup-shortcut

This is also offered automatically on first run. Re-run it any time to reconfigure the shortcut or after switching desktop environments.

View help:

tmuxido --help

Requirements

• tmux - Terminal multiplexer
• fzf - For interactive selection

How it works

1. Searches for git repositories (directories containing .git) in configured paths
2. Caches the results for faster subsequent runs
3. Presents them using fzf for selection
4. Creates or switches to a tmux session for the selected project
5. If a .tmuxido.toml config exists in the project, uses it to set up custom windows and panes
6. Otherwise, uses the default session config from ~/.config/tmuxido/tmuxido.toml (configured interactively on first run)

Caching

The tool uses an incremental cache to keep subsequent runs fast:

• Cache location: ~/.cache/tmuxido/projects.json
• Incremental updates: On each run, only directories whose mtime changed are rescanned — no full rescans
• Manual refresh: Use --refresh to force a full rescan
• Cache status: Use --cache-status to inspect the cache

The cache persists indefinitely and is updated automatically when the filesystem changes.

Project-specific Configuration

You can customize the tmux session layout for individual projects by creating a .tmuxido.toml file in the project root.

Example .tmuxido.toml:

[[windows]]
name = "editor"
panes = ["nvim"]
layout = "main-horizontal"

[[windows]]
name = "server"
panes = ["npm run dev"]

[[windows]]
name = "git"
panes = []

Available Layouts

main-horizontal — Main pane on top, others below

┌──────────────────────┐
│                      │
│       main pane      │
│                      │
├──────────┬───────────┤
│  pane 2  │  pane 3   │
└──────────┴───────────┘

main-vertical — Main pane on left, others on right

┌─────────────┬────────┐
│             │ pane 2 │
│  main pane  ├────────┤
│             │ pane 3 │
│             ├────────┤
│             │ pane 4 │
└─────────────┴────────┘

tiled — All panes tiled equally

┌───────────┬──────────┐
│  pane 1   │  pane 2  │
├───────────┼──────────┤
│  pane 3   │  pane 4  │
└───────────┴──────────┘

even-horizontal — All panes side by side

┌────────┬────────┬────────┐
│        │        │        │
│ pane 1 │ pane 2 │ pane 3 │
│        │        │        │
└────────┴────────┴────────┘

even-vertical — All panes stacked

┌──────────────────────┐
│       pane 1         │
├──────────────────────┤
│       pane 2         │
├──────────────────────┤
│       pane 3         │
└──────────────────────┘

Panes

Each window can have multiple panes with commands that run automatically:

• First pane is the main window pane
• Additional panes are created by splitting
• Empty panes array = just open the window in the project directory

Author

Cinco
@cinco