worklog

worklog is a small Rust CLI for tracking terminal-based research or work sessions.

It is a thin layer over:

• tmux
• Git
• local log files
• append-only notes and tags

The goal is straightforward: start a session, work as usual, add notes or tags when needed, then export a clean artifact that is readable by a person or ready to paste into an LLM.

Status

This repository implements the v1 workflow:

• start
• stop
• note
• tag
• status
• list
• export
• attach
• remote pull

It stores session data under an XDG-style local data directory and shells out to existing tools instead of reimplementing them.

Requirements

• Rust stable
• git
• tmux for terminal logging and attach
• ssh and scp for remote pull

Without tmux, worklog still works for session metadata, notes, tags, Git snapshots, and export. Use --no-tmux when tmux is unavailable or intentionally disabled.

Build

cargo build

Test

cargo test

Quick Start

Start a session:

worklog start mech-interp

Add notes and tags during the session:

worklog note "attention collapse after layer 8" --tag experiment --tag failure
worklog tag failure --kind experiment --value run_12
worklog status

Stop and export:

worklog stop
worklog export --latest --include-raw

How It Works

When a session starts, worklog:

• creates a readable session ID
• creates a per-session directory
• records host, user, shell, cwd, and Git context
• starts tmux pane logging unless --no-tmux is used
• marks the session as active

During a session, worklog note and worklog tag append NDJSON entries to the session directory.

When a session stops, worklog:

• turns off tmux pane logging
• records a final Git snapshot
• marks the session closed

When a session is exported, worklog:

• merges notes, tags, terminal logs, and Git context
• strips ANSI escape sequences
• extracts highlights from the merged timeline
• writes Markdown and JSON artifacts under merged/

Data Layout

By default, session data is stored under the platform-local data directory for worklog. On macOS and Linux this is typically similar to:

~/.local/share/worklog/
  state/
    active_session.json
  sessions/
    <session-id>/
      meta.json
      index.json
      local/
        tmux/
        shell/
        notes/
        git/
        system/
      remotes/
      merged/

For testing or isolation, you can override the base data directory:

WORKLOG_DATA_DIR=/tmp/worklog-demo worklog start sandbox --no-tmux

Tmux Logging

worklog uses tmux pipe-pane for terminal capture. In tmux-enabled sessions, pane output is piped through a small shell loop that prefixes each completed line with a wall-clock timestamp before appending it to the pane log.

Relevant tmux references:

• pipe-pane: https://man7.org/linux/man-pages/man1/tmux.1.html
• capture-pane: https://man7.org/linux/man-pages/man1/tmux.1.html
• control mode notifications: https://man7.org/linux/man-pages/man1/tmux.1.html

This improves exported timelines significantly with very little moving parts, but it is still not a perfect event recorder:

• timestamps are assigned when a full line is observed by the logger
• partial lines and redraw-heavy terminal UIs are not represented precisely
• full-screen applications and progress bars remain noisy by nature

That tradeoff is intentional in v1.

Documentation

• Usage Guide

Limitations

• tmux integration is limited to the current pane or the primary pane of a created session
• remote support is pull-only in v1
• shell history capture is best-effort
• terminal timestamps are line-oriented, not byte-accurate
• export filtering is heuristic by design

Development Notes

The implementation favors:

• synchronous code
• human-readable artifacts
• atomic metadata writes
• append-only note and tag logs
• small modules over framework-heavy abstractions