timelog-extract 0.2.11

Aggregate local work activity from Gemini, Claude, Cursor, OpenAI Codex IDE, Chrome, Mail, worklog, optional GitHub public activity, and optional Screen Time.

Gittan

Timelog Extract

Local time reports from how you actually work.

Aggregate IDE, browser, mail, and worklog signals—plus optional GitHub activity—into project hours and optional invoice PDFs.
Core reporting is local-first; there is no built-in cloud upload path.

---

Install

Requirements: Python 3.9+. You do not need a PyPI account to install—only maintainers need PyPI access to publish.
If the shell says command not found: pip, use python3 -m pip instead of a bare pip command (common on macOS).

Recommended: pipx (macOS / Linux — keeps gittan on your PATH)

pip install --user puts scripts under ~/Library/Python/…/bin (macOS), which is often not on PATH, so gittan can look “missing” until you edit shell config. pipx installs CLI tools into ~/.local/bin and is easier to get right:

brew install pipx
pipx ensurepath

Important: open a new terminal tab, or run source ~/.zshrc, so PATH picks up pipx ensurepath. Then:

pipx install timelog-extract
gittan -V

Alternative: pip install --user (PyPI)

python3 -m pip install --user timelog-extract

Add the user script directory to PATH (macOS example — version may differ):

export PATH="$HOME/Library/Python/3.9/bin:$PATH"

Put that line in ~/.zshrc (or run gittan doctor — it will hint if it detects this issue).

_{Until PyPI has the package for your environment, use from source below.}

More install options

Virtual environment

python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install timelog-extract

From source

git clone https://github.com/mbjorke/timelog-extract.git
cd timelog-extract
python3 -m pip install -e .

Verify:

gittan --help
gittan -V

Publishing checklist: docs/runbooks/versioning.md.

Get started

1. Health check — from a git repo that should have (or will have) a worklog:

   gittan doctor
   

   gittan doctor ends with the most useful next command to run for your current setup.
2. First-time setup — wizard for environment, optional global TIMELOG.md hooks, and timelog_projects.json:

   gittan setup              # default: one click, no prompts
   gittan setup --dry-run    # preview
   gittan setup --interactive
   

   gittan setup now closes with copyable next steps so the first real report is obvious.
3. First report — today’s activity:

   gittan report --today --source-summary
   

TIMELOG.md in the repository root (where you run the command) is the default worklog unless you pass --worklog or set a path in config. See Timelog vs config below.

---

Everyday commands

Goal	Command
Full report (prompts for range if you omit dates)	gittan report
Today / last week / custom range	gittan report --today · --last-week · --from 2026-04-01 --to 2026-04-30
Guided cleanup of uncategorized activity	gittan review --today --uncategorized
Quick hours overview	gittan status --today
Source mix / empty collectors	gittan sources (and docs/sources/sources-and-flags.md)
Edit projects JSON	gittan projects
Machine-wide commit → TIMELOG.md hooks	gittan setup-global-timelog

JSON or HTML export (quiet, script-friendly):

gittan report --today --format json
gittan report --from 2026-04-01 --to 2026-04-30 --format json --json-file out/truth.json --report-html out/report.html

Optional GitHub activity: set GITHUB_USER or --github-user; optional GITHUB_TOKEN for rate limits. Details: docs/sources/sources-and-flags.md.

---

What else is in the repo

• Cursor extension (companion, beta) — cursor-extension/README.md.
• Engine script (same API as the extension): python3 scripts/run_engine_report.py --today --pdf.

---

Timelog vs config

• TIMELOG.md — human-readable work journal; safe to treat as a diary.
• timelog_projects.json — machine config; back it up (e.g. under ~/.gittan/). Setup creates timestamped backups before replacing invalid JSON.

---

Troubleshooting

Issue	Where to look
command not found: gittan after install	Install via pipx (above), or add ~/Library/Python/…/bin and ~/.local/bin to PATH; run gittan doctor for copy-paste hints.
“0 events” / sources empty	docs/sources/sources-and-flags.md
Missing deps / editable install	python3 -m pip install -e . from clone
Invalid project config	gittan setup; backups named timelog_projects.backup-*.json
Paths / permissions	--worklog, browser DBs, Mail / Screen Time access
Global timelog automation	gittan setup-global-timelog, docs/runbooks/global-timelog-setup.md

---

Feedback

Questions, install friction, or “does this match your workflow?” — use GitHub Discussions (e.g. General or Q&A). For bugs or small reproducible issues, open an issue instead.

---

Documentation map

Vision, privacy, CLI flags, style, and release checklists live under docs/. Start with docs/product/vision-documents.md for an index (e.g. docs/sources/sources-and-flags.md, docs/security/privacy-security.md, docs/product/terminal-style-guide.md, docs/product/accuracy-plan.md, docs/runbooks/screen-time-gap-analysis.md, docs/runbooks/cli-first-v1-release-checklist.md).

---

Contributing · tests · license

• CONTRIBUTING.md — PR titles/descriptions in English; run tests before pushing.
• Maintainers (repo hygiene): issue templates, Discussions, Social preview in GitHub Settings; brand — canonical PNGs in docs/brand/, then scripts/build_brand_assets.sh -> root gittan-logo.png (site), favicon, README icon, og-image.png. See docs/brand/README.md, docs/ideas/opportunities.md.
• main is branch-protected — use a branch and PR; see BRANCH.md and docs/runbooks/ci.md.
• Tests: ./scripts/run_autotests.sh (also enforced in CI).
• License: GNU GPL-3.0-or-later — LICENSE. Changelog: CHANGELOG.md.