Timeblock#

Timeblock v2.0.0 — a utility toolkit for logging, tracking, and managing time-blocking operations from the command line. All data is stored locally in flat log files with timestamps, making it easy to review history, export records, and search across entries.

Commands#

Run scripts/script.sh <command> [args] to use.

Core Operations#

CommandDescriptionrun <input>Log a run entry (e.g. execute a time block, start a session)check <input>Log a check entry (e.g. verify block completion, review schedule)convert <input>Log a convert entry (e.g. convert time formats, transform schedules)analyze <input>Log an analyze entry (e.g. analyze time allocation, productivity patterns)generate <input>Log a generate entry (e.g. generate daily schedules, weekly plans)preview <input>Log a preview entry (e.g. preview tomorrow's blocks, upcoming week)batch <input>Log a batch entry (e.g. batch-create time blocks for a week)compare <input>Log a compare entry (e.g. compare planned vs actual time usage)export <input>Log an export entry (e.g. export schedule to calendar, share plan)config <input>Log a config entry (e.g. set block durations, default categories)status <input>Log a status entry (e.g. current block status, schedule progress)report <input>Log a report entry (e.g. daily/weekly time reports, utilization summaries)

Each command without arguments shows the 20 most recent entries for that category.

Utility Commands#

CommandDescriptionstatsSummary statistics across all log categories with entry counts and disk usageexport <fmt>Export all data in json, csv, or txt formatsearch <term>Search across all log files for a keyword (case-insensitive)recentShow the 20 most recent entries from the global activity historystatusHealth check — version, data directory, total entries, disk usage, last activityhelpShow full usage informationversionShow version string ( timeblock v2.0.0)

Data Storage#

All data is persisted locally under ~/.local/share/timeblock/:

• <command>.log — One log file per command (e.g. run.log, check.log, analyze.log)
• history.log — Global activity log with timestamps for every operation
• export.<fmt> — Generated export files (json/csv/txt)

Each entry is stored as YYYY-MM-DD HH:MM|<input> (pipe-delimited). No external services, no API keys, no network calls — everything stays on your machine.

Requirements#

• Bash 4.0+ with set -euo pipefail
• Standard Unix utilities: date, wc, du, grep, tail, cat, sed, basename
• No external dependencies or packages required
• No API keys or accounts needed

When to Use#

1. Planning your day — Use generate and run to create and log time blocks for each hour, building a structured daily schedule you can search and review later
2. Tracking schedule adherence — Use check and compare to record whether you completed blocks as planned, then stats to see completion patterns over time
3. Analyzing time allocation — Use analyze to log how you actually spent your time, then search to find patterns across categories like deep work, meetings, or breaks
4. Batch-creating weekly plans — Use batch to log entire week schedules at once, then preview to review upcoming blocks before each day starts
5. Generating productivity reports — Use report to log daily summaries, then export csv to pull structured data for time-tracking spreadsheets or dashboards

Examples#

bash

# Log a time block session
timeblock run "09:00-10:30 Deep work on project Alpha"

# Generate a daily schedule
timeblock generate "Monday: 09:00 deep work, 10:30 standup, 11:00 code review, 14:00 planning"

# Check schedule completion
timeblock check "Morning blocks completed: 3/4, missed 10:30 standup"

# Compare planned vs actual
timeblock compare "Planned 4h deep work, actual 2.5h — meetings overran by 1.5h"

# Search for all deep work entries
timeblock search "deep work"

# Export everything to JSON
timeblock export json

# View overall statistics
timeblock stats

---

Powered by BytesAgain | bytesagain.com | hello@bytesagain.com