Metadata-Version: 2.4
Name: pylumbergh
Version: 0.1.1
Summary: A self-hosted web dashboard for supervising multiple Claude Code AI sessions running in tmux
Project-URL: Homepage, https://github.com/voglster/lumbergh
Project-URL: Documentation, https://voglster.github.io/lumbergh/
Project-URL: Repository, https://github.com/voglster/lumbergh
Project-URL: Issues, https://github.com/voglster/lumbergh/issues
Project-URL: Changelog, https://github.com/voglster/lumbergh/releases
Author: James Vogel
License: MIT
Keywords: agent,ai,claude-code,dashboard,devtools,session-manager,supervisor,terminal,tmux
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi
Requires-Dist: gitpython>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: libtmux
Requires-Dist: python-multipart
Requires-Dist: tinydb
Requires-Dist: uvicorn[standard]
Description-Content-Type: text/markdown

# Lumbergh

A self-hosted web dashboard for supervising multiple Claude Code AI sessions running in tmux.

Think "micromanager for your AI interns."

**[Documentation & Screenshots](https://voglster.github.io/lumbergh/)**

![Lumbergh Dashboard](docs/screenshots/dashboard.png)

## Features

- **Multi-session dashboard** — view and manage multiple Claude Code sessions at a glance
- **Terminal streaming** — interact with live terminal sessions via xterm.js + WebSockets
- **Git diff viewer** — monitor live diffs, commit history, and branch switching as the AI works
- **Git graph** — visualize commit history with an interactive graph
- **File browser** — browse project files with syntax highlighting
- **AI chat** — manager AI agent for reviewing and coordinating work
- **Todo lists & scratchpad** — per-project notes and task tracking
- **Prompt templates** — reusable prompts with mention/variable support
- **Shared files** — share context across sessions
- **Settings** — configurable AI providers and preferences
- **Mobile-friendly** — responsive design for phones and tablets
- **PWA support** — installable as a progressive web app

## Quick Start

Install and run with one command:

```bash
uv tool install pylumbergh
lumbergh
```

Or with pip:

```bash
pip install pylumbergh
lumbergh
```

Then open `http://localhost:8420` in your browser.

### Prerequisites

| Tool | Install |
|------|---------|
| **tmux** | `sudo apt install tmux` or `brew install tmux` |
| **git** | `sudo apt install git` or `brew install git` |

That's it. The `lumbergh` command checks for these on startup and tells you what's missing.

### Remote access (phone/tablet)

Lumbergh binds to `0.0.0.0` so it's accessible from other devices on your network. For secure remote access (especially from mobile), we recommend [Tailscale](https://tailscale.com/):

1. Install Tailscale on your server and your phone/tablet
2. Access Lumbergh at `http://<tailscale-ip>:8420`

This gives you a private, encrypted connection without exposing ports to the internet.

## Development

If you want to contribute or hack on Lumbergh itself:

```bash
git clone https://github.com/voglster/lumbergh.git
cd lumbergh
./bootstrap.sh
```

This creates a tmux session with three windows (claude, backend, frontend) and opens `http://localhost:5420` with the Vite dev server. You'll need **uv**, **npm**, and **Claude Code** in addition to the prerequisites above.

## Tech Stack

- **Backend:** Python 3.11+, FastAPI, libtmux, TinyDB
- **Frontend:** React + Vite + TypeScript, xterm.js, TanStack Query, Tailwind CSS

## Project Structure

```
lumbergh/
├── backend/
│   ├── main.py              # FastAPI app entry point
│   ├── tmux_pty.py           # PTY/tmux attachment logic
│   ├── session_manager.py    # PTY pooling for WebSocket clients
│   ├── git_utils.py          # Git operations (diff, log, branches)
│   ├── file_utils.py         # File browsing utilities
│   ├── db_utils.py           # TinyDB persistence helpers
│   ├── diff_cache.py         # Diff caching layer
│   ├── idle_detector.py      # Session idle detection
│   ├── idle_monitor.py       # Idle monitoring service
│   ├── message_buffer.py     # Message buffering for AI context
│   ├── models.py             # Pydantic models
│   ├── constants.py          # Shared constants
│   ├── ai/                   # AI provider integration
│   │   ├── providers.py
│   │   └── prompts.py
│   ├── routers/
│   │   ├── ai.py             # AI chat endpoints
│   │   ├── notes.py          # Todo, scratchpad, prompt template APIs
│   │   ├── sessions.py       # Session management endpoints
│   │   ├── settings.py       # Settings endpoints
│   │   └── shared.py         # Shared files endpoints
│   ├── tests/
│   ├── pyproject.toml
│   └── start.sh
├── frontend/
│   ├── src/
│   │   ├── App.tsx
│   │   ├── pages/
│   │   │   ├── Dashboard.tsx
│   │   │   └── SessionDetail.tsx
│   │   ├── components/
│   │   │   ├── Terminal.tsx
│   │   │   ├── QuickInput.tsx
│   │   │   ├── DiffViewer.tsx
│   │   │   ├── FileBrowser.tsx
│   │   │   ├── TodoList.tsx
│   │   │   ├── Scratchpad.tsx
│   │   │   ├── PromptTemplates.tsx
│   │   │   ├── SessionCard.tsx
│   │   │   ├── CreateSessionModal.tsx
│   │   │   ├── BranchPicker.tsx
│   │   │   ├── SettingsModal.tsx
│   │   │   ├── SharedFiles.tsx
│   │   │   ├── ResizablePanes.tsx
│   │   │   ├── VerticalResizablePanes.tsx
│   │   │   ├── diff/
│   │   │   │   ├── FileList.tsx
│   │   │   │   ├── FileDiff.tsx
│   │   │   │   └── CommitList.tsx
│   │   │   └── graph/
│   │   ├── hooks/
│   │   └── utils/
│   └── start.sh
├── slides/                # Slidev presentation
├── docs/                  # PRD, architecture, roadmap
├── start.sh               # Start both backend + frontend
└── LICENSE
```

## License

MIT
