Installation Guide

Core Window Manager

• i3 window manager with status bar and lock screen
• Alacritty terminal emulator
• i3status for status bar
• dmenu application launcher
• picom compositor for transparency and effects

Fonts

• JetBrains Mono (coding font)
• Font Awesome (icon font)

Development Tools

• Ranger file manager with preview support
• lazydocker for Docker container monitoring
• btop and htop for system monitoring

Applications

• Google Chrome browser
• Cursor IDE (AppImage with desktop integration)
• Claude Code CLI (native installer)

MCP Integration

• i3-mcp Python server for Claude Code integration
• Python 3 environment configuration

System Utilities

• Screenshot tools (maim, slop, xclip)
• System tray apps (network-manager, dunst, blueman)

Project Directory

If your project is not located at ~/Documents/code/railroad, set the environment variable:

# Add to ~/.bashrc or ~/.profile
export RAILROAD_PROJECT_DIR="$HOME/path/to/your/project"

Select i3 Window Manager

After installation, log out and select i3 from the login screen:

1. Click the gear icon on the login screen
2. Select "i3" from the session list
3. Log in

Session Replay

On login, the autostart script replays your previous session from ~/.config/railroad/current-session. If no session file exists, it defaults to your configured project directory with all 5 terminal slots.

Key Bindings

Starting a Development Session

1. Press Mod+Shift+s to launch the multi-project picker
   • Select a git repository from ~/Documents/code/
   • Choose how many terminals (1-5) to allocate for that project
   • Optionally add more projects until all 5 slots are filled
   • Press Escape after selecting at least one project to launch
2. Each Claude terminal displays a title bar: <project>[<branch>] #N
3. Use Mod+F1 through Mod+F5 to jump between terminals
4. Terminals tile proportionally — adding or removing terminals resizes others automatically

To add more terminals without restarting the session, press Mod+Ctrl+a.

Status Bar

The i3 status bar displays system information on the left:

• Claude Code usage: Shows 5-hour and 7-day utilization percentages plus time until reset. Displayed in gold to match the overall accent theme.
• GPU: Shows utilization percentage and VRAM (used/total in GB). Omitted if no NVIDIA GPU detected.

Git branch information appears in each terminal's title bar rather than the status bar, since terminals may span multiple repositories.

i3 doesn't start

# Check i3 config syntax
i3 -C

# View logs
cat ~/.xsession-errors

No status bar showing

Ensure i3status is installed and the wrapper script is executable:

chmod +x ~/.local/bin/i3status-wrapper.sh

Claude Code MCP server not loading

Restart Claude Code after installation. Check your configuration:

cat ~/.claude.json

Fonts look wrong

Regenerate the font cache:

fc-cache -fv

Audio keys don't work

Install PulseAudio utilities:

sudo apt install -y pulseaudio-utils