Metadata-Version: 2.4
Name: railmux
Version: 0.1.0
Summary: Terminal UI to navigate, resume, and start Claude Code sessions across all your projects
Author-email: Rightglow <zhang.taian@foxmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Rightglow/Railmux
Project-URL: Repository, https://github.com/Rightglow/Railmux
Project-URL: Issues, https://github.com/Rightglow/Railmux/issues
Keywords: claude,claude-code,tmux,tui,session-manager,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urwid>=2.6.16
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# railmux — Claude Code session manager

A terminal UI to navigate, resume, and start [Claude Code](https://claude.com/claude-code) sessions across all your projects from one place. railmux lives in the left pane of a tmux window; the right pane shows the currently-active claude. Each claude session runs as its own detached tmux session in the background, so switching between sessions preserves all in-progress work — no responses or tool calls are interrupted.

> **This is a fork** of [regmi-saugat/railmux](https://github.com/regmi-saugat/railmux) (v0.1.5), developed with agent-assisted programming using [Claude Code](https://claude.ai/claude-code).

## Install

```bash
pip install railmux
```

Requires Python 3.12+, `tmux`, and `less` on `PATH`.

## Run

```bash
railmux
```

If you're not already inside a tmux session, railmux will launch one automatically. The most recent project is auto-selected on startup.

## Keys

### Navigation

| Key | Action |
|-----|--------|
| `↑` / `↓` | Move selection within the focused pane |
| `Tab` / `Shift-Tab` | Cycle focus through Projects, Sessions, Running panes |
| `Esc` | Move focus up: Running → Sessions → Projects |
| `/` | Filter the focused pane by name |

### Session actions

| Key | Action |
|-----|--------|
| `Enter` | Resume or start the selected session |
| `n` | Start a fresh claude session in the current project |
| `i` | Popup with session details |
| `r` | Rename the focused session |
| `s` | Toggle star — starred sessions pinned to top with ⭐ |
| `k` | Kill the running Claude process (keeps session file) |
| `d` | Delete the focused session (prompts for confirmation) |
| `t` | Open a terminal in the active project directory |
| `F9` | Fullscreen the agent pane (toggle) for clean text selection |
| `?` | Full help popup with all keybindings |
| `q` or `Ctrl-C` | Quit with confirmation |

### Mouse

| Action | Effect |
|--------|--------|
| Left-click (non-running) | Preview session history in the right pane |
| Left-click (running) | Attach to the running session (focus stays left) |
| Double-click | Open/attach and move focus to the right pane |
| Right-click | Context menu (Open, Info, Rename, Star, Kill, Term, Delete) |

## History preview

Left-click a non-running session to view its conversation history in the right pane without starting Claude. The transcript is colour-coded (user = cyan, assistant = green, tool use = yellow) and displayed via `less`. Press `q` to exit — the right pane restores whatever was there before. Double-click to skip the preview and open the session directly.

Clicking a running session attaches to it immediately (focus stays left so you can keep browsing). Double-clicking steals focus to the right pane for both running and non-running sessions.

## Status indicators

Each session shows a coloured ● reflecting its current state:

- **Green** — idle (assistant last responded normally)
- **Yellow** — busy (assistant is processing)
- **Red** — blocked (waiting for tool approval)

## How it works

`railmux` reads `~/.claude/projects/*` (Claude's per-project session history) and lists everything. Pressing `Enter` on a session does two things: (1) if a detached tmux session running `claude --resume <id>` doesn't already exist, railmux creates one with `tmux new-session -d`; (2) railmux's right pane runs `tmux attach -t cc-<id>` so you see and interact with that claude. Switching sessions just respawns the right pane to attach to a different background tmux session — the detached claudes keep running with all their state intact.

## SSH / remote use

railmux works over SSH and benefits from a few tweaks for responsiveness and scrollback:

**Server** (`~/.tmux.conf` on the remote machine):

```tmux
set -sg escape-time 0         # eliminate delay after Escape key
set -g  history-limit 10000   # generous scrollback per pane
```

**Client** (`~/.ssh/config` on your local machine):

```
Host your-server
    Compression yes           # smoother tmux pane scrolling over SSH
```

## Copying text from the Claude pane

Selecting text is awkward under tmux: the sidebar and Claude share the screen,
and over SSH your clipboard lives on the *local* machine.

- **OSC 52** (iTerm2, kitty, WezTerm, Alacritty, foot, Windows Terminal):
  drag-select in the Claude pane — copies to local clipboard automatically,
  even over SSH. No Shift needed. (iTerm2: enable *Settings → General →
  Selection → "Applications in terminal may access clipboard"*.)
- **Without OSC 52** (Terminal.app, etc.): **F9** to fullscreen the agent →
  **Shift-drag** to select → `Cmd/C` to copy → **F9** to return.
`Ctrl-B z` also toggles fullscreen (built into tmux) but zooms whichever pane
has focus, so it may fullscreen the sidebar instead.

## Configuration

Optional config at `~/.config/railmux/config.toml`:

```toml
[claude]
# Path to the claude binary (default: "claude")
binary = "claude"

[live]
# How often to refresh the session list (ms)
poll_interval_ms = 1000
```
