# 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](docs/demo.gif)

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](docs/usage.md#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](docs/notes.gif)

## 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](docs/language-servers.md)
- To build: Go 1.27

## Install

Each [release](https://github.com/dturcinovic/seam/releases) has a static
binary for Linux and macOS on `amd64` and `arm64`, which needs nothing else
but git:

```bash
# 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:

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

Or from a clone, with [Task](https://taskfile.dev):

```bash
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](docs/usage.md#upgrading)).

## Quick start

In a git repository with changes:

```bash
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](docs/usage.md): what seam compares, the views, the keys and the
  mouse, notes and agents
- [Language servers](docs/language-servers.md): which ones, how to install
  them, and their workspaces
- [Configuration](docs/configuration.md): `config.toml` with every key

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE)