englog 0.1.0

Minimalist CLI for engineering workdays. Capture time tracking, todos, TILs, and notes as timestamped markdown.

englog

Minimalist CLI for engineering workdays. Capture time tracking, todos, TILs, and notes as timestamped markdown. Optimized for speed, not processing.

Philosophy

• Fast capture: Minimal typing, no prompts, no friction
• Markdown-first: Human-readable, editor-agnostic, greppable
• Processing elsewhere: Files designed for external tools/editors
• Daily ephemeral storage: Entries captured during the day, processed end-of-day into permanent systems

Installation

# Clone the repository
git clone https://github.com/jmlrt/englog.git
cd englog

# Install with uv
uv sync

# Or install globally
uv tool install -e .

Setup

# Set up englog directory (optional, defaults to ~/englog)
export ENGLOG_DIR=~/Documents/englog

# Set up editor (required for --edit commands)
export EDITOR=vim  # or nano, code --wait, etc.

# Add to your shell profile for persistence
echo 'export ENGLOG_DIR=~/Documents/englog' >> ~/.zshrc
echo 'export EDITOR=vim' >> ~/.zshrc

# Initialize
englog init

# Optional: create a short alias
echo 'alias el="englog"' >> ~/.zshrc

Quick Start

# Start tracking time
englog time start "Review PRs @code-review"

# Add a todo
englog todo add "Fix auth bug @backend @urgent"

# Capture a learning
englog til "Python dataclasses support frozen=True @python"

# Quick note
englog note "New staging URL: https://staging.example.com @reference"

# Check status
englog status

# Open today's file in editor
englog edit

Commands

Time Tracking

englog time start "task description @tag1 @tag2"   # Start tracking time
englog time start 3                                # Restart timer by number
englog time pause                                  # Pause current timer
englog time resume                                 # Resume paused timer
englog time stop                                   # Stop and log current timer
englog time list                                   # List all timers from today

Features:

• Auto-stops current timer when starting a new one
• Restart by number creates a new entry (preserves timeline)
• Shows total time at bottom of list

Example session:

$ englog time start "Fix auth bug @backend"
Started: Fix auth bug

$ englog time start "Review security PR @code-review"
Stopped: Fix auth bug (1h 23m), Started: Review security PR

$ englog time list
1. Fix auth bug @backend (1h 23m)
2. Review security PR @code-review (45m) [ACTIVE]

Total: 2h 8m

Todo Management

englog todo add "task description @tag1 @tag2"     # Add to todo list
englog todo doing "task description"               # Move to doing by description
englog todo doing 2                                # Move to doing by number
englog todo done "task description"                # Mark as completed
englog todo done 3                                 # Mark as completed by number
englog todo list                                   # List all todos

Features:

• Match by description (case-insensitive) or by number
• Numbers only assigned to Todo and Doing sections
• Direct to done: englog todo done "Quick fix" adds directly if no match

Example session:

$ englog todo add "Fix auth bug @backend"
Added: Fix auth bug

$ englog todo add "Update docs @documentation"
Added: Update docs

$ englog todo list
Todo:
  1. Fix auth bug @backend
  2. Update docs @documentation

$ englog todo doing 1
Doing: Fix auth bug

$ englog todo done 1
Done: Fix auth bug

TIL (Today I Learned)

englog til "quick learning note @tag1 @tag2"       # Single-line TIL
englog til --edit @tag1 @tag2                      # Multi-line TIL (opens $EDITOR)

Capture learnings, techniques, patterns, "aha moments" - knowledge worth remembering.

Notes

englog note "quick note @tag1 @tag2"               # Single-line note
englog note --edit @tag1 @tag2                     # Multi-line note (opens $EDITOR)

Capture important context, references, team updates, URLs, API endpoints.

Scratch

englog scratch "temporary capture @tag1"           # Single-line scratch
englog scratch --edit @tag1                        # Multi-line scratch (opens $EDITOR)

Ultra-ephemeral captures - error messages, debug output, things you need RIGHT NOW.

Utility Commands

englog init                                        # Initialize englog directory
englog status                                      # Show overview
englog edit                                        # Open today's file in $EDITOR
englog version                                     # Show version
englog --help                                      # Show help

Tags

Tags use @tagname format and work consistently across all commands:

englog time start "Fix auth @api-refactor @backend @security"
englog todo add "Review PR @api-refactor @code-review"
englog til "OAuth handles token refresh @api-refactor @security"
englog note "API endpoint: https://api.example.com @api @reference"

Valid tag characters: a-z, A-Z, 0-9, -, _

File Format

All data stored in daily markdown files at $ENGLOG_DIR/YYYY-MM-DD.md:

# 2025-01-15

## Time

### 09:23 - 10:46 | Fix auth endpoints | @api-refactor @backend
- Duration: 1h 23m

### 10:46 - [ACTIVE] | Review security PR | @code-review
- Duration: 45m (running)

## Todo

### Todo
- [14:20] Update documentation @docs @api

### Doing
- [09:45] Fix authentication bug @backend @security

### Done
- [11:30] Deploy staging environment @devops

## TIL

### 10:15 | @python @performance
Python's walrus operator can simplify list comprehensions.

## Notes

### 09:15 | @api @reference
API endpoint: https://api.example.com/v2/users

## Scratch

### 11:00 | @error @debugging
Error output from failed deployment...

End-of-Day Workflow

1. During the day: Rapid capture with englog commands
2. End of day: Review with englog status and englog edit
3. Process entries: Extract to permanent systems (task tracker, knowledge base)
4. Archive or delete: Daily files are ephemeral by design

Configuration

Variable	Description	Default
ENGLOG_DIR	Directory for daily files	~/englog
EDITOR	Editor for --edit and englog edit	(required)

License

MIT