Sangam (संगम) is Sanskrit for a confluence: the place where two rivers
meet and flow on as one. Which is what a merge is.
sangam is a terminal UI for the part of the day spent on pull requests:
finding the ones waiting for you, reading them, reviewing them and merging
them. It runs like lazygit: type sangam in any terminal. It's built on
the GitHub CLI (gh), fzf and tmux, so it uses your existing gh sign-in
and needs no token, server or config to start.
Contents
Features
See everything that needs you
- Sections, like saved searches. Each section is a GitHub search
across all your repos: "review requested", "my PRs", one repo, a whole
org, a label. Switch with
h/l; each tab shows its count.
- Several GitHub accounts at once. Run each section as a different
gh account, so work and personal PRs sit side by side. Press u to
focus on one account.
- The repo you're in comes first. Start sangam inside a clone and a
tab for that repo is added automatically.
- Open, merged, closed or all.
f cycles the state for every section;
s narrows a section with any GitHub search (author:, label:,
head:, words...).
Read a PR properly
- Overview: state, author, branches, merge readiness, checks, reviews,
size, labels, assignees, changed files and the description, laid out in
one screen.
- Diff with syntax highlighting (via bat), checks with durations,
and comments: the conversation plus review comments on the code,
grouped by file and line.
- Failed CI logs, cleaned up.
Enter on the checks view opens the
failed jobs' logs with timestamps stripped and errors highlighted.
Act on it
- A merge panel that knows what the PR needs. It shows readiness
(checks, review, conflicts, up to date, draft) and the commits that will
land, then offers only what makes sense now: the merge methods the repo
allows, update branch, auto-merge, an admin merge, mark ready, or check
out to resolve conflicts.
- Approve, request changes, comment (in your
$EDITOR), close or
reopen, toggle draft, check out the branch, copy the link, open it in
the browser.
Fast and out of your way
- Cached lists show instantly and refresh in the background; the first
PRs of a section are prefetched, so moving through them is instant.
- Vim-style keys,
? for a key sheet, q to quit.
- Works in any terminal. Inside tmux it can also be a popup on a key
(details).
Install
Requirements
sangam is a Bash script. It runs on Linux (macOS isn't supported yet:
it uses GNU tools, see the roadmap).
| Tool | Version | What for |
|---|
| bash | 4.4+ | sangam itself |
| gh (GitHub CLI) | 2.40+ | everything GitHub: sign-in, search, PR data, merging |
| fzf | 0.66+ | the list, preview and key handling |
| tmux | 3.3+ | the layout (sangam runs its own private tmux server; you don't need to use tmux yourself) |
| jq | 1.6+ | reading GitHub's JSON |
| git, less | any | the repo you're in, full-screen views |
| GNU coreutils, GNU grep, util-linux | any | standard on Linux (md5sum, stat, grep -P, setsid) |
Optional, but recommended:
| Tool | What you get |
|---|
| bat | syntax-highlighted diffs and Markdown descriptions |
| A Nerd Font in your terminal | the icons (without one they show as boxes) |
notify-send (libnotify) | desktop notifications after merges, reviews and comments |
wl-copy (Wayland), xclip (X11) | y copies a PR's link to the clipboard |
Install them with your package manager:
# Arch Linux
sudo pacman -S --needed github-cli fzf tmux jq git bat libnotify wl-clipboard
# Fedora
sudo dnf install gh fzf tmux jq git bat libnotify wl-clipboard
# Debian / Ubuntu (gh from GitHub's apt repo: https://github.com/cli/cli/blob/trunk/docs/install_linux.md)
sudo apt install gh tmux jq git bat libnotify-bin wl-clipboard
fzf version: Debian and Ubuntu ship an fzf older than 0.66. Install
a current one from fzf's releases
(a single binary: put it in ~/.local/bin) or with
git clone --depth 1 https://github.com/junegunn/fzf ~/.fzf && ~/.fzf/install.
On Debian/Ubuntu, bat's command is batcat; link it:
ln -s /usr/bin/batcat ~/.local/bin/bat.
sangam doctor checks all of this for you.
Quick install
curl -fsSL https://raw.githubusercontent.com/Theyashsawarkar/sangam/main/install.sh | bash
This clones sangam into ~/.local/share/sangam, links
~/.local/bin/sangam to it, and runs sangam doctor. No root needed.
If ~/.local/bin isn't on your PATH, the installer tells you the line
to add.
Installer options (pass them after bash -s --):
This is the beginning of the README. Read the rest at the original. Read the full README ↗
