backlog-overview

Cross-project view for Backlog.md. One command tells you what's in progress, what's queued, and what's done — across every project under a folder. Reads the same markdown files Backlog.md already writes.

── Discounty-Expert  (in-progress 2 · to-do 5 · done 23)
   ● BACK-12   Add OAuth login
   ● BACK-18   Fix checkout bug

── Bayan  (in-progress 1 · to-do 2 · done 11)
   ● BACK-3    Migrate to Postgres

3 task(s) across 2 project(s) under /Users/you/Projects

One script. One command. No dependencies. Universal — works on any Mac, no Node, no Homebrew.

---

Why this exists

Backlog.md is a markdown-native task manager. It stores tasks as plain .md files inside each git repo, so each project is self-contained. That's a clean design — but if you work on many projects, there's no way to see "what am I in the middle of, everywhere?" without cd-ing into each repo.

This script fills that gap. It scans a root directory, finds every backlog/tasks/*.md file, parses the YAML frontmatter (just id, title, status), and groups the result by project.

That's it. It's a 200-line read-only viewer over files Backlog.md already manages.

---

Install

curl -fsSLo /tmp/bo.sh https://raw.githubusercontent.com/SMKeramati/backlog-overview/main/backlog-overview.sh \
  && chmod +x /tmp/bo.sh && /tmp/bo.sh --install && source ~/.zshrc

That copies the script to ~/.backlog-overview/backlog-overview.sh and adds two aliases to your ~/.zshrc:

• backlog-overview — the full name
• bo — short

Update later: re-run the same one-liner. --install overwrites in place; the aliases keep working.

---

Usage

bo                       # in-progress across ~/Projects (default)
bo --all                 # every status, every project
bo --status "To Do"      # filter to one status
bo --counts              # one line per project, no task titles
bo --root ~/work         # scan a different folder
bo --plain               # no colors (for pipes / grep / scripts)
bo --help                # full reference

Examples

# Morning glance — what was I doing yesterday?
bo

# Find a task by keyword across every project
bo --plain --all | grep -i oauth

# Just the counts, for a quick health check
bo --counts --all

---

How it works

1. Find. find <root> \( -path "*/backlog/tasks/*.md" -o -path "*/.backlog/tasks/*.md" \) -type f — covers both Backlog.md layouts (default backlog/ and the hidden .backlog/ variant).
2. Parse. A single awk pass over every matched file reads the YAML frontmatter between the two --- fences and extracts id, title, status. Quoted ('...' or "...") and unquoted forms both work.
3. Group. Sort by project, then status, then id. Print one block per project with a header that shows the per-status counts.

No state files. No daemon. No watching. Each run is a fresh scan — typically under 100 ms even on a folder with 50+ repos.

---

Universal compatibility

Concern	Handled
macOS Bash 3.2 (the default /bin/bash)	✅ No 4.x features. Shebang pinned to /bin/bash.
Apple Silicon (arm64) and Intel (x86_64)	✅ Architecture-independent.
No Node, no Homebrew	✅ Uses only find, awk, sed, sort, printf — all bundled with macOS.
Linux	✅ Same tools exist on every Linux distro.
Hidden .backlog/ layout	✅ Matched alongside the default backlog/.
Quoted YAML values (title: "Foo: bar")	✅ Quotes stripped.
Persian / Arabic / CJK titles	✅ Byte-clean — passes UTF-8 through untouched.

---

Commands

Command	What it does
bo	Scan ~/Projects, show in-progress tasks grouped by project.
bo --all	Show tasks in every status.
bo --status "<s>"	Filter to one status ("To Do", "In Progress", "Done", or any custom value).
bo --root <path>	Scan a different root folder.
bo --counts	Per-project header lines only, no task titles.
bo --plain	Disable colors. Auto-disabled when stdout is not a terminal.
bo --install	Copy the script to ~/.backlog-overview/ and add backlog-overview + bo aliases to ~/.zshrc. Idempotent.
bo --uninstall	Remove the aliases. Backs up ~/.zshrc first.
bo --help	Print full usage.

---

What this is not

• Not a task editor. Read-only. To create / edit / move tasks, use Backlog.md itself (backlog task create, backlog task edit, the MCP server, or backlog browser).
• Not a daemon. No background process, no file watcher. Run it when you want to look.
• Not a fork. This script never touches the backlog/ folder or the backlog CLI's state. It only reads task files.
• Not multi-format. It only understands Backlog.md's frontmatter shape. Other markdown task systems won't parse.

---

Caveats (the honest cost)

• Custom backlog-dir paths. Backlog.md lets you point the data folder anywhere via backlog.config.yml. This script only auto-detects the two default locations (backlog/ and .backlog/). If you set a custom path, the script won't see those tasks. (Fix on the roadmap; not hard — read the config — but adds dependencies.)
• No multi-line YAML titles. Titles with | or > block scalars aren't parsed. Inline quoted/unquoted titles work fine.
• Status values are case-sensitive. Backlog.md ships "To Do" / "In Progress" / "Done". If you customize them, pass the exact string to --status.

---

Uninstall

bo --uninstall                      # remove aliases (zshrc backup saved)
rm -rf ~/.backlog-overview          # remove the script copy

Your Backlog.md task files are never touched.

---

Contributing

PRs welcome. Especially:

• Support for backlog.config.yml custom paths.
• A --json output mode for scripting.
• Linux distro testing (should work — please report).
• A short-circuit bo <project-name> that jumps you into that repo (cd + backlog board).

---

License

MIT. See LICENSE.

---

Credits

• MrLesk/Backlog.md — the underlying task manager. This script is just a viewer over its files.
• Style and --install pattern adapted from SMKeramati/claude-rtl.