tuick 0.1.9

Terminal based browser for source code errors.

Tuick, the Text-based User Interface for Compilers and checKers

Tuick is a terminal browser for compiler and linter errors.

Tuick is an terminal-based interactive error browser for command-line tools, powered by fzf and errorformat, with extensive text editor integration.

Introduction

Tuick is the programmer's tool I was surprised did not exist yet.

• Display the terminal output unmodified.
• Standalone, not coupled with any text editor, and supports every editor.
• Easy navigation and selection, with preview.
• Updates automatically when source files change.
• Requires no configuration, but can be configured if needed.

Status

This tool is in early development. Feedback is more than welcome.

• More error formats. reviewdog/errorformat focuses on static analysis tools, and does not support compilers or interpreter stack traces. Please provide error dumps from your favorite tools, and I will add support for them.
• Editor support. If your text editor is not supported, please provide example commands to open files on a line, or line and column, and I will add support for it.
• Windows support. I made every effort to support Windows, but I have not tested it, so please report any issues.
• Usability. I welcome any feedback on the user interface.

Features

• Errorformat parsing: Parse output from any tool with errorformat patterns. Right now, it has built-in support for tools supported by reviewdog/errorformat, plus pytest and ruff. Improved support for mypy.
• Multi-line error grouping: Complex errors displayed as blocks, one keypress to navigate to the next error.
• Editor integration: Jump directly to error locations in your editor. Built-in support for 20 text editors. Can be configured to support any editor.
• Auto-reload: Automatic refresh on file changes using watchexec, respecting .gitignore properly and other VCS ignore files.
• Handle mixed output: Can display a single list of errors from multiple tools, with potentially incompatible syntaxes.
• Theme detection: Automatic dark/light theme detection for fzf and bat.

Quick Start

Usage Modes

List Mode (Default)

Default mode when the command name is not detected as a compiler. All output is parsed using a single format.

tuick -- mypy src tests  # Parse and browse mypy errors
tuick -- ruff check      # Parse and browse ruff errors

The -- is not necessary here, but it's a good habit to have, because it will become necessary when you add options to the build command.

Run the command, if it outputs anything, parse it and start fzf.

• Move: up, down, space, backspace, page down, page up.
• Open in editor: Enter.
• Toggle preview: /, Ctrl-/
• Manual reload: r
• Exit: q, Esc, Ctrl-C

If a reload produces no output, tuick will exit.

If you exit manually, tuick prints the raw output of the last complete command run.

Top Mode

Run build systems with output from multiple commands.

tuick make          # Auto-detect make as build system
tuick just check    # Auto-detect just as build system
tuick --top script  # Explicit top mode for unrecognized commands

To support build systems that orchestrate multiple tools, tuick has an optional layered mode of operation.

In top mode, the command output is expected to contain mixed data: raw output from the build system, and structured blocks from tuick --format.

Build systems (make, just, cmake, ninja) are auto-detected and use top mode automatically.

Explicit top mode (with --top) is required for unrecognized build systems.

The TUICK_PORT environment variable is set by tuick in top mode or list mode.

Format Mode

Intended for use in build systems:

# In Makefile:
check:
    tuick --format -- mypy .
    tuick --format -- ruff check

make check        # Non interactive, pass-through mode
tuick make check  # Interactive

If the TUICK_PORT environment variable is not set, stream command output unchanged (passthrough mode). So make check will work normally.

If the TUICK_PORT environment variable is set, parse the command output, and output null-terminated blocks, and markers. This is for the top tuick to detect output that has not been parsed.

Command-Line Options

Top-Level Options

• -f, --format-name NAME — Override autodetected errorformat name.
• -p, --pattern PATTERN — Custom errorformat pattern(s), can be specified multiple times
• --top — Force top mode (override build system detection)
• -v, --verbose — Show verbose output on exit.
• --theme THEME — Color theme: dark, light, bw, auto (default: auto)

Note: -f/--format-name and -p/--pattern are mutually exclusive.

Internal Options

These options are for internal use by tuick when communicating between processes:

• --reload — Run command and output blocks (called by fzf binding)
• --select — Open editor at error location (called by fzf binding)
• --message TEXT — Log a message (used for event logging)
• --start — Notify fzf port to parent process

Auto-Reload on File Changes

Tuick automatically monitors the filesystem and reloads on changes using watchexec:

• Monitors current directory recursively
• Honors .gitignore (properly, with subdirs ignores, user ignores, etc.) and other VCS ignore files by default
• Debounces rapid changes
• No configuration needed

Theme Detection and Configuration

Tuick supports automatic dark/light theme detection for fzf and bat preview, and obeys the NO_COLOR environment variable.

In order of precedence, highest priority first:

1. --theme option: dark/light/bw/auto, default auto.
2. CLI_THEME environment variable: dark/light.
3. NO_COLOR environment variable: if set and non-empty, selects bw theme.
4. Terminal probing: OSC11 query to detect terminal background color.
5. COLORFGBG environment variable.
6. Default to dark.

If the BAT_THEME environment variable is set, no theme selection option is passed to bat, so the theme specified by BAT_THEME will be used.

The bw theme is a special theme that disables colors, but tries to preserve text styling.

CLI_THEME and shell integration

Theme detection is a common issue. To avoid repeated terminal probing with OSC11 queries, I recommend that you set a pre-exec hook in your shell that updates CLI_THEME and other environment variables based on terminal probing.

This should probably be a project of its own.

User Configuration Environment Variables

Initial preview visibility

export TUICK_PREVIEW=0 to start with preview window hidden.

Press / or Ctrl-/ to toggle preview visibility.

Verbose output

export TUICK_VERBOSE=1 to enable verbose output showing commands run by tuick.

This is equivalent to using the --verbose flag. When set, verbose mode is inherited by nested tuick processes in build systems.

Editor Integration

Tuick opens files at error locations in your editor. Editor is selected in this order:

1. TUICK_EDITOR — Tuick-specific editor
2. EDITOR — Standard editor variable
3. VISUAL — Alternative editor variable

The environment variable can contain a command with additional options. If the editor command name is recognized, tuick will use the most appropriate method for opening the file.

In particular, IDEA, PyCharm, VS Code and variants, will open files through the URL handler registered by the editor. This is often much faster than using the command-line interface.

Custom Editor Templates

You can use the following environment variables with unsupported editors:

• TUICK_EDITOR_LINE — Template command to open a file on a line.
• TUICK_EDITOR_LINE_COLUMN — Template to open a file on a line and column.

Examples:

export TUICK_EDITOR="myeditor"
export TUICK_EDITOR_LINE="myeditor {file} -g {line}"
export TUICK_EDITOR_LINE_COLUMN="myeditor {file} -g {line}:{col}"

Internal Use Environment Variables

These variables are set by tuick for communication with commands:

• TUICK_PORT — Port number for tuick coordination server
• TUICK_API_KEY — Authentication key for tuick server
• TUICK_LOG_FILE — Path to shared log file for all tuick processes
• FORCE_COLOR — Set to 1 for build commands when theme is not black-and-white

Dependencies

Required:

• [uv] — Python package manager, for installation.
• fzf — Interactive fuzzy finder
• errorformat — Error output parser (from reviewdog project)
• watchexec — Filesystem watcher for auto-reload

Optional:

• bat — Syntax-highlighted preview in fzf (highly recommended)

Install:

# macOS (via Homebrew)
brew install uv go fzf watchexec bat

# errorformat (requires Go)
go install github.com/reviewdog/errorformat/cmd/errorformat@latest

# In the tuick repository
just install

Supported Tools

Tuick supports all tools with errorformat built-in patterns. Run errorformat -list to see available formats:

ansible-lint, bandit, black, brakeman, buf, cargo-check, clippy, dotenv-linter, dotnet, erb-lint, eslint, eslint-compact, fasterer, flake8, go-consistent, golangci-lint, golint, gosec, govet, haml-lint, hlint, isort, luacheck, misspell, msbuild, mypy, pep8, phpstan, protolint, psalm, puppet-lint, pydocstyle, reek, remark-lint, rubocop, sbt, sbt-scalastyle, scalac, scalastyle, slim-lint, sorbet, standardjs, standardrb, staticcheck, stylelint, tsc, tslint, typos, yamllint.

Additionally, tuick provides enhanced support for:

• mypy — Enhanced multi-line patterns with column support.
• ruff — Enhanced patterns for both concise and full formats.
• pytest — Custom multi-line patterns for test failures.

Build systems (stub support — groups output into info blocks):

• make, just, cmake, ninja

Additional tools can be supported by:

• Using -f/--format-name to reference any errorformat built-in format
• Providing custom patterns via -p/--pattern option
• Extending tool_registry.py for custom patterns

Check the [vim errorformat documentation] for the pattern syntax.

License

Tuick is released under the MIT License. See LICENSE for details.