# About
logcurse is a command-line tool for annotating log files and text files with line-range comments. Comments are stored in YAML sidecar files alongside the original — your source file is never modified.
Comments include a SHA-256 hash of the referenced lines, so logcurse detects when the source file changes and flags comments as drifted without silently altering the YAML.
Written in Go. Open source.
View on GitHub →Three modes
Open $EDITOR to add comments to specific line ranges.
Dual-pane terminal UI with file and comment panes side-by-side.
Interactive browser UI with chunked loading for large files.
# Installation
Binary Release
Download a prebuilt binary from GitHub Releases. Pick the right archive for your OS and architecture, extract, and add to your PATH.
# download & extract (example: macOS arm64)
curl -LO https://github.com/wasson-ece/logcurse/releases/latest/download/logcurse_darwin_arm64.tar.gz
tar xzf logcurse_darwin_arm64.tar.gz
sudo mv logcurse /usr/local/bin/| OS | Arch | Archive |
|---|---|---|
| macOS | arm64 | logcurse_darwin_arm64.tar.gz |
| macOS | amd64 | logcurse_darwin_amd64.tar.gz |
| Linux | arm64 | logcurse_linux_arm64.tar.gz |
| Linux | amd64 | logcurse_linux_amd64.tar.gz |
| Windows | amd64 | logcurse_windows_amd64.zip |
Windows Installer
Download and run the setup executable. It installs logcurse to Program Files, adds it to your PATH, and registers an uninstaller in Add/Remove Programs.
logcurse-setup-amd64.exeGo Install
If you have Go 1.24+ installed:
go install github.com/wasson-ece/logcurse@latestBuild from Source
git clone https://github.com/wasson-ece/logcurse.git
cd logcurse
go build -vDocker
Run the web viewer in a minimal container — no Go installation needed. Mount your log directory and pass the file path.
docker run -p 8080:8080 \
-v /path/to/logs:/data \
ghcr.io/wasson-ece/logcurse /data/server.log# Usage
Adding Comments
Use the -n flag with a sed-style range to open your editor and write a comment on specific lines. Lines are 1-indexed and inclusive. A bare number targets a single line.
# comment on lines 140-160 of server.log
logcurse -n '140,160p' server.log
# comment on a single line
logcurse -n 42 server.logThis opens $VISUAL or $EDITOR (falling back to nano on macOS/Linux, notepad on Windows). The comment is saved to server.log.yml.
TUI Viewer default
Run logcurse with just a filename to open the dual-pane terminal viewer.
logcurse server.log| Key | Action |
|---|---|
| Tab | Switch focus between file and comment panes |
| n / p | Jump to next / previous comment |
| ↑k ↓j | Scroll up / down |
| PgUp / PgDn | Page scroll |
| Ctrl+U / Ctrl+D | Half-page scroll |
| Homeg EndG | Jump to top / bottom |
| s | Toggle vertical / horizontal split |
| ? | Toggle help bar |
| q / Ctrl+C | Quit |
Web Viewer
Serve an interactive browser UI with the --serve flag. Defaults to port 8080.
logcurse --serve server.log
# use a custom port
logcurse --serve --port 9090 server.logThe web viewer fetches 200-line chunks on demand with 2-chunk buffering, so it handles large files efficiently.
# Comment Format
Comments live in a YAML sidecar file next to the source: server.log → server.log.yml. The source file is never touched.
version: 1
source_file: server.log
comments:
- id: "c1"
range:
start: 140
end: 160
content_hash: "sha256:a3f2b8..."
author: ""
created: "2026-03-04T10:30:00Z"
updated: "2026-03-04T10:30:00Z"
body: |
This block shows the auth timeout
that caused the cascade failure.c1, c2, c3…