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` | Show all available commands |

| `bookshelf version` | Print version (v2.0.0) |

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

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

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 | hello@bytesagain.com*