Lumbergh

What You Get

1. Install & Launch

1. Install the prerequisites

   You just need tmux and git:

   sudo apt install tmux git    # Debian/Ubuntu
   brew install tmux git         # macOS

2. Install Lumbergh

   With uv (recommended):

   uv tool install pylumbergh

   Or with pip:

   pip install pylumbergh

3. Run it

   lumbergh

   Open http://localhost:8420 in your browser. That's it.

2. Using Lumbergh

The Dashboard

The home page shows all your sessions as cards, split into Active and Inactive groups. Each card shows:

• Session status (working, waiting for input, idle, error, stalled)
• What the AI is currently doing — auto-detected from terminal activity
• Agent provider badge (Claude Code, Cursor, Aider, etc.)
• Git info: branch name, worktree indicator, parent repo
• Number of tmux windows and last used timestamp
• Quick actions: edit, reset, or delete the session

Click any card to open the session detail view.

Terminal Tips

Session Detail Tabs

Each session has a left pane (terminal) and a right pane with these tabs:

• Git — interactive commit graph, live diff viewer (unstaged, staged, commit history), and full git operations: commit, amend, push, rebase, cherry-pick, stash, branch management, and more.
• Files — browse the project file tree with syntax-highlighted previews. Select code to send as context to the terminal.
• Todo — per-project task list with drag-to-reorder, descriptions, and a free-form scratchpad for notes.
• Prompts — reusable prompt templates with @mention variables. Share prompts via Lumbergh Cloud or browse community prompts.
• Shared — files shared across sessions for cross-project context.

Quick Input Bar

The input bar at the bottom of the terminal lets you type and send text to the active session. You can choose to send text only (for composing multi-line input) or send with Enter to execute immediately. Switch between tmux windows using the window selector buttons.

Creating Sessions

Click "+ New Session" on the dashboard. There are three modes:

• Existing Repo — point at any existing working directory. Give it a name, pick the directory using the repo finder (searches your configured repo directory), and optionally add a description.
• New Repo — create a fresh project directory with an auto-initialized git repo. Pick a parent directory and name your project.
• Worktree — create a git worktree from an existing repo. Pick the parent repo, choose an existing branch or create a new one, and Lumbergh sets up the worktree automatically. Great for running parallel feature branches.

Lumbergh auto-generates a URL-safe session ID from the name (e.g., "Auth Feature" becomes auth-feature) and creates the tmux session for you.

Create a session by pointing at a repo or creating a git worktree

Prompt Templates

Build a library of reusable prompts to fire at any session with one click. Templates support two scopes:

• Project — templates specific to one session/project.
• Global — available across all sessions. Promote any project template to global with one click.

In edit mode you can reorder templates via drag-and-drop, move between scopes, and delete. Templates persist across restarts.

3. Configuration

Click the gear icon in the top-right corner of the dashboard to open Settings.

General Settings

• Repository search directory — the root path Lumbergh scans to find git repos when creating sessions (defaults to the directory where lumbergh was launched). Set this to wherever you keep your projects.
• Git graph commits — how many commits to load in the graph visualization (10–1000, default 100).
• Default agent — which coding agent new sessions use (Claude Code, Cursor, Aider, Gemini CLI, OpenCode, or Codex). Can be overridden per-session.
• Tab visibility — toggle which tabs (Git, Files, Todos, Prompts, Shared) appear by default. Can also be customized per-session.

General settings: repo search directory and git graph config

AI Provider Setup

Lumbergh uses AI to auto-detect what each session is working on and to generate context-aware commit summaries. Configure an AI provider in the AI tab of Settings. Supported providers:

Pick your AI provider and model — supports Ollama, OpenAI, Anthropic, Google AI, and any OpenAI-compatible endpoint

What the AI does

• Session status — reads terminal output to detect if the AI is working, waiting for input, idle, or in an error state. This powers the status indicators on dashboard cards.
• Activity summaries — generates a short description of what each session is currently doing (e.g., "Fixing actor sync", "Hiding view buttons").
• Commit context — summarizes recent commits using conventional commit format for the diff viewer.

Dark Mode / Light Mode

Toggle between dark and light themes using the sun/moon icon in the top-right corner of the dashboard. Your preference is saved to local storage and persists across sessions. Theme applies to everything including syntax highlighting, diff colors, and the git graph.

Dark and light themes — toggle with one click

Password Authentication

Lumbergh supports optional password protection. When a password is set, all routes require authentication via a login page. There are two ways to set a password:

• LUMBERGH_PASSWORD env var — takes precedence. Set it before launching Lumbergh.
• Security tab in Settings — set or change the password from the dashboard UI.

Sessions use HMAC-signed cookies that last 30 days. Restarting the server invalidates all sessions (signing key is regenerated). If no password is configured, auth is completely disabled.

Lumbergh Cloud

Lumbergh Cloud is an optional companion service that adds cloud features while keeping the app fully functional offline. Connect via the Cloud tab in Settings using a device code flow (no API keys needed).

• Cloud backup — auto-backup your sessions, todos, prompts, and settings on a 5-minute interval. Supports optional AES-256 encryption with a passphrase. Restore from any machine.
• Prompt sharing — share prompt templates via a short code. Recipients can install and get auto-updates when you publish changes.
• Community prompts — browse and install prompts shared by other users.
• Free AI provider — use Lumbergh Cloud as an AI provider for status detection and commit summaries at no cost.

Data Storage

All data lives in ~/.config/lumbergh/:

• sessions.json — session registry (names, workdirs, descriptions)
• session_data/<name>.json — per-session data (todos, scratchpad)
• settings.json — AI provider config, repo search path
• global.json — global prompt templates
• shared/ — shared files accessible from all sessions

No database server needed — it's all flat JSON files via TinyDB.

4. Use From Your Phone

Lumbergh is designed to be used from a phone or tablet. The UI is fully responsive and supports installation as a PWA (Progressive Web App).

Dashboard on mobile

Session detail with live terminal

Secure Remote Access with Tailscale

The recommended way to access Lumbergh from your phone is via Tailscale, which gives you a private, encrypted connection without exposing ports to the internet.

1. Install Tailscale

   Install on both your server and your phone/tablet. It's free for personal use.

2. Connect and browse

   Open http://<your-tailscale-ip>:8420 on your phone. That's it.

3. Install as PWA (optional)

   In your mobile browser, tap "Add to Home Screen" for an app-like experience with no browser chrome.

Troubleshooting

Terminal not connecting?

Make sure tmux mouse mode is on: tmux set -g mouse on. The bootstrap script does this automatically, but if you started manually you may need to set it.

Port already in use?

Lumbergh runs on :8420 by default. Use lumbergh -p 9000 to pick a different port. In dev mode, the backend runs on :8420 and the Vite frontend on :5420.

Dependencies not installing?

Run ./bootstrap.sh again — it will tell you exactly what's missing. For Node issues, make sure nvm is loaded in your shell (source ~/.nvm/nvm.sh).