tx

Modular CLI for isolated dev environments using git worktrees. Manage dev servers, SSH tunnels, worktrees, and code editors from a single tool.

Installation

npm install -g @alexcrondon/tx

Or run without installing:

npx @alexcrondon/tx

Requirements

• POSIX shell (sh)
• Git (for worktrees)
• Optional: ngrok (for tx tunnel), tmux (for tx code -t)

Quick Start

# Show status of servers, tunnel, db, worktrees
tx

# Create a worktree and launch your editor
tx code -b fix/my-bug

# Start dev server
tx serv start

Commands

| Command | Default | Description | |---------|---------|-------------| | tx / tx status | — | Show status of servers, tunnel, db, worktrees | | tx config | — | Manage config (user + project) | | tx serv | list | Dev servers: list, start, stop, restart | | tx tunnel | status | SSH tunnel (ngrok) | | tx db | status | Background db process (port-forward, etc.) | | tx wt | list | Git worktrees: add, remove, clean | | tx code | start | Launch editor/agent in worktree | | tx nuke | — | Stop everything, remove all worktrees | | tx --version | — | Show version number |

Run tx help or tx help <command> for details.

Configuration

Config uses two files; the tool writes each key to the appropriate one:

| Scope | File | Keys | |-------|------|------| | User | ~/.txrc | code, tunnel, db, auto_open, auto_tmux, auto_start | | Project | .txrc | port, start, url, branch, copy, worktrees_dir, install |

tx config                      # Show current config (with scope per key)
tx config init                 # Interactive setup (writes to appropriate file)
tx config code cursor          # Set user preference → ~/.txrc
tx config start "npm start"    # Set project config → .txrc
tx config start --unset        # Revert key to its default value
tx config reset               # Delete project .txrc
tx config reset user           # Delete ~/.txrc

| Key | Scope | Default | Description | |-----|-------|---------|-------------| | port | project | 9001 | Starting port for servers | | start | project | yarn start | Default server command | | url | project | http://localhost:{PORT} | URL template | | branch | project | (auto-detected) | Default branch for worktrees | | copy | project | (empty) | Files to copy into new worktrees | | worktrees_dir | project | .worktrees | Worktree directory | | install | project | yarn install | Install command for new worktrees | | code | user | claude | Command to run for tx code | | tunnel | user | ngrok tcp 22 | Tunnel command | | db | user | (empty) | Background db command | | auto_open | user | false | Open browser after serv start | | auto_tmux | user | false | Auto-launch tx code in tmux | | auto_start | user | false | Auto-start dev server with tx code |

Examples

# Status overview (default when no command)
tx

# Dev servers
tx serv                     # List running servers
tx serv start -o -p 3000    # Start on 3000, open browser
tx serv stop all            # Stop all

# Worktrees
tx wt add -n hotfix         # Create worktree "hotfix"
tx wt add -b fix/my-bug     # Create worktree fix-my-bug on branch fix/my-bug

# Code editor (creates worktree by default)
tx code -b fix/my-bug       # Worktree "fix-my-bug" on branch fix/my-bug
tx code -s -b fix/my-bug    # Same, plus install deps and start dev server
tx code -r                  # Run in repo root instead
tx code -t                  # Launch in tmux session
tx code attach hotfix       # Reattach to tmux

# Tunnel
tx tunnel start -c          # Start ngrok, caffeinate to prevent sleep

# Nuclear option
tx nuke                     # Stop all, remove worktrees (with confirmation)

Shell completions

# zsh
eval "$(tx completions)"
# or add to ~/.zshrc

License

MIT