gitpulse-tui 1.2.7__tar.gz → 1.2.9__tar.gz

{gitpulse_tui-1.2.7/gitpulse_tui.egg-info → gitpulse_tui-1.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitpulse-tui
-Version: 1.2.7
+Version: 1.2.9
 Summary: Git Repo Dashboard TUI — live status, commits, diffs, and branches in your terminal
 Requires-Python: >=3.10
 License-File: LICENSE

{gitpulse_tui-1.2.7 → gitpulse_tui-1.2.9}/README.md

@@ -4,8 +4,25 @@ A developer-focused terminal dashboard that scans a root directory for all local
 
 Built with **Python**, **Textual**, **Rich**, and **GitPython**.
 
+## Why GitPulse?
+
+A lot of development happens late at night, and not everyone commits or pushes
+their changes right away. With "vibe coding" becoming so popular, many people
+now juggle several projects at once — and that makes it genuinely hard to keep
+track of every local repository.
+
+GitPulse exists to solve exactly that. It gives you a single dashboard for all
+your local repos, so at a glance you can see what's committed but not yet
+pushed, what's changed but not yet committed, the number of modified files, the
+current branch, the last commit, and everything else about the state of each
+local Git repository.
+
 ## Screenshots
 
+**Demo** — GitPulse in action
+
+![GitPulse demo](ss/gitpulse.gif)
+
 **📋 Status tab** — repo summary panel, staged/unstaged/untracked file lists, stash entries
 
 ![Status tab](ss/status.png)
@@ -30,9 +47,10 @@ launcher — it bootstraps an isolated Python environment and runs the same
 Python application (no logic is duplicated):
 
 ```bash
-npm install -g gitpulse
+npm install -g gitpulse-tui
 ```
 
+The CLI command is still `gitpulse` once installed.
 This requires Python 3.10+ on your system; the wrapper handles the rest.
 See [npm/README.md](./npm/README.md) for details and troubleshooting.
 

{gitpulse_tui-1.2.7 → gitpulse_tui-1.2.9}/gitpulse/git_ops.py

@@ -725,8 +725,8 @@ def get_file_tree(path: Path) -> "rich.tree.Tree":
     # Render the dict structure into a Rich Tree
     repo_name = path.name
     rich_tree = RichTree(
-        f"[bold #ff2d4a]📁 {repo_name}[/]",
-        guide_style="#2a2a3a",
+        f"[bold #8b5cf6]{repo_name}[/]",
+        guide_style="#1f2937",
     )
 
     def build_tree(node: "RichTree", d: dict) -> None:
@@ -735,22 +735,22 @@ def get_file_tree(path: Path) -> "rich.tree.Tree":
         files = sorted(k for k, v in d.items() if v is None)
 
         for name in dirs:
-            branch = node.add(f"[bold #e040fb]📂 {name}[/]")
+            branch = node.add(f"[bold #8b5cf6]{name}/[/]")
             build_tree(branch, d[name])
 
         for name in files:
             # Color-code by extension
             ext = name.rsplit(".", 1)[-1].lower() if "." in name else ""
             if ext in ("py", "js", "ts", "go", "rs", "c", "cpp", "java"):
-                label = f"[#3ddc84]  {name}[/]"
+                label = f"[#22c55e]{name}[/]"
             elif ext in ("md", "rst", "txt"):
-                label = f"[#ffb74d]  {name}[/]"
+                label = f"[#f59e0b]{name}[/]"
             elif ext in ("json", "yaml", "yml", "toml", "ini", "cfg", "env"):
-                label = f"[#4dd0e1]  {name}[/]"
+                label = f"[#8b5cf6]{name}[/]"
             elif ext in ("sh", "bash", "zsh"):
-                label = f"[#ff5252]  {name}[/]"
+                label = f"[#ef4444]{name}[/]"
             else:
-                label = f"[#d4d4dc]  {name}[/]"
+                label = f"[#d1d5db]{name}[/]"
             node.add(label)
 
     build_tree(rich_tree, root_dict)

{gitpulse_tui-1.2.7 → gitpulse_tui-1.2.9}/gitpulse/main.py

@@ -16,7 +16,7 @@ from pathlib import Path
 
 from textual.app import App, ComposeResult
 from textual.binding import Binding
-from textual.widgets import Header, Footer, Input
+from textual.widgets import Footer, Input
 from textual.containers import Horizontal, Vertical
 from textual.worker import Worker, WorkerState
 
@@ -27,6 +27,8 @@ try:
     from gitpulse.git_ops import get_repo_info, switch_branch, RepoInfo
     from gitpulse.ui.sidebar import RepoSidebar
     from gitpulse.ui.tabs import MainPanel
+    from gitpulse.ui.header import AppHeader, TAB_IDS
+    from gitpulse.ui.help_modal import HelpModal
     from gitpulse.ui.fleet_status import FleetStatus
     from gitpulse.ui.digest_screen import DigestScreen
     from gitpulse.ui.command_palette import CommandPaletteModal
@@ -44,6 +46,8 @@ except ImportError:
     from git_ops import get_repo_info, switch_branch, RepoInfo  # type: ignore[no-redef]
     from ui.sidebar import RepoSidebar  # type: ignore[no-redef]
     from ui.tabs import MainPanel  # type: ignore[no-redef]
+    from ui.header import AppHeader, TAB_IDS  # type: ignore[no-redef]
+    from ui.help_modal import HelpModal  # type: ignore[no-redef]
     from ui.fleet_status import FleetStatus  # type: ignore[no-redef]
     from ui.digest_screen import DigestScreen  # type: ignore[no-redef]
     from ui.command_palette import CommandPaletteModal  # type: ignore[no-redef]
@@ -79,6 +83,9 @@ class GitPulseApp(App):
         Binding("escape", "clear_search", "Clear", show=False),
         Binding("tab", "focus_next", "Next", show=False),
         Binding("shift+tab", "focus_previous", "Prev", show=False),
+        Binding("right_square_bracket", "next_tab", "Next Tab", show=False),
+        Binding("left_square_bracket", "prev_tab", "Prev Tab", show=False),
+        Binding("question_mark", "open_help", "Help", show=True),
     ]
 
     def __init__(
@@ -105,7 +112,7 @@ class GitPulseApp(App):
     # -----------------------------------------------------------------
 
     def compose(self) -> ComposeResult:
-        yield Header()
+        yield AppHeader(id="app-header")
         with Horizontal(id="app-grid"):
             with Vertical(id="sidebar-column"):
                 yield FleetStatus(id="fleet-status")
@@ -250,6 +257,38 @@ class GitPulseApp(App):
         sidebar: RepoSidebar = self.query_one("#sidebar-container", RepoSidebar)
         sidebar.focus_search()
 
+    def action_next_tab(self) -> None:
+        """Switch to the next content tab (bound to ']')."""
+        self._cycle_tab(1)
+
+    def action_prev_tab(self) -> None:
+        """Switch to the previous content tab (bound to '[')."""
+        self._cycle_tab(-1)
+
+    def _cycle_tab(self, delta: int) -> None:
+        main: MainPanel = self.query_one("#main-panel", MainPanel)
+        current = main._active_tab()
+        try:
+            idx = TAB_IDS.index(current)
+        except ValueError:
+            idx = 0
+        self._switch_tab(TAB_IDS[(idx + delta) % len(TAB_IDS)])
+
+    def _switch_tab(self, tab_id: str) -> None:
+        """Switch the active content tab and sync the header highlight."""
+        header: AppHeader = self.query_one("#app-header", AppHeader)
+        header.set_active(tab_id)
+        main: MainPanel = self.query_one("#main-panel", MainPanel)
+        main.show_tab(tab_id)
+
+    def on_app_header_tab_changed(self, message: AppHeader.TabChanged) -> None:
+        """User clicked a tab in the header."""
+        self._switch_tab(message.tab_id)
+
+    def action_open_help(self) -> None:
+        """Show the keyboard-shortcut cheat sheet (bound to '?')."""
+        self.push_screen(HelpModal())
+
     def action_clear_search(self) -> None:
         """Clear search and refocus repo list."""
         inp = self.query_one("#search-input", Input)

{gitpulse_tui-1.2.7 → gitpulse_tui-1.2.9}/gitpulse/ui/bulk_results.py

@@ -30,14 +30,14 @@ class BulkResultsScreen(ModalScreen):
     #results-frame {
         width: 88%;
         height: 75%;
-        background: #1a1a24;
-        border: thick #e040fb;
+        background: #111827;
+        border: solid #8b5cf6;
     }
     #results-title {
         dock: top;
         height: 1;
-        background: #242430;
-        color: #e040fb;
+        background: #1f2937;
+        color: #8b5cf6;
         text-style: bold;
         padding: 0 1;
     }
@@ -48,10 +48,10 @@ class BulkResultsScreen(ModalScreen):
     #results-footer {
         dock: bottom;
         height: 1;
-        background: #1a1a24;
-        color: #555568;
+        background: #111827;
+        color: #6b7280;
         padding: 0 1;
-        border-top: solid #2a2a3a;
+        border-top: solid #1f2937;
     }
     """
 
@@ -87,13 +87,13 @@ class BulkResultsScreen(ModalScreen):
         self._completed += 1
 
         if isinstance(result, Exception):
-            status = "[bold #ff5252]ERROR[/]"
+            status = "[bold #ef4444]ERROR[/]"
             output = str(result)[:80]
         elif isinstance(result, str) and result.lower().startswith("error"):
-            status = "[bold #ff5252]FAIL[/]"
+            status = "[bold #ef4444]FAIL[/]"
             output = result[:80]
         else:
-            status = "[bold #3ddc84]OK[/]"
+            status = "[bold #22c55e]OK[/]"
             output = (str(result) if result else "done")[:80]
 
         table.add_row(repo.name, status, output)

{gitpulse_tui-1.2.7 → gitpulse_tui-1.2.9}/gitpulse/ui/command_palette.py

@@ -39,19 +39,19 @@ class CommandPaletteModal(ModalScreen):
         height: auto;
         max-height: 24;
         padding: 1 2;
-        background: #1a1a24;
-        border: thick #ff2d4a;
+        background: #111827;
+        border: solid #8b5cf6;
     }
     #palette-title {
         text-style: bold;
-        color: #ff2d4a;
+        color: #8b5cf6;
         margin-bottom: 1;
         text-align: center;
         width: 100%;
         height: 1;
     }
     #palette-scope {
-        color: #ffb74d;
+        color: #f59e0b;
         margin-bottom: 1;
         width: 100%;
         height: 1;
@@ -79,7 +79,7 @@ class CommandPaletteModal(ModalScreen):
             else "current repo"
         )
         with Container(id="palette-frame"):
-            yield Static("⚡ Bulk Action", id="palette-title", markup=False)
+            yield Static("Bulk Action", id="palette-title", markup=False)
             yield Static(f"  Scope: {scope_text}", id="palette-scope", markup=False)
             yield Input(placeholder="Filter actions…", id="palette-input")
             yield ListView(id="palette-list")
@@ -93,7 +93,7 @@ class CommandPaletteModal(ModalScreen):
         lv.clear()
         for key, label, desc in actions:
             lv.append(ListItem(
-                Static(f"[bold #3ddc84]{label}[/]  [dim #555568]{desc}[/]", markup=True),
+                Static(f"[bold #22c55e]{label}[/]  [dim #6b7280]{desc}[/]", markup=True),
                 id=f"action-{key}",
             ))
         if actions:

{gitpulse_tui-1.2.7 → gitpulse_tui-1.2.9}/gitpulse/ui/digest_screen.py

@@ -44,23 +44,23 @@ class DigestScreen(ModalScreen):
     #digest-frame {
         width: 95%;
         height: 90%;
-        background: #1a1a24;
-        border: thick #ff2d4a;
+        background: #111827;
+        border: solid #8b5cf6;
     }
     #digest-header {
         dock: top;
         height: 3;
-        background: #242430;
-        color: #ff2d4a;
+        background: #1f2937;
+        color: #8b5cf6;
         text-style: bold;
         padding: 0 2;
-        border-bottom: heavy #2a2a3a;
+        border-bottom: heavy #1f2937;
         layout: horizontal;
         align: left middle;
     }
     #digest-window-label {
         width: auto;
-        color: #e040fb;
+        color: #8b5cf6;
         margin-left: 2;
     }
     #digest-scroll {
@@ -74,10 +74,10 @@ class DigestScreen(ModalScreen):
     #digest-footer {
         dock: bottom;
         height: 1;
-        background: #1a1a24;
-        color: #555568;
+        background: #111827;
+        color: #6b7280;
         padding: 0 1;
-        border-top: solid #2a2a3a;
+        border-top: solid #1f2937;
     }
     """
 
@@ -97,7 +97,7 @@ class DigestScreen(ModalScreen):
     def compose(self) -> ComposeResult:
         with Container(id="digest-frame"):
             with Horizontal(id="digest-header"):
-                yield Static("📋 Activity Digest", markup=False)
+                yield Static("Activity Digest", markup=False)
                 yield Static("", id="digest-window-label")
             with ScrollableContainer(id="digest-scroll"):
                 yield Static(
@@ -116,7 +116,7 @@ class DigestScreen(ModalScreen):
 
     def _load_digest(self) -> None:
         label: Static = self.query_one("#digest-window-label", Static)
-        label.update(f"[#e040fb]window: {self._window}[/]")
+        label.update(f"[#8b5cf6]window: {self._window}[/]")
 
         body: Static = self.query_one("#digest-body", Static)
         body.update("[dim italic]Computing digest…[/]")
@@ -124,7 +124,7 @@ class DigestScreen(ModalScreen):
         try:
             since_ts = parse_since(self._window)
         except ValueError as e:
-            body.update(f"[bold #ff5252]Error: {e}[/]")
+            body.update(f"[bold #ef4444]Error: {e}[/]")
             return
 
         # Run in a worker so we don't block the UI.
@@ -144,7 +144,7 @@ class DigestScreen(ModalScreen):
             self._render_digest()
         elif event.state == WorkerState.ERROR:
             body: Static = self.query_one("#digest-body", Static)
-            body.update(f"[bold #ff5252]Error building digest: {event.worker.error}[/]")
+            body.update(f"[bold #ef4444]Error building digest: {event.worker.error}[/]")
 
     def _render_digest(self) -> None:
         d = self._digest
@@ -156,34 +156,34 @@ class DigestScreen(ModalScreen):
         if d.total_commits == 0:
             body.update(
                 "[dim italic]  No commits found for this window and author pattern.[/]\n"
-                "[dim #555568]  Tip: configure author emails in ~/.config/gitpulse/config.toml[/]"
+                "[dim #6b7280]  Tip: configure author emails in ~/.config/gitpulse/config.toml[/]"
             )
             return
 
         lines: list[str] = []
         since_str = datetime.fromtimestamp(d.since_ts, tz=timezone.utc).strftime("%Y-%m-%d %H:%M")
         lines.append(
-            f"[bold #ff2d4a]{d.total_commits}[/] commits across "
-            f"[bold #3ddc84]{d.repos_active}[/] repos  "
-            f"[#3ddc84]+{d.total_insertions}[/] [#ff5252]-{d.total_deletions}[/] lines  "
+            f"[bold #8b5cf6]{d.total_commits}[/] commits across "
+            f"[bold #22c55e]{d.repos_active}[/] repos  "
+            f"[#22c55e]+{d.total_insertions}[/] [#ef4444]-{d.total_deletions}[/] lines  "
             f"[dim]since {since_str} UTC[/]"
         )
-        lines.append("[dim #2a2a3a]─" * 60 + "[/]")
+        lines.append("[dim #1f2937]─" * 60 + "[/]")
 
         for rd in d.by_repo:
             lines.append(
-                f"\n[bold #e040fb]📁 {rd.repo.name}[/]  "
+                f"\n[bold #8b5cf6]{rd.repo.name}[/]  "
                 f"[dim]{len(rd.commits)} commit{'s' if len(rd.commits) != 1 else ''}  "
-                f"[#3ddc84]+{rd.insertions}[/]"
-                f" [#ff5252]-{rd.deletions}[/][/dim]"
+                f"[#22c55e]+{rd.insertions}[/]"
+                f" [#ef4444]-{rd.deletions}[/][/dim]"
             )
             for c in rd.commits:
                 rel = relative_time(c.ts)
-                stats = f"[#3ddc84]+{c.insertions}[/] [#ff5252]-{c.deletions}[/]" if (c.insertions or c.deletions) else ""
+                stats = f"[#22c55e]+{c.insertions}[/] [#ef4444]-{c.deletions}[/]" if (c.insertions or c.deletions) else ""
                 msg = c.message[:70]
                 lines.append(
-                    f"  [dim #ff2d4a]{c.short_hash}[/]  {msg}"
-                    f"  {stats}  [dim #555568]{rel}[/]"
+                    f"  [dim #8b5cf6]{c.short_hash}[/]  {msg}"
+                    f"  {stats}  [dim #6b7280]{rel}[/]"
                 )
 
         body.update("\n".join(lines))

gitpulse_tui-1.2.9/gitpulse/ui/fleet_status.py

@@ -0,0 +1,100 @@
+"""
+fleet_status.py — Cross-repo fleet status strip for GitPulse.
+
+A quiet single-line strip of clickable counters (dirty, behind, ahead,
+stashes, stale) across all scanned repositories. Each chip posts a
+FilterRequested message so the sidebar can narrow to matching repos.
+"""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.message import Message
+from textual.widget import Widget
+from textual.widgets import Static
+
+try:
+    from gitpulse.git_ops import RepoInfo, RepoStatus
+except ImportError:
+    from git_ops import RepoInfo, RepoStatus  # type: ignore[no-redef]
+
+
+class FleetChip(Static):
+    """A single clickable counter chip in the fleet status strip."""
+
+    def __init__(self, category: str, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.category = category
+
+    def on_click(self) -> None:
+        self.post_message(FleetStatus.FilterRequested(self.category))
+
+
+class FleetStatus(Widget):
+    """
+    Quiet single-row strip above the sidebar showing cross-repo counters.
+
+    Counters: dirty, behind, ahead, stashes, stale — plus an 'all' reset chip.
+    Clicking a chip filters the sidebar to the matching repos.
+    """
+
+    class FilterRequested(Message):
+        """Posted when a chip is clicked; carries the category to filter by."""
+
+        def __init__(self, category: str) -> None:
+            super().__init__()
+            self.category = category
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._active_filter: str = ""
+
+    def compose(self) -> ComposeResult:
+        yield Static("fleet", id="fleet-label", markup=False)
+        yield FleetChip("dirty",   id="chip-dirty")
+        yield FleetChip("behind",  id="chip-behind")
+        yield FleetChip("ahead",   id="chip-ahead")
+        yield FleetChip("stashes", id="chip-stashes")
+        yield FleetChip("stale",   id="chip-stale")
+        yield FleetChip("all",     id="chip-all")
+
+    def on_mount(self) -> None:
+        self._set_chip("chip-dirty",   "dirty",  0, "#f59e0b")
+        self._set_chip("chip-behind",  "behind", 0, "#ef4444")
+        self._set_chip("chip-ahead",   "ahead",  0, "#22c55e")
+        self._set_chip("chip-stashes", "stash",  0, "#8b5cf6")
+        self._set_chip("chip-stale",   "stale",  0, "#6b7280")
+        self.query_one("#chip-all", FleetChip).update("[#6b7280]all[/]")
+
+    def update_counters(self, repos: list[RepoInfo]) -> None:
+        """Recompute all chips from the current repo list."""
+        n_dirty       = sum(1 for r in repos if r.status != RepoStatus.CLEAN)
+        total_behind  = sum(r.behind for r in repos)
+        n_ahead       = sum(1 for r in repos if r.ahead > 0)
+        total_stashes = sum(r.stash_count for r in repos)
+        n_stale       = sum(1 for r in repos if r.has_stale_branches)
+
+        self._set_chip("chip-dirty",   "dirty",  n_dirty,       "#f59e0b")
+        self._set_chip("chip-behind",  "behind", total_behind,  "#ef4444")
+        self._set_chip("chip-ahead",   "ahead",  n_ahead,       "#22c55e")
+        self._set_chip("chip-stashes", "stash",  total_stashes, "#8b5cf6")
+        self._set_chip("chip-stale",   "stale",  n_stale,       "#6b7280")
+
+    def set_active_filter(self, category: str) -> None:
+        """Highlight the active filter chip and clear the others."""
+        self._active_filter = category
+        chip_map = {
+            "dirty": "chip-dirty", "behind": "chip-behind",
+            "ahead": "chip-ahead", "stashes": "chip-stashes",
+            "stale": "chip-stale", "all": "chip-all",
+        }
+        for cat, cid in chip_map.items():
+            chip: FleetChip = self.query_one(f"#{cid}", FleetChip)
+            chip.set_class(cat == category and category not in ("all", ""), "-active-filter")
+
+    def _set_chip(self, widget_id: str, label: str, count: int, color: str) -> None:
+        chip: FleetChip = self.query_one(f"#{widget_id}", FleetChip)
+        if count == 0:
+            chip.update(f"[#6b7280]{label} 0[/]")
+        else:
+            chip.update(f"[{color}]{label} {count}[/]")

gitpulse_tui-1.2.9/gitpulse/ui/header.py

@@ -0,0 +1,84 @@
+"""
+header.py — Slim application header for GitPulse.
+
+A single-row bar holding the logo, the seven content tabs, and the global
+action hints. Replaces Textual's built-in Header. Clicking a tab (or the
+prev/next tab keybindings handled by the app) posts an AppHeader.TabChanged
+message; the app switches the ContentSwitcher pane in response.
+"""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.message import Message
+from textual.widget import Widget
+from textual.widgets import Static
+from textual.containers import Horizontal
+
+# (tab id, display label) — order defines left-to-right tab order.
+TABS: list[tuple[str, str]] = [
+    ("status", "Status"),
+    ("commits", "Commits"),
+    ("diff", "Diff"),
+    ("branches", "Branches"),
+    ("remotes", "Remotes"),
+    ("tags", "Tags"),
+    ("tree", "Tree"),
+]
+
+TAB_IDS = [t[0] for t in TABS]
+
+
+class HeaderTab(Static):
+    """A single clickable tab label in the header."""
+
+    def __init__(self, tab_id: str, label: str, active: bool = False, **kwargs) -> None:
+        super().__init__(label, **kwargs)
+        self.tab_id = tab_id
+        if active:
+            self.add_class("-active")
+
+    def on_click(self) -> None:
+        self.post_message(AppHeader.TabChanged(self.tab_id))
+
+
+class AppHeader(Widget):
+    """Slim top header: logo · tabs · action hints."""
+
+    class TabChanged(Message):
+        """Posted when the active content tab should change."""
+
+        def __init__(self, tab_id: str) -> None:
+            super().__init__()
+            self.tab_id = tab_id
+
+    def __init__(self, active_tab: str = "status", **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._active = active_tab
+
+    def compose(self) -> ComposeResult:
+        yield Static(
+            "[bold #d1d5db]GitPulse[/]  [#6b7280]Fleet overview[/]",
+            id="header-logo",
+            markup=True,
+        )
+        with Horizontal(id="header-tabs"):
+            for tid, label in TABS:
+                yield HeaderTab(
+                    tid, label, active=(tid == self._active), id=f"htab-{tid}"
+                )
+        yield Static(
+            "[#6b7280]/ Search   r Refresh   ? Help[/]",
+            id="header-actions",
+            markup=True,
+        )
+
+    def set_active(self, tab_id: str) -> None:
+        """Highlight *tab_id* and clear the highlight from the others."""
+        self._active = tab_id
+        for tid in TAB_IDS:
+            try:
+                tab = self.query_one(f"#htab-{tid}", HeaderTab)
+            except Exception:
+                continue
+            tab.set_class(tid == tab_id, "-active")

gitpulse_tui-1.2.9/gitpulse/ui/help_modal.py

@@ -0,0 +1,101 @@
+"""
+help_modal.py — Keyboard shortcut cheat-sheet modal for GitPulse.
+
+Opened with '?'. Lists the global and context keybindings in a single
+centered panel.
+"""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.screen import ModalScreen
+from textual.widgets import Static
+from textual.containers import Container
+
+_SECTIONS: list[tuple[str, list[tuple[str, str]]]] = [
+    ("Global", [
+        ("/", "Search / filter repos"),
+        ("r", "Refresh — rescan all repos"),
+        ("w", "Toggle watch mode"),
+        ("d", "Activity digest"),
+        (":", "Bulk action palette"),
+        ("b", "Stale-branch cleanup"),
+        ("[ ]", "Previous / next tab"),
+        ("?", "This help"),
+        ("q", "Quit"),
+    ]),
+    ("Status tab", [
+        ("s / u", "Stage / unstage file"),
+        ("a / U", "Stage all / unstage all"),
+        ("c", "Commit staged changes"),
+        ("n", "New branch"),
+        ("z / Z", "Create / pop stash"),
+    ]),
+    ("Other tabs", [
+        ("Enter", "Switch branch · view commit diff · preview file"),
+        ("d", "Delete branch · view commit diff"),
+        ("f / p / P", "Fetch / pull / push (Remotes)"),
+    ]),
+    ("Sidebar", [
+        ("↑ ↓", "Navigate repositories"),
+        ("Space", "Toggle multi-select"),
+        ("*", "Select all visible"),
+    ]),
+]
+
+
+class HelpModal(ModalScreen):
+    """Centered keyboard-shortcut reference."""
+
+    BINDINGS = [Binding("escape,q,question_mark", "close", "Close", show=True)]
+
+    DEFAULT_CSS = """
+    HelpModal {
+        align: center middle;
+    }
+    #help-frame {
+        width: 64;
+        height: auto;
+        max-height: 90%;
+        padding: 1 2;
+        background: #111827;
+        border: solid #8b5cf6;
+    }
+    #help-title {
+        text-style: bold;
+        color: #8b5cf6;
+        width: 100%;
+        text-align: center;
+        margin-bottom: 1;
+    }
+    #help-body {
+        width: 100%;
+        height: auto;
+    }
+    #help-footer {
+        width: 100%;
+        text-align: center;
+        color: #6b7280;
+        margin-top: 1;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        with Container(id="help-frame"):
+            yield Static("Keyboard Shortcuts", id="help-title", markup=False)
+            yield Static(self._body(), id="help-body", markup=True)
+            yield Static("Esc / q to close", id="help-footer", markup=False)
+
+    @staticmethod
+    def _body() -> str:
+        lines: list[str] = []
+        for section, rows in _SECTIONS:
+            lines.append(f"[bold #d1d5db]{section}[/]")
+            for key, desc in rows:
+                lines.append(f"  [#8b5cf6]{key:<10}[/] [#d1d5db]{desc}[/]")
+            lines.append("")
+        return "\n".join(lines).rstrip()
+
+    def action_close(self) -> None:
+        self.dismiss()