# jgorodetsky/ghh architecture

> Architecture diagram of the GitHub repository jgorodetsky/ghh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jgorodetsky/ghh
- Repository: https://github.com/jgorodetsky/ghh

## Overview

ghh is a shell-based, searchable command center for Git and GitHub workflows, with a separate interactive conventional-commit command. The main workflow is to invoke ghh, optionally pre-filter its menu, choose a command, complete any guided prompts or pickers, pass its risk checks, and run it. The README documents broad Git, PR, CI, issue, worktree, and release capabilities. Runtime source was not sampled, so subsystem paths use the existing bin/ghh file and uncertain internal wiring is omitted.

Main entry points: [`bin/ghh`](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh) (Risk checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_menu["Command menu"]
  node_entry["ghh entry"]
  node_catalog["Command catalog"]
  node_filter["Menu filtering"]
  node_menuui["Fuzzy menu"]
  node_risk["Risk checks"]
  node_guided["Guided pickers"]
  node_custom["Custom commands"]
  node_recent["Recent commands"]
end

subgraph group_git["Git workflows"]
  node_gitops["Git operations"]
  node_diff["Diff and review"]
  node_worktrees["Branch and worktrees"]
  node_commit["Commit builder"]
end

subgraph group_github["GitHub workflows"]
  node_pr["PR workflows"]
  node_ci["CI and checks"]
  node_issues["Issues and search"]
  node_releases["Tags and releases"]
end

subgraph group_support["Shell support"]
  node_state[("Pick/query state")]
end

node_user(("User"))
node_gitcli["git"]
node_ghcli["GitHub CLI"]
node_fzf["fzf"]
node_history[("Shell history")]
node_browser["Web browser"]
node_shell["Shell"]
node_platform["Platform services"]

node_user -->|"invokes"| node_entry
node_entry -->|"loads"| node_catalog
node_entry -->|"passes query"| node_filter
node_entry -->|"opens"| node_menuui
node_catalog -->|"includes"| node_custom
node_custom -->|"reads config"| node_shell
node_menuui -->|"queries"| node_fzf
node_menuui -->|"selects command"| node_risk
node_menuui -->|"ranks commands"| node_recent
node_recent -->|"reads history"| node_state
node_recent -->|"writes history"| node_state
node_risk -->|"dispatches guided commands"| node_guided
node_risk -->|"dispatches"| node_gitops
node_risk -->|"dispatches"| node_diff
node_risk -->|"dispatches"| node_worktrees
node_risk -->|"dispatches"| node_commit
node_risk -->|"dispatches"| node_pr
node_risk -->|"dispatches"| node_ci
node_risk -->|"dispatches"| node_issues
node_risk -->|"dispatches"| node_releases
node_gitops -->|"runs"| node_gitcli
node_diff -->|"runs"| node_gitcli
node_worktrees -->|"runs"| node_gitcli
node_commit -->|"commits with"| node_gitcli
node_pr -->|"runs"| node_ghcli
node_ci -->|"runs"| node_ghcli
node_issues -->|"runs"| node_ghcli
node_releases -->|"runs tag commands"| node_gitcli
node_releases -->|"runs release commands"| node_ghcli
node_entry -->|"records commands"| node_history
node_ci -->|"opens check"| node_browser
node_entry -->|"detects clipboard and browser"| node_platform
node_entry -.->|"integrates with"| node_shell

click node_entry "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_catalog "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_filter "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_menuui "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_risk "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_guided "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_custom "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_recent "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_gitops "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_diff "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_worktrees "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_commit "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_pr "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_ci "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_issues "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"
click node_releases "https://github.com/jgorodetsky/ghh/blob/main/bin/ghh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_catalog,node_filter,node_menuui,node_risk,node_guided,node_custom,node_recent,node_user,node_browser toneBlue
class node_gitops,node_diff,node_worktrees,node_commit,node_history toneAmber
class node_pr,node_ci,node_issues,node_releases toneMint
class node_state toneRose
class node_gitcli,node_ghcli,node_fzf,node_shell,node_platform toneIndigo
```

## Components

### Command menu

- [ghh entry](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Command catalog](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Menu filtering](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Fuzzy menu](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Risk checks](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Guided pickers](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Custom commands](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Recent commands](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`

### Git workflows

- [Git operations](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Diff and review](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Branch and worktrees](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Commit builder](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`

### GitHub workflows

- [PR workflows](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [CI and checks](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Issues and search](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`
- [Tags and releases](https://github.com/jgorodetsky/ghh/blob/main/bin/ghh): `bin/ghh`

### Shell support

- **Pick/query state**

### Other components

- **User**
- **git**
- **GitHub CLI**
- **fzf**
- **Shell history**
- **Web browser**
- **Shell**
- **Platform services**

## Connections

- User → ghh entry: invokes
- ghh entry → Command catalog: loads
- ghh entry → Menu filtering: passes query
- ghh entry → Fuzzy menu: opens
- Command catalog → Custom commands: includes
- Custom commands → Shell: reads config
- Fuzzy menu → fzf: queries
- Fuzzy menu → Risk checks: selects command
- Fuzzy menu → Recent commands: ranks commands
- Recent commands → Pick/query state: reads history
- Recent commands → Pick/query state: writes history
- Risk checks → Guided pickers: dispatches guided commands
- Risk checks → Git operations: dispatches
- Risk checks → Diff and review: dispatches
- Risk checks → Branch and worktrees: dispatches
- Risk checks → Commit builder: dispatches
- Risk checks → PR workflows: dispatches
- Risk checks → CI and checks: dispatches
- Risk checks → Issues and search: dispatches
- Risk checks → Tags and releases: dispatches
- Git operations → git: runs
- Diff and review → git: runs
- Branch and worktrees → git: runs
- Commit builder → git: commits with
- PR workflows → GitHub CLI: runs
- CI and checks → GitHub CLI: runs
- Issues and search → GitHub CLI: runs
- Tags and releases → git: runs tag commands
- Tags and releases → GitHub CLI: runs release commands
- ghh entry → Shell history: records commands
- CI and checks → Web browser: opens check
- ghh entry → Platform services: detects clipboard and browser
- ghh entry → Shell: integrates with