Overview

The useful part of a commit message is often trapped in Git.

The issue tracker gets a final link—if someone remembers—but not the sequence of decisions, fixes, and tradeoffs that produced it. Reconstructing that narrative at the end of a week is slow and usually incomplete.

Posting updates automatically sounds simple until the first commit is matched to the wrong work item.

The system therefore automates collection and drafting, but not publication.

Architecture

git push
  -> pre-push hook reads pushed commit range
  -> append commit records to local queue
  -> background reviewer detects queued work
  -> match commits to active work items
  -> draft one update per work item
  -> human edits / approves / skips
  -> post approved updates

The hook and the reviewer are separate processes. This boundary is the most important design decision in the project.

The Push Must Never Wait

A network call inside pre-push turns an issue-tracker outage into a source-control outage.

The hook does only local work:

  1. Read Git’s pre-push input.
  2. Resolve the commits entering the remote.
  3. Record their subject, body, changed files, repository, and timestamp.
  4. Append one JSON line per commit to a user-local queue.

If enqueueing fails, the hook reports the problem and still exits successfully. Worklog automation is useful; pushing code is essential.

The append-only queue also survives restarts and keeps hook execution independent from UI startup.

Matching Commits to Work

The reviewer loads active work items and scores each commit against them using signals such as:

  • explicit work-item keys in branch names or commit text
  • overlap between changed paths and component labels
  • terminology shared by the commit and work-item description
  • repository-level configuration

A deterministic engine always exists. When a supported local coding-agent CLI is available, the application can ask it to rerank candidates and improve the narrative.

The LLM is an enhancement, not a dependency. If it times out, is missing, or returns unusable output, the deterministic result remains available.

Drafting at the Right Level

Posting one comment per commit creates noise. The reviewer groups related commits by work item and drafts a single progress narrative:

  • what changed
  • why it changed
  • notable validation performed
  • any limitation or follow-up visible from the commit set

Raw commit messages remain visible beside the draft. The generated prose is never the only record a reviewer sees.

Already-posted commit hashes are tracked, so rerunning review does not duplicate earlier updates.

Approval Is Part of the Product

The desktop interface groups drafts by work item. Each group can be edited, approved, or skipped independently.

There is no “approve everything silently” background mode. That is deliberate.

The matching engine may be confident and still be wrong. Commit messages may also contain internal phrasing that should not be copied into a broader audience. Per-comment review makes both problems visible at the last responsible moment.

The tray application handles queue notifications and can start with the operating system. Credentials are stored in the OS keychain rather than the application’s configuration file.

Local-First Failure Handling

The workflow treats external systems as optional until posting:

  • Push succeeds even if the assistant is broken.
  • Queue records survive application restarts.
  • Dry-run mode previews without mutating either the queue or the issue tracker.
  • Doctor diagnostics explain whether deterministic or LLM-enhanced mode is active.
  • Posting failures leave the relevant queue entries available for retry.

This makes failure recoverable without hiding it.

What Worked

  • Moving all network and LLM work out of the Git hook.
  • Keeping a deterministic matcher beneath the optional LLM.
  • Grouping commits into work-item narratives instead of posting commit spam.
  • Requiring approval at the unit that will actually be published.
  • Storing secrets in the platform keychain.

What Was Hard

  • Correctly interpreting branch updates, new branches, and force-push ranges.
  • Deduplicating commits across repeated pushes and review sessions.
  • Matching work without over-trusting a key mentioned in unrelated text.
  • Building a cross-platform background application without making Git integration platform-specific.

Takeaway

The best automation around human communication does not remove the human.

It removes the reconstruction work and leaves the judgment where it belongs.