claudewatch

claudewatch is a zero-argument CLI that watches a Git worktree and renders syntax-highlighted unified diffs in the terminal.

Install

bun install

Run

bun run dev

Inside a Git repository:

claudewatch

Modes

• Default watch mode (claudewatch):
  • Interactive, Vim-style scrolling in an alternate screen.
  • Clean exit (q) restores your previous terminal contents.
  • Tracks latest changed files at the bottom (recently changed files move down).
• Stream mode (--stream):
  • Appends snapshots to stdout with separators.
  • No in-app viewport controls (uses normal terminal scrollback).
• Once mode (--once):
  • Renders one snapshot and exits.
  • Uses less when output exceeds terminal height (unless --no-pager).
• Demo mode (--demo):
  • Uses a built-in fake diff snapshot (no real repo changes required).
  • Works with --once or watch mode.

Watch keybindings (non-stream)

• j / k: scroll down / up by one line
• Ctrl-d / Ctrl-u: half-page down / up
• g / G: jump to top / bottom
• q: quit cleanly

Common commands

claudewatch --once
claudewatch --interval 500
claudewatch --max-files 30 --max-lines 1500
claudewatch --theme nord --lang auto
claudewatch --color never
claudewatch --truecolor true
claudewatch --stream
claudewatch --live      # alias for non-stream watch mode
claudewatch --demo --once
claudewatch --ignore "**/*.snap" --ignore "dist/**"

Options

--help
--version
--list-themes
--interval MS
--stream
--live, --refresh
--once
--demo
--ignore PATTERN                (repeatable, comma-separated accepted)
--max-files N
--max-lines N
--max-width N
--padding auto|false
--color auto|always|never
--no-color
--truecolor auto|true|false
--nerd-fonts auto|true|false
--theme NAME
--lang auto|LANG
--no-pager

Ignore behavior

• Ignored paths are excluded from:
  • status counts/lists
  • rendered diff files
• Matching uses Bun glob matching.
• Built-in default ignore globs:
  • **/bun.lock
  • **/bun.lockb
  • **/package-lock.json
  • **/pnpm-lock.yaml
  • **/yarn.lock
  • **/pnpm-workspace.yaml
  • **/Cargo.lock
  • **/Gemfile.lock
  • **/poetry.lock
  • **/uv.lock
• Binary files are ignored in rendered output.

Diff behavior

• Uses git unified diffs (--patch) and parses them via vendored Pierre parser code.
• Adaptive context and hunk merging:
  • fewer changed files => larger context
  • more changed files => tighter context
  • nearby hunks are merged via --inter-hunk-context
• Syntax highlighting uses Shiki (with chunked highlighting to avoid large-file fallback whitening).

Example config.toml

Create ~/.config/claudewatch/config.toml:

interval = 700
theme = "nord"
stream = false
max_files = 40
max_lines = 2500
max_width = 0
padding = "auto"
truecolor = "auto"
nerd_fonts = "auto"
no_pager = false

# Additional ignore globs (appended to built-in defaults)
ignore = [
  "**/*.snap",
  "dist/**",
  "coverage/**",
  "**/.DS_Store",
]

Development

bun run test
bun run tc
bun run lint:fix
bun run build