>_
worktale university

university / course 01

Beginner 5 lessons · ~30 min

Foundations.

Install the CLI, initialize your first repo, tour the TUI dashboard, and write your first digest. By the end of this course you'll have Worktale tracking a real project and producing a shareable end-of-day summary.

Lesson 1.1

Why Worktale exists.

WHAT YOU'LL LEARN

The problem Worktale solves, so the rest of the course makes sense. No setup yet — just the shape of the thing.

Most serious software gets built inside private repos. Under NDAs. Behind firewalls. At clients. At employers. When the engagement ends or you move on, the record doesn't come with you — and six months later you can't reconstruct what you shipped.

The same thing is happening with your AI spend. You're burning real money on Claude, GPT, and Copilot, split across four different agents and however many projects, and the only record is your monthly invoice.

Worktale is a personal, local-first record of what you built, what it cost, and why. It stays on your machine and moves with you when you change jobs.

What it actually is

  • A CLI tool you install once with npm install -g worktale
  • A local SQLite database at ~/.worktale/data.db that only you can read
  • Silent git hooks that snapshot every commit's metadata (never contents)
  • A TUI dashboard (worktale) and an optional desktop app
  • An opt-in cloud profile at worktale.dev/{username} you control

What it is not

  • Not a surveillance tool. It has no team view. No manager can see your data.
  • Not a time tracker. It doesn't watch keystrokes or track mouse movement.
  • Not SaaS. Everything runs locally. The cloud is optional and opt-in.
  • Not reading your source. Only git metadata: commit hashes, messages, diff stats.

KEY INSIGHT

Your Worktale data lives at ~/.worktale/data.db — outside any repo, on your own machine. If you lose access to a company's repos, your record of what you shipped stays with you. That's the whole point.

Lesson 1.2

Install the CLI.

WHAT YOU'LL LEARN

How to install Worktale globally via npm, verify it works, and what gets created on first run.

Prerequisites

  • Node.js 18 or later (node -v to check)
  • git installed and on your PATH
  • Any terminal: bash, zsh, PowerShell, Git Bash on Windows — all fine

Install

~ — install worktale

$ npm install -g worktale

added 142 packages in 3s

$ worktale --version

1.5.0

That's it. No account. No API key. No first-run wizard. The tool is idle until you run a command.

Where did it install?

A globally-installed npm package puts the worktale binary somewhere on your PATH:

  • macOS / Linux: typically /usr/local/bin/worktale or ~/.nvm/versions/node/.../bin/worktale
  • Windows: %APPDATA%\npm\worktale.cmd

Worktale itself creates nothing until you run worktale init. The database at ~/.worktale/data.db does not exist until your first repo is tracked.

Updating later

$ npm install -g worktale@latest

Your data is preserved across updates. The database schema is migrated in-place on first launch of the new version.

GOTCHA

If you see EACCES permission denied on macOS or Linux, your npm global prefix is in a root-owned directory. Rather than sudo npm install, fix the prefix: npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH. Cleaner and safer.

Lesson 1.3

Initialize a repo with worktale init.

WHAT YOU'LL LEARN

How worktale init imports your git history and installs the silent post-commit hook that captures future commits automatically.

Run it

cd into any git repository you've been working on — even one with ten years of history — and run:

~/my-project — initialize

$ worktale init

⚡ Initializing Worktale for my-project...

  Scanning git history...

  Imported 1,847 commits across 3 branches

  Installed post-commit hook

  Database at ~/.worktale/data.db

✓ Ready. Run worktale to open the dashboard.

What init actually did

  1. Registered the repo. Added a row to the repos table with the absolute path, name, and first-seen timestamp.
  2. Imported git history. Ran git log under the hood, inserted one row per commit into the commits table with sha, author, message, timestamp, lines added/removed, files changed, branch, and any tags.
  3. Built daily summaries. Grouped commits by day into the daily_summaries table so the TUI's Overview and History tabs load instantly.
  4. Installed the hook. Dropped a post-commit hook into .git/hooks/ that calls worktale silently after every commit. The hook is 3 lines; you can read it.

What it didn't do

  • It did not read any file contents. Only git log metadata.
  • It did not make a network request.
  • It did not modify any tracked files in your repo.
  • It did not touch .gitignore or create any files your teammates would see.

If you don't want hooks

Prefer import-only? Use worktale batch instead of init. It imports your history exactly the same way but skips the hook step. You can add the hook later with worktale hook install, or remove it with worktale hook uninstall. Hooks are fully optional; the import is the core.

GOTCHA

If the repo's git user email doesn't match yours, Worktale imports every committer's work. On shared repos, set your email filter: worktale config set git.userEmailOverride "you@example.com". Future imports will only count commits authored by that email.

Lesson 1.4

Tour the TUI dashboard.

WHAT YOU'LL LEARN

How to open the dashboard, what each of the four tabs shows, and how to navigate with the keyboard.

Opening it

From inside any initialized repo, just type:

$ worktale # or: worktale dash

The four tabs

Press 1, 2, 3, or 4 to jump between tabs, or Tab to cycle.

[1] Overview

Today at a glance. Commits, lines added/removed, files touched. Weekly activity bar chart. Current + best streak. Last 5 commits with messages and timestamps.

[2] Daily Log

One day per screen. Arrow keys ← / → to move between days. Per-day stats, your notes (press e to edit), AI-session summaries, and the full commit list.

[3] History

The long view. GitHub-style 52-week heatmap, all-time stats, top modules (biggest folders by churn), and milestones (from git tags).

[4] AI Sessions

Last 30 days of AI activity. KPIs (sessions, cost, tokens, active duration), cost/day and tokens/day sparklines, and breakdowns by agent, model, provider, and top tools.

Keyboard summary

1 2 3 4jump to tab
Tabcycle tab forward
d / Dgenerate today's digest and exit
p / Ppublish today's digest to the cloud and exit
eedit notes (on Daily Log tab)
← →previous / next day (on Daily Log tab)
qquit

KEY INSIGHT

The TUI is safe to leave running. It doesn't poll or fetch — it reads from SQLite on each tab change. Close your laptop, come back, data is still current. New commits made while the TUI is open require a restart to appear (this is intentional; we may add auto-refresh later).

Lesson 1.5

Write your first digest.

WHAT YOU'LL LEARN

How to run worktale digest, what the output looks like, and what to do with it.

Run it

From any initialized repo, at the end of your workday:

~/my-saas-project — end of day

$ worktale digest

⚡ WORKTALE DIGEST — Friday, April 17, 2026

─────────────────────────────────────────────

What I built

• Added rate limiting to /api/upload endpoint

• Fixed race condition in job queue worker

• Refactored payment webhook into a module

• Added regression tests for idempotency key check

Stats

• 7 commits, +1,204 / -389 lines, 23 files

Areas

• src/api/ (38%), src/workers/ (24%), tests/ (21%)

Save this digest? (Y/n) Y

✓ Digest saved!

What just happened

  • Today's commits were turned into a bulleted “What I built” list using the commit messages as source material.
  • Stats came straight from the commits and daily_summaries tables.
  • Areas ranks folders by total changes for the day (using the file_activity table).
  • Saving wrote the digest to the daily_summaries.ai_draft column for the current date. You can edit it later in the Daily Log tab or republish it.

What to do with it

  • Paste into a status-update Slack message, client email, or retro doc.
  • Save it as the seed for your weekly review — tomorrow you'll add to it.
  • Run worktale digest --format json to get structured output for scripting (covered in Course 04).
  • If you have Worktale Cloud connected, press p in the TUI to publish it to your profile (covered in Course 06).

Template vs Ollama mode

The digest above is template mode: deterministic, offline, no AI involved. It's the default and it's enough for most days.

If you've got Ollama running locally, you can opt into AI-narrated digests with worktale config set ai.provider ollama and the digest becomes more prosaic. We cover Ollama setup in Course 04 Lesson 4.4.

KEY INSIGHT

A digest is not a replacement for good commit messages. A digest is what rescues days where you didn't write great messages — by giving you stats, areas, and a second chance to narrate. Commit messages still matter. The digest just makes them visible after the fact.

GOTCHA

If you run worktale digest and nothing shows, you probably have zero commits today. That's fine — Worktale won't fabricate work you didn't do. Run worktale status to confirm the day's state.