tongs 1.0.1

▶ Watch the trailer (58 s, on YouTube)

Every forge. One place.
A terminal-native code review inbox for developers who work across GitHub and GitLab.

Your team uses GitHub. Another uses GitLab. You live in the terminal. tongs gives you a single review inbox across forges, with syntax-highlighted diffs and inline comments, right where you already work.

lazygit is great for git operations. tongs picks up where it stops, at code review.

Documentation | PyPI | Issues

Install

# Recommended: install with pipx for isolation
pipx install tongs
# Or run directly in an isolated environment with uvx
uvx tongs

# Or install it persistently as a uv tool
uv tool install tongs

# Or plain pip
pip install tongs

Optional extras:

pip install "tongs[mcp]"      # MCP server for AI assistants
pip install "tongs[keyring]"  # system keyring as a credential source

Requires Python 3.12+. tongs needs no compiler and no system libraries of its own. It does read your forge credentials from the gh and glab CLIs when they are installed, falling back to ~/.netrc and then the optional system keyring, so at least one of those credential sources has to be set up before the inbox can load. See First-time auth setup.

From source

git clone https://github.com/andre-motta/tongs.git
cd tongs
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]" ruff

Use Python 3.12 or newer. If you prefer uv, use uv venv --python 3.12 to create the environment and uv pip install -e ".[dev]" ruff after activation.

Quick start

# Run tongs; it scans ~/git by default
tongs

# Override the scan root for a single run
tongs --scan-root ~/projects

To change the default permanently, set scan_root in ~/.config/tongs/config.toml:

[general]
scan_root = "~/projects"

tongs discovers repos under your scan root, reads their git remotes, and populates the inbox. Auth tokens come from your existing gh and glab CLI logins automatically.

First-time auth setup

# GitHub
gh auth login

# GitLab (gitlab.com)
glab auth login

# GitLab (self-hosted)
glab auth login --hostname gitlab.example.com

tongs never stores your tokens. It delegates to gh auth token / glab config get token at runtime, falling back to ~/.netrc and then the system keyring (if the optional keyring package is installed).

Features

Inbox

• Multi-forge inbox: GitHub PRs and GitLab MRs in one view, auto-detected from your git remotes
• Three tabs: My Reviews, My MRs, All Open with lazy loading and parallel fetching
• Per-repo scope: click any repo in the repo list to filter the inbox to just that project
• Sortable: press s to cycle sort order (updated, title, CI status, author)
• Repo list: searchable, filterable by forge type (GH/GL/All), sortable by name/forge/host

Diff review

• Split-pane viewer: file tree on the left, diff content on the right
• Syntax highlighting: 500+ languages via Pygments, bulk-highlighted per file for performance
• Word-level diffs: changed words highlighted bold+underline within modified lines
• Context folding: long unchanged sections collapse to "... N unchanged lines ..." markers
• Truncated diff handling: files too large for the API appear in the file tree with +/- stats and a "view in browser" prompt
• Markdown preview: toggle rendered preview for .md files with m
• File navigation: jump between files with n / Shift+N
• Unified or split view: press v to toggle; in split view h / l move focus between the old and new side

Commenting

• Inline comments: press c on any diff line to open the bottom-docked comment editor
• Discussion threads: existing inline comments appear as gutter markers in the diff; press d to expand/collapse threads with full Markdown rendering, replies, and resolution status
• Discussion tab: card-based view of all MR discussions with diff snippets, Rich Markdown threads, reply/resolve actions, and cross-tab jump-to-diff navigation
• Comment navigation: jump between comments with ] / [, wrapping around
• Reply to threads: press r to reply to a discussion from the diff or discussion tab
• Resolve threads: press R to resolve/unresolve a discussion (GitHub and GitLab; double-press to confirm)
• Visual line selection: select multiple lines with Shift+J / Shift+K or Ctrl+Click for multi-line comments
• Suggested changes: press F3 to open your $EDITOR with the selected code; edit it, and tongs posts a suggestion block (GitHub suggestion / GitLab suggestion:-0+N syntax)
• External editor: press F2 inside the comment editor to switch to your preferred editor
• General comments: press c from the overview tab to post a top-level MR comment
• Durable review drafts: press Ctrl+G to start review mode, collect comments locally, then submit them as one review with a verdict

Desktop review workspace (beta)

The terminal TUI remains the default interface. The desktop workspace is a beta optional interface over the same repositories, reviews, and drafts, documented in the desktop workspace guide. It has its own installation path, described in Desktop application (beta) below.

The desktop sidebar scans the configured local scan_root and scan_depth. It supports display-name search, GitHub/GitLab filtering, and Name, Forge, or Host sorting, while retaining entries whose host is missing. Its inbox uses the labels My Reviews, My MRs, All Open, Open, and Closed & merged. All Open is the scope that provides closed and merged reviews. Refreshing retains the current context and available review data; a partial repository failure leaves successful results visible. Selecting another repository resets the inbox query to that repository's default context.

Reviewing happens on the diff. Hover a line on Files changed and a + appears in the gutter; clicking it, or pressing c, opens a composer directly under that line. Drag over the line numbers or Shift-click a second line to comment on a range. The composer always offers the same two writes, so an immediate comment and a pending one are never the same gesture: Add comment now posts straight away, and Start a review, which becomes Add to review once one is pending, adds the entry to a durable draft. Insert suggestion pre-fills a suggestion block from the selected new-side lines.

Pending entries render inline under their anchor with a Pending badge and can be edited or deleted where they sit. A Your review button on Files changed and Discussions carries the pending count and opens a drawer holding the pending comments grouped by file, the review Summary, the Verdict tiles the forge and your permissions allow, Submit review, and Discard review, together with the submission progress and the recovery choices.

Draft edits are revision-bound. A stale-version conflict shows both texts and asks for a real choice rather than discarding either. Submissions report partial or unknown outcomes and require explicit reconciliation when the remote result cannot be established. Uncertain writes are never replayed automatically.

Desktop suggestions require a complete current diff selection containing contiguous new-side lines. Unified and Split are display layouts; deletions, old-side lines, partial diffs, unavailable files, and earlier revisions cannot be suggested. The replacement remains editable and uses the forge's supported suggestion syntax for GitHub or GitLab.

Desktop descriptions and discussions render ordinary Markdown while keeping raw HTML inert and images as text placeholders. Large or complex content can fall back to a bounded plain-text preview, and an aggregate discussion budget can omit later Markdown. HTTPS links open externally only after explicit activation.

The defects that are known and unfixed in the desktop workspace are listed in known issues.

Pipeline / CI

• Three-level drill-down: browse pipelines, drill into jobs grouped by stage, drill into full job logs
• ANSI log rendering: CI color output rendered natively via Text.from_ansi() with line numbers
• Cancel / Retry: cancel running pipelines or individual jobs (C), retry failed pipelines or jobs (R), with double-press confirmation
• Log search: press / in the log view to search the full job output, n / N to walk matches, Escape to close the search and return to where you were
• Open in editor: press F2 to open the job log in your $EDITOR for deeper analysis
• Open in browser: press o to jump to the pipeline or job in the web UI
• MR-scoped: Pipeline tab shows only pipelines associated with the current MR/PR
• Lazy loading: pipeline data is fetched only when the Pipeline tab is first opened

Caching

• SQLite-backed cache: API responses are cached locally in SQLite (via aiosqlite) for snappy navigation
• Transparent caching layer: CachedForgeClient wraps forge clients, caching reads and invalidating on mutations
• Per-key TTL: MR lists (60s) and diffs (300s) have configurable time-to-live; expired entries are pruned automatically
• LRU eviction: size-capped at 100 MB by default; recently accessed entries are protected from eviction
• WAL mode: concurrent reads never block the UI event loop
• Clear Cache: available from the command palette (Ctrl+P) to force a fresh fetch

Actions

• Approve (A): approve the MR/PR with double-press confirmation
• Unapprove (U): revoke your approval (GitLab)
• Merge (M): merge with double-press confirmation
• Close (X): close with double-press confirmation
• Merge readiness: visual indicator showing blockers (draft, conflicts, CI failing, merge status)

Navigation

• Command palette (Ctrl+P): context-aware fuzzy search across all available actions
• Commits tab: browse the full commit history for any MR/PR
• Open in browser (o): jump to the MR/PR in your default browser
• Copy URL (Ctrl+Y): yank the MR URL to clipboard
• Refresh (Ctrl+R): reload the current view

Desktop application (beta)

Every stable release publishes the desktop assets to the GitHub Release of the same vX.Y.Z tag that publishes tongs to PyPI: the signed per-user archive, its release manifest and Sigstore bundle, the Fedora RPMs, an SBOM and a checksum list. tongs --install-desktop selects the release whose version equals the installed core, so the pair to run for one version is:

pip install tongs==1.0.1
tongs --install-desktop

The desktop app is a beta. The v1.0.1 GitHub Release attaches the per-user archive and the Fedora RPMs. The commands and package names below describe the contract that every release satisfies.

The desktop application is optional. Plain tongs keeps scanning your repositories and opening the TUI; it never downloads, activates, or starts the desktop shell on its own.

The release contract matches Linux, Fedora 44, x86_64, and the GNU ABI. The native acceptance policy covers Fedora 44 KDE on x86_64 using XWayland. Other distributions, desktop environments, operating systems, architectures, and native Wayland are outside that policy, and the release metadata check rejects an unsupported target before anything is downloaded.

Per-user archive

tongs --install-desktop                  # exactly the same as: tongs desktop install
tongs desktop install --version 1.2.3    # install one exact release
tongs desktop update                     # install the verified release matching the core
tongs desktop status                     # inspect health; add --json for machine output
tongs desktop repair                     # recover activation or menu state
tongs desktop repair --redownload        # download a verified replacement if local recovery fails
tongs desktop uninstall                  # remove only the per-user activation

The archive installs under $XDG_DATA_HOME, or ~/.local/share when that variable is unset or relative. It needs no root, owns only its own menu entry, and never writes to /usr.

Every release is verified before anything is extracted: fixed-repository release discovery, a GitHub-managed attestation bound to an exact workflow and tag identity, manifest and archive hashes, and a local downgrade guard. See Security and signing for the full contract and its limits, and the desktop lifecycle reference for the recovery states and the status fields.

Fedora RPMs

A separate, optional RPM path builds three packages:

tongs-desktop requires the exact python3-tongs build it was made against, plus xorg-x11-server-Xwayland. Each stable release attaches these RPMs, together with the source-built companion packages they depend on, to its GitHub Release; install them from there with dnf install ./*.rpm. There is no COPR repository and no Fedora review submission, and the RPMs are not signed with a GPG key. The packaging sources and the local rebuild harness are under packaging/rpm/.

The two methods are independent. The per-user commands never install RPM packages, elevate privileges, write to /usr, or remove RPM-owned files, and tongs desktop status reports when a per-user activation and an RPM installation coexist.

Keybindings

The keybindings below describe the terminal TUI. The beta desktop workspace uses labelled controls and does not change these terminal commands.

Global

Inbox

Repo list

MR detail

Diff viewer

In split diff mode, h and l move focus between the old and new side columns.

Comment editor

Review draft

See the full keybinding reference for the three additional bindings that reconcile an interrupted submission.

Discussion tab

Pipeline tab

Configuration

tongs uses ~/.config/tongs/config.toml (or the platform-appropriate config directory). All settings have sensible defaults. The configuration reference documents every key, including three keys that older configs may still set and that no code currently reads.

[general]
scan_root = "~/git"
scan_depth = 5

[ui]
ascii_mode = false          # Set true for minimal terminals

[cache]
mr_list_ttl = 60
diff_ttl = 300
max_size_mb = 100

[concurrency]
max_parallel = 8
request_timeout = 30

# Self-hosted forges
[hosts.my-gitlab]
hostname = "gitlab.example.com"
forge_type = "gitlab"

[hosts.my-ghes]
hostname = "github.corp.com"
forge_type = "github"

Plugin system

tongs uses a plugin architecture based on Python entry points. The MCP server, for example, is itself a plugin. You can extend tongs with new commands, screens, and lifecycle hooks by writing your own.

Writing a plugin

1. Subclass TongsPlugin:

   from tongs.plugins.base import TongsPlugin
   
   class MyPlugin(TongsPlugin):
       @property
       def name(self) -> str:
           return "my-plugin"
   
       @property
       def version(self) -> str:
           return "0.1.0"
   
       async def on_app_ready(self, ctx) -> None:
           """Called after the TUI app is mounted, with a PluginContext."""
   
       async def on_app_shutdown(self, ctx) -> None:
           """Called before app exit."""
   
       def get_commands(self) -> list[tuple[str, str, object]]:
           """Return (display, help_text, callback) tuples for the command palette."""
           return [("My Action", "Does something useful", self._do_it)]
   
       def get_screens(self) -> dict[str, type]:
           """Return screen_name -> Screen class mappings."""
           return {}
   

2. Register it as an entry point in your package's pyproject.toml:

   [project.entry-points."tongs.plugins"]
   my-plugin = "my_package.plugin:MyPlugin"
   

3. Install your package (or pip install -e . for development) and tongs discovers it automatically on startup.

Plugin configuration

Plugins are enabled by default. To disable a plugin, add a [plugins.<name>] section to your config:

# ~/.config/tongs/config.toml
[plugins.mcp]
enabled = false

Plugin hooks

ctx is a PluginContext, a restricted view of the app rather than the app itself. It exposes the forge registry, cache, config and discovered repos, a notify helper, push_screen and pop_screen, and plugin_config(name) for the plugin's own config section.

MCP server (plugin)

tongs ships an optional Model Context Protocol server, packaged as a built-in plugin, that lets AI assistants interact with your merge requests programmatically.

Install

pip install "tongs[mcp]"

Start

tongs-mcp

The server communicates over stdio, so you can wire it into any MCP-compatible client, including Codex, Claude Code, and Claude Desktop. It reuses the same forge configuration and auth tokens as the TUI.

When the mcp extra is installed, the built-in plugin also adds a Start MCP Server command to the command palette, which launches the server as python -m tongs.mcp.server. On a default install without the extra, the plugin contributes no command.

Connect to Codex

After installing tongs[mcp] and completing the forge login above, register the server with the Codex CLI:

codex mcp add tongs -- tongs-mcp
codex mcp list

Codex launches the stdio server itself. The tongs-mcp executable and any authentication CLI (gh or glab) must be available in the environment where Codex runs.

For a source checkout, install the MCP extra in the activated virtual environment and register the executable by absolute path:

source .venv/bin/activate
python -m pip install -e ".[dev,mcp]"
codex mcp add tongs -- "$PWD/.venv/bin/tongs-mcp"

Alternatively, add this to ~/.codex/config.toml, replacing the path with your checkout's absolute path:

[mcp_servers.tongs]
command = "/absolute/path/to/tongs/.venv/bin/tongs-mcp"

See the official Codex MCP configuration guide for configuration options. Example request: "Use tongs to list open PRs for github.com/acme/app."

Connect to Claude Code

claude mcp add tongs -- tongs-mcp
claude mcp list

Everything after -- is the command Claude Code launches, so use an absolute path when tongs-mcp is not on PATH:

claude mcp add tongs -- "$PWD/.venv/bin/tongs-mcp"

claude mcp add defaults to the local scope, which applies to the current project only. Add --scope user to make the server available in all your projects, or --scope project to write a shared .mcp.json into the repository. Claude Desktop is a separate application with its own claude_desktop_config.json.

Tools

All tools accept a repo_path in hostname/owner/repo format (e.g. github.com/acme/app). Destructive actions (merge, close, reopen, cancel) are intentionally excluded as a security boundary.

tongs is for you if

• You review code across both GitHub and GitLab
• You want diffs, inline comments, and approvals in your terminal
• You manage many repos and want a single inbox
• You prefer keyboard-driven workflows over browser tabs

Current state

The terminal application is the released, supported product. The version you get from PyPI today provides the multi-forge inbox, the diff viewer, inline comments and suggested changes, discussion threads, MR actions, pipeline and CI drill-down, the SQLite cache, the plugin system, and the MCP server.

tongs 1.0.0 added the split diff view and durable review drafts, and 1.0.1 fixes the defects found since then, including token refresh after a 401. The desktop workspace is a beta attached to every release since v1.0.0, for Fedora 44 x86_64, together with its per-user installer and Fedora RPMs. Known defects are listed in known issues.

Track what is planned and what is blocked through the open issues and their dependency links rather than through a phase table.

Contributing

See CONTRIBUTING.md for development setup, code style, and how to add forge backends, and the Contributing page for a summary of the checks a pull request has to pass.

Working on tongs with a coding agent

Run your agent from the repository root after the source setup. Both Codex and Claude Code read AGENTS.md for the development workflow, validation commands, commit rules, and links to the subsystem guides under .agents/. See OpenAI's AGENTS.md guide for how Codex discovers those instructions.

The MCP connection above is optional for contributing to tongs. It exposes forge operations to the assistant; repository development itself uses the local source tree and tests.

Contributions still shape the architecture. The plugin system makes it easy to add new commands, screens, and lifecycle hooks without touching core code. Check the issues for good starting points, or open one to discuss what you'd like to build.

Why "tongs"?

In metalworking, tongs grip hot work across the forge. This tool grips your merge requests across forges.

License

MIT