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 operationexport.<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
- 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
- Tracking schedule adherence — Use
check and compare to record whether you completed blocks as planned, then stats to see completion patterns over time
- 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
- Batch-creating weekly plans — Use
batch to log entire week schedules at once, then preview to review upcoming blocks before each day starts
- Generating productivity reports — Use
report to log daily summaries, then export csv to pull structured data for time-tracking spreadsheets or dashboards
Examples
# 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
1---2name: timeblock3description: Plan your day hour-by-hour with intentional time blocking. Use when blocking sessions, checking plans, analyzing allocation, generating agendas.4---5
6# Timeblock
7
8Timeblock 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.
9
10## Commands
11
12Run `scripts/script.sh <command> [args]` to use.
13
14### Core Operations
15
16| Command | Description |
17|---------|-------------|
18| `run <input>` | Log a run entry (e.g. execute a time block, start a session) |
19| `check <input>` | Log a check entry (e.g. verify block completion, review schedule) |
20| `convert <input>` | Log a convert entry (e.g. convert time formats, transform schedules) |
21| `analyze <input>` | Log an analyze entry (e.g. analyze time allocation, productivity patterns) |
22| `generate <input>` | Log a generate entry (e.g. generate daily schedules, weekly plans) |
23| `preview <input>` | Log a preview entry (e.g. preview tomorrow's blocks, upcoming week) |
24| `batch <input>` | Log a batch entry (e.g. batch-create time blocks for a week) |
25| `compare <input>` | Log a compare entry (e.g. compare planned vs actual time usage) |
26| `export <input>` | Log an export entry (e.g. export schedule to calendar, share plan) |
27| `config <input>` | Log a config entry (e.g. set block durations, default categories) |
28| `status <input>` | Log a status entry (e.g. current block status, schedule progress) |
29| `report <input>` | Log a report entry (e.g. daily/weekly time reports, utilization summaries) |
30
31Each command without arguments shows the 20 most recent entries for that category.
32
33### Utility Commands
34
35| Command | Description |
36|---------|-------------|
37| `stats` | Summary statistics across all log categories with entry counts and disk usage |
38| `export <fmt>` | Export all data in `json`, `csv`, or `txt` format |
39| `search <term>` | Search across all log files for a keyword (case-insensitive) |
40| `recent` | Show the 20 most recent entries from the global activity history |
41| `status` | Health check — version, data directory, total entries, disk usage, last activity |
42| `help` | Show full usage information |
43| `version` | Show version string (`timeblock v2.0.0`) |
44
45## Data Storage
46
47All data is persisted locally under `~/.local/share/timeblock/`:
48
49- **`<command>.log`** — One log file per command (e.g. `run.log`, `check.log`, `analyze.log`)
50- **`history.log`** — Global activity log with timestamps for every operation
51- **`export.<fmt>`** — Generated export files (json/csv/txt)
52
53Each 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.
54
55## Requirements
56
57- **Bash** 4.0+ with `set -euo pipefail`
58- Standard Unix utilities: `date`, `wc`, `du`, `grep`, `tail`, `cat`, `sed`, `basename`
59- No external dependencies or packages required
60- No API keys or accounts needed
61
62## When to Use
63
641. **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
652. **Tracking schedule adherence** — Use `check` and `compare` to record whether you completed blocks as planned, then `stats` to see completion patterns over time
663. **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
674. **Batch-creating weekly plans** — Use `batch` to log entire week schedules at once, then `preview` to review upcoming blocks before each day starts
685. **Generating productivity reports** — Use `report` to log daily summaries, then `export csv` to pull structured data for time-tracking spreadsheets or dashboards
69
70## Examples
71
72```bash
73# Log a time block session
74timeblock run "09:00-10:30 Deep work on project Alpha"
75
76# Generate a daily schedule
77timeblock generate "Monday: 09:00 deep work, 10:30 standup, 11:00 code review, 14:00 planning"
78
79# Check schedule completion
80timeblock check "Morning blocks completed: 3/4, missed 10:30 standup"
81
82# Compare planned vs actual
83timeblock compare "Planned 4h deep work, actual 2.5h — meetings overran by 1.5h"
84
85# Search for all deep work entries
86timeblock search "deep work"
87
88# Export everything to JSON
89timeblock export json
90
91# View overall statistics
92timeblock stats
93```
94
95---
96
97Powered by BytesAgain | bytesagain.com | hello@bytesagain.com
bytesagain