bookshelf

name	Bookshelf
description	Track reading progress, rate finished books, and manage your library. Use when logging books, reviewing reading stats, or planning reading goals.
version	2.0.0
author	BytesAgain
homepage	https://bytesagain.com
source	https://github.com/bytesagain/ai-skills
tags	["books","reading","library","list","tracker","literature","personal","knowledge"]
categories	["Personal Management","Productivity","Education"]

Bookshelf

A personal productivity toolkit for managing books, reading plans, progress tracking, reviews, and reading habits — all from the command line with timestamped local logging, tagging, archiving, and weekly review workflows.

Commands

Command	Description
bookshelf add <input>	Add a book or item to your shelf. Without args, shows recent add entries
bookshelf plan <input>	Record a reading plan or goal. Without args, shows recent plans
bookshelf track <input>	Track reading progress. Without args, shows recent tracking entries
bookshelf review <input>	Log a book review or assessment. Without args, shows recent reviews
bookshelf streak <input>	Record a reading streak or consistency milestone. Without args, shows recent streaks
bookshelf remind <input>	Set a reading reminder note. Without args, shows recent reminders
bookshelf prioritize <input>	Record a prioritization decision. Without args, shows recent priorities
bookshelf archive <input>	Archive a finished or dropped book. Without args, shows recent archives
bookshelf tag <input>	Tag or categorize a book. Without args, shows recent tag entries
bookshelf timeline <input>	Record a reading timeline entry or milestone. Without args, shows recent timeline entries
bookshelf report <input>	Generate and log a reading report. Without args, shows recent reports
bookshelf weekly-review <input>	Record a weekly reading review summary. Without args, shows recent weekly reviews
bookshelf stats	Show summary statistics across all entry types
bookshelf search <term>	Search across all log entries for a keyword
bookshelf recent	Show the 20 most recent activity entries
bookshelf status	Health check — version, data dir, entry count, disk usage, last activity
bookshelf export <fmt>	Export all data in json, csv, or txt format
bookshelf help

Each command (add, plan, track, etc.) works the same way:

• With arguments: saves the entry with a timestamp to its dedicated .log file and records it in activity history
• Without arguments: displays the 20 most recent entries from that command's log

Data Storage

All data is stored locally in plain-text log files:

~/.local/share/bookshelf/
├── add.log             # Added books and items
├── plan.log            # Reading plans and goals
├── track.log           # Progress tracking entries
├── review.log          # Book reviews and assessments
├── streak.log          # Reading streak records
├── remind.log          # Reminder notes
├── prioritize.log      # Prioritization decisions
├── archive.log         # Archived / finished books
├── tag.log             # Tag and genre categorization
├── timeline.log        # Reading timeline milestones
├── report.log          # Reading reports and summaries
├── weekly-review.log   # Weekly reading review summaries
└── history.log         # Unified activity log with timestamps

Each entry is stored as YYYY-MM-DD HH:MM|<value> for easy parsing and export.

Requirements

• Bash 4.0+ (uses set -euo pipefail)
• Standard UNIX utilities: date, wc, du, grep, head, tail, cat
• No external dependencies or API keys required
• Runs without internet — all data stays on your machine

When to Use

1. Reading list management — Use add to build your to-read list, prioritize what to pick up next, and archive books once finished or dropped
2. Reading habit tracking — Track daily pages or chapters with track, maintain reading streaks with streak, and review progress in weekly-review
3. Book review journaling — After finishing a book, use review to log your thoughts, ratings, and key takeaways for future reference
4. Annual reading goals — Set yearly targets with plan, track progress with stats, and generate periodic reports with report to stay on pace
5. Genre and tag organization — Use tag to categorize books by genre, topic, or mood, then search to find the right book for any occasion

Examples

Add books and start reading

# Add books to your shelf
bookshelf add "Atomic Habits by James Clear — recommended by Kelly"
bookshelf add "Deep Work by Cal Newport — productivity classic"
bookshelf add "Project Hail Mary by Andy Weir — sci-fi for fun"

# Tag them by genre
bookshelf tag "Atomic Habits: #self-help #habits #productivity"
bookshelf tag "Deep Work: #productivity #focus #career"
bookshelf tag "Project Hail Mary: #sci-fi #fiction #adventure"

# Prioritize what to read next
bookshelf prioritize "Atomic Habits — start this week, short chapters"

Track reading progress

# Track daily reading
bookshelf track "Atomic Habits — finished chapters 1-3, 45 pages"
bookshelf track "Atomic Habits — chapters 4-6, identity-based habits section"

# Record streaks
bookshelf streak "day 7 of reading at least 20 pages daily"
bookshelf streak "day 30 — one month streak! 🎉"

# Set a reminder
bookshelf remind "return library copy of Deep Work by April 20"

# Record a timeline milestone
bookshelf timeline "2024-04-01: started Atomic Habits reading challenge"

Review, report, and archive

# Write a book review
bookshelf review "Atomic Habits — 5/5. Best takeaway: habit stacking. Changed my morning routine."

# Weekly reading review
bookshelf weekly-review "Week 15: finished Atomic Habits (5/5), started Deep Work. Read 180 pages total."

# Generate a monthly report
bookshelf report "April: 2 books finished, 1 in progress. 620 pages read. On track for 24-book goal."

# Set reading plans
bookshelf plan "Q2 goal: finish 6 books — 2 non-fiction, 2 sci-fi, 2 technical"

# Archive finished books
bookshelf archive "Atomic Habits — completed 2024-04-10, review saved"

# Check overall stats
bookshelf stats
bookshelf recent

Search and export

# Search for a book or topic
bookshelf search "productivity"

# Export entire library as JSON
bookshelf export json

# Export as CSV for spreadsheet tracking
bookshelf export csv

# Health check
bookshelf status

Output

All commands print confirmation to stdout. Data is persisted in ~/.local/share/bookshelf/. Use bookshelf stats for an overview, bookshelf search <term> to find specific entries, or bookshelf export <fmt> to extract all data as JSON, CSV, or plain text.

---

Powered by BytesAgain | bytesagain.com | [e-mail]