Dev Journal CLI

A focused CLI tool for engineering journals, weekly summaries, and reflection across Git history, local journal files, and hand-written notes.

Why

If you ship software regularly, capturing what changed, what broke, and what you learned often gets lost in commit noise and chat threads. Dev Journal CLI turns existing artifacts into structured summaries with filters, so weekly reviews and retrospectives take minutes instead of hours.

Features

• Git-backed journals: Extract entries from tag-style commit messages (#entry, [entry], entry:).
• File-backed journals: Parse lightweight markers from .md, .txt, and .journal files.
• Configurable roots: point the tool at any journal directories or notes files via .journal.toml.
• Filtering: restrict output by --since, --author, and --path.
• Human-readable output: markdown-style summaries that are easy to scan and share.

Installation

pip install -e .

Setup

Initialize a journal config in your repo or notes folder:

dev-journal init .

This creates .journal.toml with your current directory listed as a watched path.

Usage

# Analyze entries since a date
dev-journal analyze --since 2026-07-01

# Summarize entries by author and date
dev-journal summarize --since 2026-07-01 --author "Omar Carter"

# Use a custom config file
dev-journal analyze --config /path/to/.journal.toml

Markers you can use anywhere

Supported entry markers:

• #entry: shipped login flow
• [entry] fixed critical auth bug
• entry: reviewed PR #42
• * #entry cleaned up logs

Everything after the marker is treated as the entry message.

Example output

# Dev Journal Summary

2026-07-12

ENTRIES (2)
- [/notes/sprint.md] (Omar Carter): shipped onboarding flow
- [dev-journal] (Omar Carter): moved to pytest fixtures

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest

Roadmap

• richer aggregation by label/topic
• CSV and JSON report formats
• shell completions for bash, zsh, and fish
• journal entry templates

License

MIT