>_
worktale university

university / course 07

Expert 7 lessons · ~70 min

Mastery.

The patterns that emerge when you've been running Worktale for months. Real workflows for freelancers, NDA work, performance reviews, and the edge cases nobody tells you about.

Lesson 7.1

NDA-safe workflow.

WHAT YOU'LL LEARN

How to use Worktale on NDA'd work without violating the agreement, and how to share outputs safely.

What Worktale captures

Commit metadata only:

  • SHA, author email, timestamp, branch name, tag names
  • Commit message (the text you wrote)
  • Lines added/removed, files changed count, names of changed files
  • AI session cost/tokens/tools — but not the agent's transcript content

What Worktale does not capture

  • File contents, diffs, or snippets
  • Secrets, env vars, or config values
  • The agent's conversation transcript
  • Any data from remote git hosts

Safe-to-share outputs

  • Digest output — uses commit messages you wrote. Review before sharing; if you wrote secrets into a commit message, they'll be in the digest. You'd have the same problem with a git log paste.
  • Stats (worktale status) — counts only. Always safe.
  • AI session stats — models and costs. Always safe (no transcript content).

Riskier

  • Notes you wrote yourself — may contain sensitive detail. Review before sharing.
  • File name lists — the top-modules view may reveal internal structure (e.g. src/billing/stripe/enterprise-overrides). Consider repo-slug anonymization if you publish.

Repo slug for anonymization

When publishing to Worktale Cloud, each repo has a public slug. Default = repo name. You can override:

$ worktale repos rename acme-proprietary-thing "Client Work"

The public profile will now show “Client Work” instead of the real repo name.

Lesson 7.2

Multi-project patterns.

WHAT YOU'LL LEARN

Strategies for working across 5, 10, 20+ repos without losing the thread.

Bulk onboard everything once

$ worktale batch ~/code --auto --since 6m --install-hooks

One command gets every repo under ~/code into the database with hooks installed, limited to the last 6 months of history.

Cross-repo day view

The TUI shows one repo at a time. To see all your activity for today across all repos:

$ worktale status --all-repos

Today (2026-04-17)

  acme-portal: 3 commits · +421

  my-saas: 4 commits · +783

  side-lib: 1 commit · +42

One digest per project vs one rollup

Two patterns:

  • Per-project — run worktale digest from each repo. Publish separately. Client-specific retention. Best for billed consulting work.
  • Rollup — worktale standup --days 1 --all-repos. Single summary combining every repo. Best for "what did I do today" personal journaling.

Lesson 7.3

Freelance invoicing.

WHAT YOU'LL LEARN

Turn Worktale data into line items for client invoices, with AI cost pass-through.

The pattern

  1. Export your month for the client's repo as JSON.
  2. Extract: total active time (sum of session durations), AI cost for that repo, top modules touched.
  3. Attach the CSV as a substantiation doc.

# In the client's repo directory

$ worktale log --days 30 --format csv > invoice-apr.csv

$ worktale session list --days 30 --format csv > ai-apr.csv

# Get the month's AI total for pass-through

$ worktale session stats --days 30 --format json | jq '.total_cost'

47.83

Invoice line item template

Engineering services — April 2026

32h at $175/hr ...................... $5,600.00

AI tooling pass-through (Claude + GPT) ... $47.83

Total ........................................ $5,647.83

Detailed breakdown: invoice-apr.csv, ai-apr.csv

KEY INSIGHT

Clients love seeing AI cost called out. It signals: you're using the tools efficiently, you're transparent about expenses, and they're not being surprised later with a "who ran up our API bill?" conversation. Worktale makes this a one-line change to your monthly invoice.

Lesson 7.4

Performance review prep.

WHAT YOU'LL LEARN

Walk into a review with exact dates, counts, and context instead of a half-remembered list of features.

The six-month digest

$ worktale digest --since 2026-01-01 --format markdown > h1-review.md

This compiles everything — commit counts, big features, modules touched, AI-session totals — into a markdown doc you can edit into your review narrative.

The three-paragraph rescue

Can't remember March? Don't fake it:

$ worktale log --since 2026-03-01 --until 2026-03-31 --format markdown

Every commit in March with its message. Scan, pick the big ones, rewrite into prose. Takes 15 minutes; produces specific, accurate review material.

Themes over time

Run worktale, open History tab, look at top modules. The module you spent 30% of your year in is your theme. Lead your self-review with it.

Lesson 7.5

Weekly standup automation.

WHAT YOU'LL LEARN

Schedule a Monday 9am Slack post with last week's recap so you never again ask “what did I do last week?”

Two options:

1. Cron + Slack webhook (local, no Pro tier needed)

# ~/bin/weekly-standup.sh

#!/bin/bash

TEXT=$(worktale standup --days 7 --format slack)

curl -X POST -H 'Content-type: application/json' \

  -d "{\"text\": \"$TEXT\"}" \

  "$SLACK_WEBHOOK_URL"

# crontab -e, add:

0 9 * * 1 /home/you/bin/weekly-standup.sh

2. Worktale Cloud Pro

On Pro, the cloud can schedule and send standups for you. Set your Slack webhook and cadence from worktale.dev/settings/standups. No cron. No script maintenance.

Lesson 7.6

Data portability and export.

WHAT YOU'LL LEARN

How to back up, migrate, or leave Worktale entirely. Your data is always yours.

Back up your entire history

The whole database is one SQLite file:

$ cp ~/.worktale/data.db ~/backups/worktale-$(date +%Y%m%d).db

Put that on Dropbox, Syncthing, an encrypted USB stick — whatever you trust. It's SQLite; any SQLite tool can open it.

Export to JSON/CSV

$ worktale export --format json > worktale-export.json

$ worktale export --format csv --dir ~/worktale-csv/

Migrating between machines

  1. On the old machine: cp ~/.worktale/data.db /tmp/data.db.
  2. Transfer data.db + config.json to the new machine.
  3. Install Worktale on the new machine, don't run init yet.
  4. Drop the files into ~/.worktale/.
  5. Worktale picks them up on next run. Repos at their old absolute paths won't resolve; use worktale repos move to fix each one.

Leaving Worktale

# Uninstall hooks from every tracked repo

$ worktale hook uninstall --all

# Remove the CLI

$ npm uninstall -g worktale

# Remove data (your choice — keeping it is fine)

$ rm -rf ~/.worktale/

Lesson 7.7

Troubleshooting.

WHAT YOU'LL LEARN

The failure modes we see most often and how to fix them.

"Commits aren't being captured"

  • Check worktale hook status in the repo. If missing, worktale hook install.
  • Check git.userEmailOverride config — if set, only commits by that email count.
  • Check that worktale is on the PATH visible to your shell when git runs the hook. Some IDE terminals use a different PATH than your login shell.

"AI sessions aren't being captured"

  • Verify the plugin is installed: for Claude Code, /plugin list; for Codex/Copilot, confirm the watcher is running.
  • Check ls ~/.claude/projects/ / ~/.codex/sessions/ / ~/.copilot/session-state/ — the agent must actually be writing transcripts to disk.
  • Run worktale session list --days 1. If empty, the plugin's SessionEnd callback didn't fire; restart the agent and try a short session.

"Digest is empty"

  • Run worktale status. If commits = 0, the day has no content to digest.
  • If commits > 0 but digest is still empty, the timezone may be off — Worktale is looking at today in your timezone setting. Commits made at 11pm local might be tomorrow in UTC.
  • If Ollama mode hangs: Ollama isn't reachable at ai.ollamaUrl. Fall back with worktale config set ai.provider template.

"Cloud login hangs"

The CLI polls the cloud until you confirm the code. If you don't confirm within 15 minutes it times out. Ctrl+C and try again; the code is one-time use and new on every login attempt.

"Desktop app won't launch on Windows"

Most likely: WebView2 runtime missing. Windows 11 has it by default; on Windows 10 you may need to install it. Error messages will usually point you there.

KEY INSIGHT

If you hit a reproducible bug, capture it with worktale diagnose — a command that prints your OS, CLI version, config (secrets redacted), DB schema version, and last 10 operations. Paste that into a GitHub issue and we can usually fix within a day.