muxx

Minimal tmux session automation CLI.

Goal

A focused, dependency-light CLI for managing tmux sessions from the terminal. No TUI, no plugins, no telemetry — just a clean interface over tmux commands.

MVP Scope

• List active tmux sessions
• Attach to a session by name or default to the most recent
• Kill a session by name
• Print the currently attached session

Commands

| Command | Alias | Description | |---|---|---| | muxx | | Connect to a session in the current directory | | muxx connect [dir] [--name <n>] [--no-attach] [--cmd "<cmd>"] | c | Connect to or create a tmux session | | muxx list [--json] | ls | List all tmux sessions | | muxx kill <name> [--force] | k | Kill a session by name | | muxx current | cur | Print the current session name | | muxx completion <bash\|zsh\|fish> | | Print shell completion script |

Shell Completion

muxx can print completion scripts for bash, zsh, and fish.

bash

Add to ~/.bashrc:

eval "$(muxx completion bash)"

zsh

Add to ~/.zshrc (after compinit):

eval "$(muxx completion zsh)"

Or write to a file in your $fpath for faster startup (run once):

muxx completion zsh > "${fpath[1]}/_muxx"

Note: The eval line must appear after compinit in your ~/.zshrc. If you use a framework like Oh My Zsh or Prezto, compinit is called for you — just add the eval line after the framework is loaded.

fish

Run once to install:

muxx completion fish > ~/.config/fish/completions/muxx.fish

Requirements

• Node.js 18+
• tmux installed on the system

Installation

npm install -g @harshsandhu44/muxx

Development

npm install
npm run dev -- list        # run via tsx (no build needed)
npm run build              # compile to dist/
npm run typecheck          # type-check without emitting
npm run clean              # remove dist/

Config

Optional config file at ~/.config/muxx/config.json. Defines named projects so you can run muxx connect <name> without typing the full path.

{
  "projects": {
    "vitaq": { "cwd": "~/Code/vitaq" },
    "muxx": { "cwd": "~/Code/personal/muxx" }
  }
}

If the target matches a project key, its cwd is used. Otherwise the target is treated as a directory path.

Installation (from source)

npm run build
npm link

Releases

Releases are fully automated via semantic-release on every push to main.

How it works

1. Every push to main runs typecheck, tests, and build.
2. If all pass, semantic-release analyzes commits since the last release.
3. If releasable commits exist, it bumps the version, publishes to npm, and creates a GitHub release.

Commit convention

This project uses Conventional Commits. Only certain commit types trigger a release:

| Commit type | Release type | |---|---| | fix: | patch (e.g. 0.1.0 → 0.1.1) | | feat: | minor (e.g. 0.1.0 → 0.2.0) | | BREAKING CHANGE: in footer | major (e.g. 0.1.0 → 1.0.0) |

Types like chore:, docs:, test:, refactor: do not trigger a release.

Required GitHub secrets

| Secret | Description | |---|---| | NPM_TOKEN | npm access token with publish rights (create at npmjs.com → Access Tokens) | | GITHUB_TOKEN | Automatically provided by GitHub Actions — no setup needed |

Smoke test (pre-publish verification)

# 1. Build and pack (produces muxx-<version>.tgz)
npm run build
npm pack

# 2. Install the tarball globally
npm install -g ./muxx-*.tgz

# 3. Verify the binary runs
muxx --help
muxx list

# 4. Uninstall when done
npm uninstall -g muxx