WorkLog

Engineering Context Manager — Git stores code. WorkLog stores engineering context.

Links:

• 📖 Architecture Design Manual
• 💾 Advanced Installation Guide

WorkLog is a local-first, offline-first command-line tool designed to capture the why, the blockers, the decisions, and the meaningful progress of your daily engineering work. It helps you keep track of what you are doing so you never have to ask yourself, "What was I doing yesterday?"

Technical Stack

• Language: TypeScript
• Runtime: Node.js (v20+ recommended)
• CLI Framework: Commander.js
• Database: SQLite (via better-sqlite3 native drivers)
• Validation: Zod
• Logging: Pino (saved to .worklog/worklog.log)

Installation

WorkLog is configured to install and run locally.

1. Ensure you have pnpm and Node.js installed.
2. Clone this repository.
3. Install dependencies:

   pnpm install

4. Build the application:

   pnpm build

5. Link the command globally (optional):

   pnpm link --global

Now you can invoke WorkLog with:

worklog --help

Core Philosophy

• Local Scope: Every project initializes its own database in a .worklog/ directory (just like .git in Git).
• Fast Interactive Prompts: If you omit arguments, worklog add automatically prompts you through choices.
• Machine Readable: Add the --json flag to print structured data for IDE plugins or scripts.
• Dedicated Exporters: Supports Markdown, CSV, and JSON outputs for clean copy-pasting.

CLI Usage & Reference

1. Initialize a Project (init / i)

Initializes a new context tracker in the current directory.

worklog init
# or
worklog i

Output:

Initialized empty WorkLog repository in /path/to/project/.worklog/

2. Create a Work Unit (add / a)

Create an entry representing a Feature, Bug, Refactor, Spike, Research, or Decision.

Non-Interactive Mode:

worklog add --title "Setup authentication endpoint" --type Feature --status "In Progress" --module Auth --tags backend,security
# or
worklog a -t "Fix connection leak" --type Bug --status Completed

Interactive Mode: Simply run worklog add (or worklog a) without flags in a TTY terminal, and it will guide you:

? Title: › Setup auth
? Type: › Feature
? Status: › Planned
? Description (optional): › Initial JWT setup
? Module (optional): › auth
? Tags (comma-separated, optional): › backend,security
? Next Step (optional): › write unit tests

3. List Work Units (list / ls)

Lists recent entries.

worklog list
# or
worklog ls

Output:

ID   Title                      Type    Status      Module Priority Created At
#2   Fix connection leak        Bug     Completed   -      -        Jul 26
#1   Setup authentication...    Feature In Progress Auth   -        Jul 26

Options:

• -l, --limit <count>: Limit output (default is 20).
• -s, --status <status>: Filter list by status.
• -t, --type <type>: Filter list by type.
• --json: Output machine-readable JSON array.

4. Show Details (show / sh)

Displays detailed card information for a single Work Unit.

worklog show 1
# or
worklog sh 1

5. Multi-criteria Search (search / s)

Perform case-insensitive text search querying the SQLite FTS5 virtual table, combined with category filters.

# Search text
worklog search "connection leak"

# Search by tags and module
worklog search --tag backend --module auth

# Combined keyword and status query
worklog search "setup" --status "In Progress"

Options:

• --tag <tag>: Filter results by tag.
• --module <module>: Filter results by module.
• --status <status>: Filter results by status.
• --type <type>: Filter results by type.
• --json: Return structured matches as JSON.

6. Today's Progress (today / t)

Display work units created or updated today since midnight.

worklog today
# or
worklog t

7. Weekly Summary (week / w)

Provides a weekly summary of progress grouped by engineering categories (features completed, bugs fixed, decisions made, blockers encountered, research performed) and prints status/type distribution counts.

worklog week
# or
worklog w

8. Project Dashboard (dashboard / db)

Displays a focused overview answering three core developer questions:

1. What am I currently working on? (In Progress items)
2. What needs attention? (Blocked or Planned items)
3. What changed recently? (Recently updated items)

worklog dashboard
# or
worklog db

9. Resume Last Work (continue / co)

Resumes the most recently touched unfinished task (Planned, In Progress, Blocked), shifting its status to In Progress and updating its time marker. If multiple unfinished units exist, it prompts you to select one (sorted by update date, most recent first).

worklog continue
# or
worklog co

10. Analytical Insights (stats / st)

Shows high-level metrics (totals, category distributions, and daily activity logs over the past 7 days) in clean text bars.

worklog stats
# or
worklog st

11. Export Context (export / ex)

Exports log entries to Markdown, CSV, or JSON. Supports writing directly to files or stdout piping.

# Export everything to markdown file
worklog export --format markdown --output docs/summary.md

# Pipe CSV data
worklog export --format csv > data_export.csv

# Export a single work unit
worklog export --id 1 --format markdown

Options:

• -f, --format <format>: Output format (markdown / md, csv, json). Defaults to markdown.
• -o, --output <file>: Writes data to a physical file.
• --id <id>: Exports only the unit matching this ID.

Error Codes

The CLI will exit with:

• 0 on successful operation execution.
• 1 on user/validation errors (e.g. invalid arguments, missing fields, not in a repository).
• 2 on system/database failures (e.g. SQLite corruption, unhandled crashes).