railmux 0.1.0__tar.gz

railmux-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saugat Regmi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

railmux-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+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
+```

railmux-0.1.0/README.md

@@ -0,0 +1,121 @@
+# 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
+```

railmux-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "railmux"
+dynamic = ["version"]
+description = "Terminal UI to navigate, resume, and start Claude Code sessions across all your projects"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  {name = "Rightglow", email = "zhang.taian@foxmail.com"},
+]
+keywords = ["claude", "claude-code", "tmux", "tui", "session-manager", "terminal"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console :: Curses",
+  "Intended Audience :: Developers",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+  "Topic :: Terminals",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "urwid>=2.6.16",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "build>=1.2",
+  "twine>=5.0",
+]
+
+[project.scripts]
+railmux = "railmux.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Rightglow/Railmux"
+Repository = "https://github.com/Rightglow/Railmux"
+Issues = "https://github.com/Rightglow/Railmux/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "railmux.__version__"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

railmux-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

railmux-0.1.0/src/railmux/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

railmux-0.1.0/src/railmux/__main__.py

@@ -0,0 +1,4 @@
+from railmux.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

railmux-0.1.0/src/railmux/atomic_file.py

@@ -0,0 +1,38 @@
+"""Small atomic-file helpers for railmux-owned state."""
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(
+    path: Path,
+    text: str,
+    *,
+    encoding: str = "utf-8",
+) -> None:
+    """Replace *path* atomically after writing *text* beside it."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, raw_tmp = tempfile.mkstemp(
+        prefix=f".{path.name}.",
+        dir=path.parent,
+    )
+    tmp = Path(raw_tmp)
+    stream = None
+    try:
+        stream = os.fdopen(fd, "w", encoding=encoding)
+        fd = -1
+        with stream:
+            stream.write(text)
+        stream = None
+        os.replace(tmp, path)
+    finally:
+        if stream is not None:
+            stream.close()
+        if fd >= 0:
+            os.close(fd)
+        try:
+            tmp.unlink()
+        except OSError:
+            pass

railmux-0.1.0/src/railmux/cli.py

@@ -0,0 +1,78 @@
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from railmux import __version__
+from railmux.config import load_config
+from railmux import tmux_ctl
+
+
+def is_ssh_session(environ: dict[str, str] | None = None) -> bool:
+    """Best-effort detection of a process reached through an SSH transport.
+
+    OpenSSH exports all three variables below. tmux normally refreshes
+    ``SSH_CONNECTION`` when a client attaches, so this also works when railmux is
+    launched from an existing tmux session. Explicit CLI flags remain available
+    for terminals or gateways that strip these variables.
+    """
+    env = os.environ if environ is None else environ
+    return any(env.get(name) for name in ("SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="railmux", description="Claude Code session manager TUI")
+    parser.add_argument("--version", action="version", version=f"railmux {__version__}")
+    parser.add_argument("--project", help="Launch focused on a single project path")
+    parser.add_argument("--claude-home", default=str(Path.home() / ".claude"), help="Override ~/.claude location (testing)")
+    parser.add_argument("--inside-tmux", action="store_true", help="Internal: skip the auto-tmux-launch step")
+    scroll_group = parser.add_mutually_exclusive_group()
+    scroll_group.add_argument(
+        "--scroll-coalescing",
+        dest="scroll_coalescing",
+        action="store_true",
+        default=None,
+        help="Force-enable tmux copy-mode wheel event coalescing",
+    )
+    scroll_group.add_argument(
+        "--no-scroll-coalescing",
+        dest="scroll_coalescing",
+        action="store_false",
+        help="Force-disable tmux copy-mode wheel event coalescing",
+    )
+    args = parser.parse_args(argv)
+
+    # If we're not in tmux and not told we're already inside, re-exec ourselves under tmux.
+    if not args.inside_tmux and not tmux_ctl.in_tmux():
+        if not tmux_ctl.has_tmux():
+            print("error: tmux is required but not found on PATH. Install tmux to use railmux.", file=sys.stderr)
+            return 2
+        # Find this railmux binary to re-exec.
+        railmux_path = sys.argv[0]
+        cmd = ["tmux", "new-session", "-A", "-s", "railmux",
+               railmux_path, "--inside-tmux"]
+        # If extra args were passed, forward them.
+        for a in sys.argv[1:]:
+            cmd.append(a)
+        os.execvp("tmux", cmd)
+        # unreachable
+
+    # Inside tmux now.
+    config = load_config()
+    # Lazy import so non-TUI invocations (--version etc) don't pull urwid.
+    from railmux.ui.app import App
+    app = App(
+        claude_home=Path(args.claude_home),
+        config=config,
+        auto_launched=args.inside_tmux,
+        scroll_coalescing=(
+            is_ssh_session() if args.scroll_coalescing is None
+            else args.scroll_coalescing
+        ),
+    )
+    app.run()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())