>_
worktale university

university / course 02

Intermediate 5 lessons · ~40 min

Daily Practice.

Worktale rewards consistency. This course is about turning Foundations into a daily habit — a rhythm of commits, notes, and digests that builds a record you'll actually use.

Lesson 2.1

The daily loop.

WHAT YOU'LL LEARN

The three moves that make Worktale pay off: commit, note, digest. In that order. Every day.

Worktale's payoff comes from compounding small inputs. Nothing in the tool is heavyweight: no long-form journal, no required form fields, no tagging taxonomy. Just three small actions, repeated.

Step 1 — Commit (as you already do)

Write your commit messages slightly better than you would without Worktale. Not drastically better — just readable. fix stuff becomes fix: webhook race on idempotent payment retry. The digest later uses these messages verbatim.

The post-commit hook captures the metadata automatically. You don't have to think about Worktale at commit time.

Step 2 — Note (1-2 times/day, <30s each)

Between commits, when you figure something out or make a decision, drop a note:

$ worktale note "switched from app-level locking to DB unique constraint; faster under load"

✓ Noted.

The note is appended to today's user_notes. It shows up in worktale digest and in the TUI Daily Log tab. Notes are the "why" layer — commits are "what", notes are "why you chose this".

Step 3 — Digest (once/day, at end of day)

When you're closing the laptop: worktale digest. Confirm Y to save. Done. Takes 5 seconds.

Or set up a nudge (Lesson 2.4) so Worktale reminds you at 5pm.

KEY INSIGHT

Missing a digest is fine. Your commits are still captured, and you can generate a digest for any past date with worktale digest --date 2026-04-15. The loop is forgiving; consistency builds the asset, but missing a day doesn't break it.

Lesson 2.2

Reading stats.

WHAT YOU'LL LEARN

How to read the Overview and History tabs without getting confused by vanity metrics.

The useful numbers

  • Current streak — consecutive days with at least one commit. This is the only “gamified” metric and we use it as a gentle prompt, not a goal. Breaking a streak because you took a weekend off is healthy.
  • Commits per day — useful for spotting rhythm. A week of 0-commit days inside a “busy” sprint usually means you're stuck on something; the digest will remind you to surface it.
  • Lines added/removed — directionally useful. Don't chase the number. Refactors that remove lines are often more valuable than ones that add.
  • Top modules — where you spent the week. Surprisingly honest. The module you didn't realize you'd been working on shows up here.

The 52-week heatmap

The History tab renders a GitHub-style heatmap of your commit activity, but it's computed from your local data — it includes private repos GitHub's public heatmap would never show. This is often the first place you see the total arc of your work.

Per-repo vs all-repo stats

By default, the TUI shows stats for the repo you opened it from. To see all repos, use worktale repos:

$ worktale repos

acme-portal     847 commits   last: 2h ago

my-saas-project   1,204 commits   last: today

side-experiment   38 commits   last: 6d ago

GOTCHA

If “top modules” looks weird (e.g. node_modules showing up), it's because a historical commit actually touched those paths. Worktale isn't filtering; it's showing the truth. You can exclude paths at the git level with .gitattributes linguist-generated or handle it at review time.

Lesson 2.3

Writing notes that matter.

WHAT YOU'LL LEARN

How to use worktale note so that six months later, past-you is a useful coworker.

Three ways to add a note

1. CLI (fastest)

$ worktale note "picked option B because redis lookups are ~5x cheaper than DB for this"

2. TUI (edit longer notes)

Open the TUI with worktale, press 2 for Daily Log, then e to edit. This drops you into your $EDITOR (defaults to nano or vim).

3. AI agent (automatic)

With a Worktale plugin installed, two layers of automation kick in:

  • SessionEnd hook (Claude Code, Codex, Copilot plugins): the hook itself parses the transcript on session end and records tokens/cost/model/tools automatically — no agent involvement.
  • Per-commit narrative: the agent's skill tells it to run worktale note after each commit. For rules-based integrations without hooks (Cursor, Cline, Windsurf), the one-shot worktale session add --write-note records a per-commit session row and appends the narrative to the daily log in a single call.

Covered in detail in Course 03.

What to actually write

The commit message tells you what changed. Your note should tell you why this approach. Useful patterns:

  • Decision + alternative: “went with Redis lock over DB-level; tradeoff is cache miss storm on restart but we have a warmer.”
  • Surprise: “the webhook race was masked by a second bug in retry logic; fixing the retry exposed it.”
  • Dead end: “tried lock-free ring buffer, scrapped, spinlock was enough at current volume.”
  • External context: “client rejected the idea of v2 API; sticking with v1 + feature flags.”

What NOT to write

  • Secrets, tokens, API keys (the database is local but backups exist).
  • Things that belong in code comments (“this is O(n log n)” — put it in the code).
  • Full design docs. Notes are context, not artifacts.

KEY INSIGHT

The best test for a note: if you read it six months from now, alongside the day's commits and AI session tools-used list, could you reconstruct why you did what you did? If yes, good note. If not, be more specific.

Lesson 2.4

Nudges.

WHAT YOU'LL LEARN

How to set up a shell-prompt reminder that nudges you to digest when you haven't yet.

A nudge is a one-liner Worktale adds to your .bashrc or .zshrc that checks, once per shell load after your configured “nudge time”, whether you've committed today but haven't run worktale digest. If both are true, Worktale auto-generates and saves a template digest for each pending repo and prints a one-line confirmation. You can review or edit later with worktale digest.

Want reminders only, no auto-save? worktale config set autoDigestOnNudge false.

Install

$ worktale nudge --install

✓ Added nudge to ~/.bashrc and ~/.zshrc

Reload your shell or run `source ~/.bashrc`

Configure

# Default nudge fires at 17:00 (5pm)

$ worktale config set nudgeTime "18:30"

# Timezone defaults to auto; override if needed

$ worktale config set timezone "America/New_York"

What it looks like

# You open a new terminal after 5pm

⚡ Worktale — Auto-saved digest for acme-portal (815 lines shipped today).

Review or edit: worktale digest

$

Remove

$ worktale nudge --uninstall

GOTCHA

The nudge runs worktale nudge --check as a background shell call. It's fast (one SQLite query) but if your .bashrc also does other heavy work, the total shell-open time can creep. If that happens, remove the nudge and rely on the desktop app's dock icon instead (Course 05).

Lesson 2.5

CLI vs Desktop: when to switch.

WHAT YOU'LL LEARN

The CLI and desktop app read the same SQLite database. Which one to reach for, when.

Reach for the CLI when

  • You're already in a terminal
  • You want to run a one-off command (status, note, digest)
  • You want scripted output (--format json)
  • You're on a remote server / SSH session

Reach for the desktop app when

  • You want to browse multiple days / repos visually
  • You're editing a long digest draft (CodeMirror is nicer than vim in-terminal)
  • You want to publish to the cloud with a click
  • You want interactive charts for AI cost

Both read/write the same local database. You can use both; they stay in sync. The desktop app is covered in detail in Course 05; this lesson is just the "when to use which" heuristic.

KEY INSIGHT

A good default is: terminal for writing (commits, notes, digests), desktop app for reading (browsing history, comparing weeks, publishing). The TUI is fine for both, but once you're looking at data — especially across multiple repos — the desktop app wins on pure ergonomics.