logcurse — annotate your logs

# 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

edit

Comment Editor

Open $EDITOR to add comments to specific line ranges.

view

TUI Viewer

Dual-pane terminal UI with file and comment panes side-by-side.

web

Web Viewer

Interactive browser UI with chunked loading for large files.

# Installation

recommended

Binary Release

Download a prebuilt binary from GitHub Releases. Pick the right archive for your OS and architecture, extract, and add to your PATH.

shell

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

Browse all releases →

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.

download

logcurse-setup-amd64.exe

Download from Releases →

Go Install

If you have Go 1.24+ installed:

shell

go install github.com/wasson-ece/logcurse@latest

Build from Source

shell

git clone https://github.com/wasson-ece/logcurse.git
cd logcurse
go build -v

Docker

Run the web viewer in a minimal container — no Go installation needed. Mount your log directory and pass a file or directory path.

docker run

# single file
docker run -p 8080:8080 \
  -v /path/to/logs:/data \
  ghcr.io/wasson-ece/logcurse /data/server.log

# browse a directory
docker run -p 8080:8080 \
  -v /path/to/logs:/data \
  ghcr.io/wasson-ece/logcurse /data/

docker-compose.yml

services:
  logcurse:
    image: ghcr.io/wasson-ece/logcurse
    ports:
      - "8080:8080"
    volumes:
      - ./logs:/data
    restart: unless-stopped
    command: /data/

# 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.

shell

# comment on lines 140-160 of server.log
logcurse -n '140,160p' server.log

# comment on a single line
logcurse -n 42 server.log

This 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.

shell

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. Pass a single file or a directory.

shell

# serve a single file
logcurse --serve server.log

# serve a directory of log files
logcurse --serve ./logs/

# use a custom port
logcurse --serve --port 9090 server.log

# enable read-write mode
logcurse --serve --rw server.log

The web viewer fetches 200-line chunks on demand with 2-chunk buffering, so it handles large files efficiently. Click a line number to select it, or shift+click to select a range — the URL updates to #L10 or #L10-L25 for shareable links that highlight and scroll to the selected lines.

In directory mode, logcurse shows a file listing with annotation status. Annotated files are sorted to the top with comment counts. Click any file to open it in the viewer.

The --rw flag enables creating, editing, and deleting comments directly in the browser. Select lines and click “Add Comment” to write a new comment, or use the [EDIT] and [DEL] controls on existing comments. Your author name is prompted on first use and stored in the browser for future comment IDs.

# Comment Format

Comments live in a YAML sidecar file next to the source: server.log → server.log.yml. The source file is never touched.

server.log.yml

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.

IDs are sequential from the CLI (c1, c2), author-based from the web (chip1, chip2), or timestamp-based when anonymous (w1741193400).

Ranges are 1-indexed and inclusive.

content_hash is a SHA-256 of the referenced lines at comment time. If the source changes, the comment is flagged as drifted.

Timestamps use RFC 3339 format.

# Agent Usage

logcurse publishes machine-readable documentation for LLMs and AI coding agents. When instructing an LLM to use logcurse, include something like this in your prompt:

prompt snippet

logcurse is a CLI tool for annotating log files with line-range comments
stored in YAML sidecar files. For full usage and API documentation, read
https://logcurse.wasson-ece.dev/llms.txt

The documentation is also available at the /.well-known/llms.txt path.