[](https://drone.cincoeuzebio.com/cinco/Tmuxido)
[](https://drone.cincoeuzebio.com/cinco/Tmuxido)
[](https://git.cincoeuzebio.com/cinco/Tmuxido/releases)
# 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 with live `README.md` preview (rendered via `glow` when available)
- 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
```sh
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
```bash
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:
```toml
# 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:
```bash
tmuxido
```
Or provide a specific directory:
```bash
tmuxido /path/to/project
```
Force refresh the cache (useful after adding new projects):
```bash
tmuxido --refresh
# or
tmuxido -r
```
Check cache status:
```bash
tmuxido --cache-status
```
Update tmuxido to the latest version:
```bash
tmuxido --update
```
Set up a desktop keyboard shortcut (Hyprland, GNOME, KDE):
```bash
tmuxido --setup-shortcut
```
Install the `.desktop` entry and icon (so tmuxido appears in app launchers like Walker/Rofi):
```bash
tmuxido --setup-desktop-shortcut
```
Both are also offered automatically on first run. Re-run them any time to reconfigure.
View help:
```bash
tmuxido --help
```
## Requirements
- [tmux](https://github.com/tmux/tmux) - Terminal multiplexer
- [fzf](https://github.com/junegunn/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`:
```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
