TimeBlock

# 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 | Command | Description | |---------|-------------| | `run <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 | Command | Description | |---------|-------------| | `stats` | Summary statistics across all log categories with entry counts and disk usage | | `export <fmt>` | Export all data in `json`, `csv`, or `txt` format | | `search <term>` | Search across all log files for a keyword (case-insensitive) | | `recent` | Show the 20 most recent entries from the global activity history | | `status` | Health check — version, data directory, total entries, disk usage, last activity | | `help` | Show full usage information | | `version` | Show 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