seam

module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT

README

seam

A side-by-side diff viewer for the terminal that knows your code: hover a symbol in the diff for its type and docs from the language server, and leave review notes at lines for an agent such as Claude Code to answer. One key switches between the changed hunks and the whole file.

seam showing a diff, the whole file and a hover

seam is not a pager like delta or diff-so-fancy, which colour the output of git diff: it reads the repository itself, holds both versions of each file, and lets you move through them.

Features

  • Side by side, or one column when the terminal is narrow
  • The changed hunks or the whole file, one file at a time or all of them in one stream
  • Hover and go-to-definition through the language server, on the new side and the old one, also when comparing commits
  • Syntax colours for Go, Rust, JavaScript, TypeScript, JSX, TSX, HTML, PHP and Python, and any other language chroma knows, by configuration
  • Changed words marked within a line
  • Review notes: questions and findings at lines of the diff, set with a key or a click in the gutter, which follow their lines through edits and belong to the branch they were set on
  • seam mcp, so that an agent such as Claude Code or OpenCode reads your notes and answers them at the line, and S sends the waiting notes to a running Claude Code session (see Agents)
  • Files or directories on disk compared with --files, also as git difftool
  • A file list grouped by folder, and reload on change with --watch
  • Keys, colours and servers configurable in one TOML file

seam setting a question and a finding, then listing the notes

Requirements

  • Linux or macOS
  • git 2.36 or newer
  • A terminal with mouse support for hover; without one, the caret does it
  • For hover, the language server of the language, see Language servers
  • To build: Go 1.27

Install

Each release has a static binary for Linux and macOS on amd64 and arm64, which needs nothing else but git:

# macOS, with Homebrew
brew install --cask dturcinovic/tap/seam
# Debian, Ubuntu
sudo apt install ./seam_<version>_amd64.deb
# Fedora and other rpm systems
sudo dnf install ./seam-<version>-1.x86_64.rpm
# Any Linux: unpack and put seam on the PATH
tar -xzf seam_<version>_linux_amd64.tar.gz seam && mv seam ~/.local/bin/

checksums.txt in the release holds the SHA-256 of each file.

With Go 1.27:

go install github.com/dturcinovic/seam/cmd/seam@latest

Or from a clone, with Task:

task build    # bin/seam

seam --version names the release, the commit and its date, and seam upgrade brings an install to the latest release (see Upgrading).

Quick start

In a git repository with changes:

seam                # HEAD against the worktree
seam main           # main against the worktree
seam HEAD~1 HEAD    # the last commit
seam --staged       # what is staged
seam --files a b    # two files or directories on disk
Key Does
tab / shift+tab Next, previous file
n / p Next, previous change
f Hunks or the whole file
u Side by side or one column
s One file or all files in a stream
b File list
mouse at rest Hover
ctrl + click Go to the definition, ctrl+o back
i Caret: K hovers, d goes to the definition
c A note at the caret's line, or click [+] in the gutter
N All notes
q Quit

Documentation

  • Usage: what seam compares, the views, the keys and the mouse, notes and agents
  • Language servers: which ones, how to install them, and their workspaces
  • Configuration: config.toml with every key

Contributing

See CONTRIBUTING.md.

License

MIT

Directories

Path Synopsis
cmd
seam command
Command seam shows the changes of a git repository side by side in the terminal.
Command seam shows the changes of a git repository side by side in the terminal.
internal
adapter/driven
Package driven groups the adapters that implement outgoing ports, one subpackage per outside system (git, chroma, the language servers, the configuration file).
Package driven groups the adapters that implement outgoing ports, one subpackage per outside system (git, chroma, the language servers, the configuration file).
adapter/driven/chroma
Package chroma finds the tokens of source text with chroma's built-in lexers and maps chroma's token types onto syntax kinds.
Package chroma finds the tokens of source text with chroma's built-in lexers and maps chroma's token types onto syntax kinds.
adapter/driven/command
Package command runs the command that upgrades seam, such as brew, with its output where the user sees it.
Package command runs the command that upgrades seam, such as brew, with its output where the user sees it.
adapter/driven/configfile
Package configfile reads seam's TOML configuration file: the table of languages and servers, the viewer's settings and the limits.
Package configfile reads seam's TOML configuration file: the table of languages and servers, the viewer's settings and the limits.
adapter/driven/files
Package files reads files and directories on disk that git does not track, as git difftool hands them over, and finds those that lie in the repository's worktree.
Package files reads files and directories on disk that git does not track, as git difftool hands them over, and finds those that lie in the repository's worktree.
adapter/driven/fswatch
Package fswatch watches a repository's files with fsnotify (inotify on Linux, kqueue on macOS) and reports that something changed, never what.
Package fswatch watches a repository's files with fsnotify (inotify on Linux, kqueue on macOS) and reports that something changed, never what.
adapter/driven/git
Package git reads the repository seam compares in: it lists changes and untracked files with the git command and reads blobs through one long-running cat-file process and worktree files through os.Root.
Package git reads the repository seam compares in: it lists changes and untracked files with the git command and reads blobs through one long-running cat-file process and worktree files through os.Root.
adapter/driven/github
Package github asks GitHub's public release API for the latest release of seam.
Package github asks GitHub's public release API for the latest release of seam.
adapter/driven/lsp
Package lsp talks to language servers over the Language Server Protocol: it starts them as child processes, one per server and workspace and at most four at a time, tells them about the documents on screen and asks them for hovers.
Package lsp talks to language servers over the Language Server Protocol: it starts them as child processes, one per server and workspace and at most four at a time, tells them about the documents on screen and asks them for hovers.
adapter/driven/lsp/cmd/fakelsp command
Command fakelsp is a language server for seam's tests that does what its script says, misbehaviour included.
Command fakelsp is a language server for seam's tests that does what its script says, misbehaviour included.
adapter/driven/notestore
Package notestore keeps the book of review notes in one JSON file in git's directory, shared by every seam process of the worktree.
Package notestore keeps the book of review notes in one JSON file in git's directory, shared by every seam process of the worktree.
adapter/driven/process
Package process asks the operating system whether a process of this machine still runs.
Package process asks the operating system whether a process of this machine still runs.
adapter/driven/selfbinary
Package selfbinary replaces seam's own binary with a newer one, at once or not at all.
Package selfbinary replaces seam's own binary with a newer one, at once or not at all.
adapter/driven/statefile
Package statefile keeps what seam remembers between sessions in a file under the XDG state directory: for now the last check for a newer release.
Package statefile keeps what seam remembers between sessions in a file under the XDG state directory: for now the last check for a newer release.
adapter/driving/mcp
Package mcp serves the review notes of a worktree to an agent session (Claude Code, OpenCode, any MCP client) over the Model Context Protocol on stdin and stdout: the agent takes notes, reads them and answers them.
Package mcp serves the review notes of a worktree to an agent session (Claude Code, OpenCode, any MCP client) over the Model Context Protocol on stdin and stdout: the agent takes notes, reads them and answers them.
adapter/driving/tui
Package tui is the Bubble Tea front end.
Package tui is the Bubble Tea front end.
app/port/in
Package in holds the incoming ports, which the TUI adapter calls and the use cases implement.
Package in holds the incoming ports, which the TUI adapter calls and the use cases implement.
app/port/in/infakes
Code generated by counterfeiter.
Code generated by counterfeiter.
app/port/out
Package out holds the outgoing ports, cut by capability, which the use cases call and the driven adapters implement.
Package out holds the outgoing ports, cut by capability, which the use cases call and the driven adapters implement.
app/port/out/outfakes
Code generated by counterfeiter.
Code generated by counterfeiter.
app/usecase
Package usecase implements the incoming ports on top of the outgoing ones.
Package usecase implements the incoming ports on top of the outgoing ones.
archtest
Package archtest checks rules of the code base that no linter covers, such as goroutines started only through supervise.
Package archtest checks rules of the code base that no linter covers, such as goroutines started only through supervise.
config
Package config resolves the settings of one seam session from flags and the environment, the path of the configuration file among them.
Package config resolves the settings of one seam session from flags and the environment, the path of the configuration file among them.
domain
Package domain holds the business types of seam: the diff model and its algorithm, views and their anchors, comparisons and sources, languages, hover values and limits.
Package domain holds the business types of seam: the diff model and its algorithm, views and their anchors, comparisons and sources, languages, hover values and limits.
domain/change
Package change describes what seam compares: the two sides of a comparison, the files that differ between them and the errors of reading a side.
Package change describes what seam compares: the two sides of a comparison, the files that differ between them and the errors of reading a side.
domain/diff
Package diff compares two versions of a file line by line and aligns them side by side: equal lines pair up, a block of changed lines pairs up as far as both sides reach, and the rest of the block stands alone.
Package diff compares two versions of a file line by line and aligns them side by side: equal lines pair up, a block of changed lines pairs up as far as both sides reach, and the rest of the block stands alone.
domain/filediff
Package filediff describes loading the diff of one file in the background: the request with its generation, the snapshot the UI shows, the notices that explain what it leaves out, the column index of long lines and the syntax of both sides.
Package filediff describes loading the diff of one file in the background: the request with its generation, the snapshot the UI shows, the notices that explain what it leaves out, the column index of long lines and the syntax of both sides.
domain/hover
Package hover holds the values that pass between the viewer and the language servers: the documents a server is told about, the position a hover asks for, how a request was taken, and what comes back.
Package hover holds the values that pass between the viewer and the language servers: the documents a server is told about, the position a hover asks for, how a request was taken, and what comes back.
domain/lang
Package lang names the languages of a session and the servers that hover over them: which language a file or a code fence is written in, which server and languageId it has, and which workspace a file belongs to.
Package lang names the languages of a session and the servers that hover over them: which language a file or a code fence is written in, which server and languageId it has, and which workspace a file belongs to.
domain/limits
Package limits holds the bounds seam keeps on what it reads and keeps in memory, as types that check themselves.
Package limits holds the bounds seam keeps on what it reads and keeps in memory, as types that check themselves.
domain/note
Package note holds the review notes set at places of a diff: what a note is, where it is anchored, how its place is found again in a later version of the file, and the book that keeps them all.
Package note holds the review notes set at places of a diff: what a note is, where it is anchored, how its place is found again in a later version of the file, and the book that keeps them all.
domain/release
Package release holds what seam knows about its own releases: a release version, the last check for a newer one and the notice that names it, the kinds of install and how each is upgraded, and the archive of a release with its checksums.
Package release holds what seam knows about its own releases: a release version, the last check for a newer one and the notice that names it, the kinds of install and how each is upgraded, and the archive of a release with its checksums.
domain/syntax
Package syntax describes highlighted text as kinds of token per stretch of a line.
Package syntax describes highlighted text as kinds of token per stretch of a line.
domain/ui
Package ui holds what a user may set about the viewer: the palette, the keys of its actions, the context of the hunk view, the delay of a hover and when the sides stand side by side.
Package ui holds what a user may set about the viewer: the palette, the keys of its actions, the context of the hunk view, the delay of a hover and when the sides stand side by side.
domain/view
Package view lays out the rows of a file diff as the lines of a view, the full file or the changed blocks with context and folds, side by side or unified, and keeps a view's place across a change of view through its anchor row.
Package view lays out the rows of a file diff as the lines of a view, the full file or the changed blocks with context and folds, side by side or unified, and keeps a view's place across a change of view through its anchor row.
observability
Package observability builds the process logger and routes fx's events and the panics caught by supervise into it.
Package observability builds the process logger and routes fx's events and the panics caught by supervise into it.
supervise
Package supervise starts every goroutine and timer callback of seam.
Package supervise starts every goroutine and timer callback of seam.
testsupport
Package testsupport holds fixtures and helpers shared by the tests.
Package testsupport holds fixtures and helpers shared by the tests.
textcell
Package textcell maps text to terminal cells: grapheme boundaries, cell widths, tab stops and visible replacements for control characters, each cell traced back to its original bytes.
Package textcell maps text to terminal cells: grapheme boundaries, cell widths, tab stops and visible replacements for control characters, each cell traced back to its original bytes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL